--- /dev/null
+// -*- 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:
- - +BR2_CONFIG+: the path to the Buildroot .config file
- - +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
++
+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:
-* 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.
+ - +BR2_CONFIG+: the path to the Buildroot .config file
+ - +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
-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.
+Below two more methods of customizing the target filesystem are
+described, but they are not recommended.
-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.
+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.
-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+.
-
-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.
projects / buildroot.git / commitdiff