docs/manual/customize-rootfs.txt

   1 // -*- mode:doc; -*-
   2 // vim: set syntax=asciidoc:
   3
   4 [[rootfs-custom]]
   5 === Customizing the generated target filesystem
   6
   7 Besides changing the configuration through +make *config+,
   8 there are a few other ways to customize the resulting target filesystem.
   9
  10 The two recommended methods, which can co-exist, are root filesystem
  11 overlay(s) and post build script(s).
  12
  13 Root filesystem overlays (+BR2_ROOTFS_OVERLAY+)::
  14 +
  15 A filesystem overlay is a tree of files that is copied directly
  16   over the target filesystem after it has been built. To enable this
  17   feature, set config option +BR2_ROOTFS_OVERLAY+ (in the +System
  18   configuration+ menu) to the root of the overlay. You can even specify
  19   multiple overlays, space-separated. If you specify a relative path,
  20   it will be relative to the root of the Buildroot tree. Hidden
  21   directories of version control systems, like +.git+, +.svn+, +.hg+,
  22   etc., files called +.empty+ and files ending in +~+ are excluded from
  23   the copy.
  24 +
  25 As shown in xref:customize-dir-structure[], the recommended path for
  26   this overlay is +board/<company>/<boardname>/rootfs-overlay+.
  27
  28 Post-build scripts (+BR2_ROOTFS_POST_BUILD_SCRIPT+)::
  29 +
  30 Post-build scripts are shell scripts called 'after' Buildroot builds
  31   all the selected software, but 'before' the rootfs images are
  32   assembled. To enable this feature, specify a space-separated list of
  33   post-build scripts in config option +BR2_ROOTFS_POST_BUILD_SCRIPT+ (in
  34   the +System configuration+ menu). If you specify a relative path, it
  35   will be relative to the root of the Buildroot tree.
  36 +
  37 Using post-build scripts, you can remove or modify any file in your
  38   target filesystem. You should, however, use this feature with care.
  39   Whenever you find that a certain package generates wrong or unneeded
  40   files, you should fix that package rather than work around it with some
  41   post-build cleanup scripts.
  42 +
  43 As shown in xref:customize-dir-structure[], the recommended path for
  44   this script is +board/<company>/<boardname>/post_build.sh+.
  45 +
  46 The post-build scripts are run with the main Buildroot tree as current
  47   working directory. The path to the target filesystem is passed as the
  48   first argument to each script. If the config option
  49   +BR2_ROOTFS_POST_SCRIPT_ARGS+ is not empty, these arguments will be
  50   passed to the script too. All the scripts will be passed the exact
  51   same set of arguments, it is not possible to pass different sets of
  52   arguments to each script.
  53 +
  54 In addition, you may also use these environment variables:
  55
  56   - +BR2_CONFIG+: the path to the Buildroot .config file
  57   - +HOST_DIR+, +STAGING_DIR+, +TARGET_DIR+: see
  58     xref:generic-package-reference[]
  59   - +BUILD_DIR+: the directory where packages are extracted and built
  60   - +BINARIES_DIR+: the place where all binary files (aka images) are
  61     stored
  62   - +BASE_DIR+: the base output directory
  63
  64 Below two more methods of customizing the target filesystem are
  65 described, but they are not recommended.
  66
  67 Direct modification of the target filesystem::
  68 +
  69 For temporary modifications, you can modify the target filesystem
  70   directly and rebuild the image. The target filesystem is available
  71   under +output/target/+. After making your changes, run +make+ to
  72   rebuild the target filesystem image.
  73 +
  74 This method allows you to do anything to the target filesystem, but if
  75   you need to clean your Buildroot tree using +make clean+, these
  76   changes will be lost. Such cleaning is necessary in several cases,
  77   refer to xref:full-rebuild[] for details. This solution is therefore
  78   only useful for quick tests: _changes do not survive the +make clean+
  79   command_. Once you have validated your changes, you should make sure
  80   that they will persist after a +make clean+, using a root filesystem
  81   overlay or a post-build script.
  82
  83 Custom target skeleton (+BR2_ROOTFS_SKELETON_CUSTOM+)::
  84 +
  85 The root filesystem image is created from a target skeleton, on top of
  86   which all packages install their files. The skeleton is copied to the
  87   target directory +output/target+ before any package is built and
  88   installed. The default target skeleton provides the standard Unix
  89   filesystem layout and some basic init scripts and configuration files.
  90 +
  91 If the default skeleton (available under +system/skeleton+) does not
  92   match your needs, you would typically use a root filesystem overlay or
  93   post-build script to adapt it. However, if the default skeleton is
  94   entirely different than what you need, using a custom skeleton may be
  95   more suitable.
  96 +
  97 To enable this feature, enable config option
  98   +BR2_ROOTFS_SKELETON_CUSTOM+ and set +BR2_ROOTFS_SKELETON_CUSTOM_PATH+
  99   to the path of your custom skeleton. Both options are available in the
 100   +System configuration+ menu. If you specify a relative path, it will
 101   be relative to the root of the Buildroot tree.
 102 +
 103 This method is not recommended because it duplicates the entire
 104   skeleton, which prevents taking advantage of the fixes or improvements
 105   brought to the default skeleton in later Buildroot releases.
 106
 107 include::customize-device-permission-tables.txt[]