manual/user guide/customization: rework section on rootfs customization

// -*- mode:doc; -*-

// vim: set syntax=asciidoc:

=== Customization _after_ the images have been created

While post-build scripts (xref:rootfs-custom[]) are run _before_

building the filesystem image, kernel and bootloader, *post-image

scripts* can be used to perform some specific actions _after_ all images

have been created.

Post-image scripts can for example be used to automatically extract your

root filesystem tarball in a location exported by your NFS server, or

to create a special firmware image that bundles your root filesystem and

kernel image, or any other custom action required for your project.

To enable this feature, specify a space-separated list of post-image

scripts in config option +BR2_ROOTFS_POST_IMAGE_SCRIPT+ (in the +System

configuration+ menu). If you specify a relative path, it will be

relative to the root of the Buildroot tree.

Just like post-build scripts, post-image scripts are run with the main

Buildroot tree as current working directory. The path to the +images+

output directory 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.

Again just like for the post-build scripts, the scripts have access to

the environment variables +BR2_CONFIG+, +HOST_DIR+, +STAGING_DIR+,

+TARGET_DIR+, +BUILD_DIR+, +BINARIES_DIR+ and +BASE_DIR+.

The post-image scripts will be executed as the user that executes

Buildroot, which should normally _not_ be the root user. Therefore, any

action requiring root permissions in one of these scripts will require

special handling (usage of fakeroot or sudo), which is left to the

script developer.

[[rootfs-custom]]

=== Customizing the generated target filesystem

Besides changing one or another configuration through +make *config+,

there are a few ways to customize the resulting target filesystem.

Besides changing the configuration through +make *config+,

there are a few other ways to customize the resulting target filesystem.

* Customize the target filesystem directly and rebuild the image.  The

  target filesystem is available under +output/target/+.  You can

  simply make your changes here and run make afterwards - this will

  rebuild the target filesystem image. This method allows you to do

  anything to the target filesystem, but if you decide to completely

  rebuild your toolchain and tools, these changes will be lost. This

  solution is therefore only useful for quick tests only: _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+ by using one of the following methods.

The two recommended methods, which can co-exist, are root filesystem

overlay(s) and post build script(s).

* Create a filesystem overlay: a tree of files that are copied directly

  over the target filesystem after it has been built.  Set

  +BR2_ROOTFS_OVERLAY+ to the top of the tree.  +.git+, +.svn+, +.hg+

  directories, +.empty+ files and files ending with +~+ are excluded.

  _Among these first 3 methods, this one should be preferred_.

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.

* In the Buildroot configuration, you can specify the paths to one or

  more *post-build scripts*. These scripts are called in the given order,

  'after' Buildroot builds all the selected software, but 'before' the

  rootfs images are assembled. The +BR2_ROOTFS_POST_BUILD_SCRIPT+ allows

  you to specify the location of your post-build scripts. This option can be

  found in the +System configuration+ menu. The destination root

  filesystem folder is given as the first argument to these scripts,

  and these scripts can then be used to remove or modify any file in your

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.

  You may also use these variables in your post-build script:

+

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.

+

In addition, you may also use these environment variables:

  - +BR2_CONFIG+: the path to the Buildroot .config file

  - +HOST_DIR+, +STAGING_DIR+, +TARGET_DIR+: see

    xref:generic-package-reference[]

    stored

  - +BASE_DIR+: the base output directory

* Create your own 'target skeleton'. You can start with the default

  skeleton available under +system/skeleton+ and then customize it to

  suit your needs. The +BR2_ROOTFS_SKELETON_CUSTOM+ and

  +BR2_ROOTFS_SKELETON_CUSTOM_PATH+ will allow you to specify the

  location of your custom skeleton. These options can be found in the

  +System configuration+ menu. At build time, the contents of the

  skeleton are copied to output/target before any package

  installation. Note that this method is *not recommended*, as it

  duplicates the entire skeleton, which prevents from taking advantage

  of the fixes or improvements brought to the default Buildroot

  skeleton. The recommended method is to use the _post-build scripts_

  mechanism described in the previous item.

Note also that you can use the *post-image scripts*

if you want to perform some specific actions 'after' all

filesystem images have been created (for example to automatically

extract your root filesystem tarball in a location exported by your

NFS server, or to create a special firmware image that bundles your

root filesystem and kernel image, or any other custom action), you can

specify a space-separated list of scripts in the

+BR2_ROOTFS_POST_IMAGE_SCRIPT+ configuration option. This option can be

found in the +System configuration+ menu as well.

Each of those scripts will be called with the path to the +images+

output directory as first argument, and will be executed with the main

Buildroot source directory as the current directory. Those scripts will

be executed as the user that executes Buildroot, which should normally

not be the root user. Therefore, any action requiring root permissions

in one of these _post-image scripts_ will require special handling

(usage of fakeroot or sudo), which is left to the script developer.

Below two more methods of customizing the target filesystem are

described, but they are not recommended.

Just like for the _post-build scripts_ mentioned above, you also have

access to the following environment variables from your _post-image

scripts_: +BR2_CONFIG+, +BUILD_DIR+, +HOST_DIR+, +STAGING_DIR+,

+TARGET_DIR+, +BINARIES_DIR+ and +BASE_DIR+.

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.

Additionally, each of the +BR2_ROOTFS_POST_BUILD_SCRIPT+ and

+BR2_ROOTFS_POST_IMAGE_SCRIPT+ scripts will be passed the arguments

specified in +BR2_ROOTFS_POST_SCRIPT_ARGS+ (if that is not empty).

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.

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.

+

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.

include::customize-rootfs.txt[]

include::customize-post-image.txt[]

include::customize-store.txt[]

include::customize-packages.txt[]