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 three 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 Post-fakeroot scripts (+BR2_ROOTFS_POST_FAKEROOT_SCRIPT+)::
 108 +
 109 When aggregating the final images, some parts of the process requires
 110   root rights: creating device nodes in `/dev`, setting permissions or
 111   ownership to files and directories... To avoid requiring actual root
 112   rights, Buildroot uses +fakeroot+ to simulate root rights. This is not
 113   a complete substitute for actually being root, but is enough for what
 114   Buildroot needs.
 115 +
 116 Post-fakeroot scripts are shell scripts that are called at the 'end' of
 117   the fakeroot phase, 'right before' the filesystem image generator is
 118   called. As such, they are called in the fakeroot context.
 119 +
 120 Post-fakeroot scripts can be useful in case you need to tweak the
 121   filesystem to do modifications that are usually only available to the
 122   root user.
 123 +
 124 .Note:
 125 It is recommended to use the existing mechanisms to set file permissions
 126   or create entries in `/dev` (see xref:customize-device-permission[]) or
 127   to create users (see xref:customize-users[])
 128 +
 129 .Note:
 130 The difference between post-build scripts (above) and fakeroot scripts,
 131   is that post-build scripts are not called in the fakeroot context.
 132 +
 133 .Note;
 134 Using `fakeroot` is not an absolute substitute for actually being root.
 135   `fakeroot` only ever fakes the file access rights and types (regular,
 136   block-or-char device...) and uid/gid; these are emulated in-memory.
 137
 138 include::customize-device-permission-tables.txt[]