docs/manual/customize-rootfs.adoc

// -*- mode:doc; -*-
// vim: set syntax=asciidoc:

[[rootfs-custom]]
=== Customizing the generated target filesystem

Besides changing the configuration through +make *config+,
there are a few other ways to customize the resulting target filesystem.

The two recommended methods, which can co-exist, are root filesystem
overlay(s) and post build script(s).

Root filesystem overlays (+BR2_ROOTFS_OVERLAY+)::
+
A filesystem overlay is a tree of files that is copied directly
  over the target filesystem after it has been built. To enable this
  feature, set config option +BR2_ROOTFS_OVERLAY+ (in the +System
  configuration+ menu) to the root of the overlay. You can even specify
  multiple overlays, space-separated. If you specify a relative path,
  it will be relative to the root of the Buildroot tree. Hidden
  directories of version control systems, like +.git+, +.svn+, +.hg+,
  etc., files called +.empty+ and files ending in +~+ are excluded from
  the copy.
+
When +BR2_ROOTFS_MERGED_USR+ is enabled, then the overlay must not
  contain the '/bin', '/lib' or '/sbin' directories, as Buildroot will
  create them as symbolic links to the relevant folders in '/usr'.  In
  such a situation, should the overlay have any programs or libraries,
  they should be placed in '/usr/bin', '/usr/sbin' and '/usr/lib'.
+
As shown in xref:customize-dir-structure[], the recommended path for
  this overlay is +board/<company>/<boardname>/rootfs-overlay+.

Post-build scripts (+BR2_ROOTFS_POST_BUILD_SCRIPT+)::
+
Post-build scripts are shell scripts called 'after' Buildroot builds
  all the selected software, but 'before' the rootfs images are
  assembled. To enable this feature, specify a space-separated list of
  post-build scripts in config option +BR2_ROOTFS_POST_BUILD_SCRIPT+ (in
  the +System configuration+ menu). If you specify a relative path, it
  will be relative to the root of the Buildroot tree.
+
Using post-build scripts, you can remove or modify any file in your
  target filesystem. You should, however, use this feature with care.
  Whenever you find that a certain package generates wrong or unneeded
  files, you should fix that package rather than work around it with some
  post-build cleanup scripts.
+
As shown in xref:customize-dir-structure[], the recommended path for
  this script is +board/<company>/<boardname>/post_build.sh+.
+
The post-build scripts are run with the main Buildroot tree as current
  working directory. The path to the target filesystem is passed as the
  first argument to each script. If the config option
  +BR2_ROOTFS_POST_SCRIPT_ARGS+ is not empty, these arguments will be
  passed to the script too. All the scripts will be passed the exact
  same set of arguments, it is not possible to pass different sets of
  arguments to each script.

  Note that the arguments from +BR2_ROOTFS_POST_SCRIPT_ARGS+ will also be
  passed to post-image and post-fakeroot scripts. If you want to use
  arguments that are only used for the post-build scripts you can use
  +BR2_ROOTFS_POST_BUILD_SCRIPT_ARGS+.

+
In addition, you may also use these environment variables:

  - +BR2_CONFIG+: the path to the Buildroot .config file
  - +CONFIG_DIR+: the directory containing the .config file, and
    therefore the top-level Buildroot Makefile to use (which is
    correct for both in-tree and out-of-tree builds)
  - +HOST_DIR+, +STAGING_DIR+, +TARGET_DIR+: see
    xref:generic-package-reference[]
  - +BUILD_DIR+: the directory where packages are extracted and built
  - +BINARIES_DIR+: the place where all binary files (aka images) are
    stored
  - +BASE_DIR+: the base output directory
  - +PARALLEL_JOBS+: the number of jobs to use when running parallel processes.

Below three more methods of customizing the target filesystem are
described, but they are not recommended.

Direct modification of the target filesystem::
+
For temporary modifications, you can modify the target filesystem
  directly and rebuild the image. The target filesystem is available
  under +output/target/+. After making your changes, run +make+ to
  rebuild the target filesystem image.
+
This method allows you to do anything to the target filesystem, but if
  you need to clean your Buildroot tree using +make clean+, these
  changes will be lost. Such cleaning is necessary in several cases,
  refer to xref:full-rebuild[] for details. This solution is therefore
  only useful for quick tests: _changes do not survive the +make clean+
  command_. Once you have validated your changes, you should make sure
  that they will persist after a +make clean+, using a root filesystem
  overlay or a post-build script.

Custom target skeleton (+BR2_ROOTFS_SKELETON_CUSTOM+)::
+
The root filesystem image is created from a target skeleton, on top of
  which all packages install their files. The skeleton is copied to the
  target directory +output/target+ before any package is built and
  installed. The default target skeleton provides the standard Unix
  filesystem layout and some basic init scripts and configuration files.
+
If the default skeleton (available under +system/skeleton+) does not
  match your needs, you would typically use a root filesystem overlay or
  post-build script to adapt it. However, if the default skeleton is
  entirely different than what you need, using a custom skeleton may be
  more suitable.
+
To enable this feature, enable config option
  +BR2_ROOTFS_SKELETON_CUSTOM+ and set +BR2_ROOTFS_SKELETON_CUSTOM_PATH+
  to the path of your custom skeleton. Both options are available in the
  +System configuration+ menu. If you specify a relative path, it will
  be relative to the root of the Buildroot tree.
+
Custom skeletons don't need to contain the '/bin', '/lib' or '/sbin'
  directories, since they are created automatically during the build.
  When +BR2_ROOTFS_MERGED_USR+ is enabled, then the custom skeleton must
  not contain the '/bin', '/lib' or '/sbin' directories, as Buildroot
  will create them as symbolic links to the relevant folders in '/usr'.
  In such a situation, should the skeleton have any programs or
  libraries, they should be placed in '/usr/bin', '/usr/sbin' and
  '/usr/lib'.
+
This method is not recommended because it duplicates the entire
  skeleton, which prevents taking advantage of the fixes or improvements
  brought to the default skeleton in later Buildroot releases.

Post-fakeroot scripts (+BR2_ROOTFS_POST_FAKEROOT_SCRIPT+)::
+
When aggregating the final images, some parts of the process requires
  root rights: creating device nodes in `/dev`, setting permissions or
  ownership to files and directories... To avoid requiring actual root
  rights, Buildroot uses +fakeroot+ to simulate root rights. This is not
  a complete substitute for actually being root, but is enough for what
  Buildroot needs.
+
Post-fakeroot scripts are shell scripts that are called at the 'end' of
  the fakeroot phase, 'right before' the filesystem image generator is
  called. As such, they are called in the fakeroot context.
+
Post-fakeroot scripts can be useful in case you need to tweak the
  filesystem to do modifications that are usually only available to the
  root user.
+
.Note:
It is recommended to use the existing mechanisms to set file permissions
  or create entries in `/dev` (see xref:customize-device-permission[]) or
  to create users (see xref:customize-users[])
+
.Note:
The difference between post-build scripts (above) and fakeroot scripts,
  is that post-build scripts are not called in the fakeroot context.
+
.Note:
Using `fakeroot` is not an absolute substitute for actually being root.
  `fakeroot` only ever fakes the file access rights and types (regular,
  block-or-char device...) and uid/gid; these are emulated in-memory.

include::customize-device-permission-tables.adoc[]