manual/user guide/customization: rework section on rootfs customization
This patch reworks the section on root filesystem customization as follows: - use labeled list instead of bulleted list to clarify the different methods - move rootfs overlay and post-build scripts to the top and label them as recommended. - split post-image to a separate section, as it is not related to the target filesystem customization - line up post-build and post-image explanations, for example regarding working directory of the script - general expansion of some of the explanation - general rewording Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
This commit is contained in:
Thomas De Schampheleire
Peter Korsgaard
parent
24534eb40a
commit
44a5c46213
37
docs/manual/customize-post-image.txt
Normal file
37
docs/manual/customize-post-image.txt
Normal file
@ -0,0 +1,37 @@
|
||||
// -*- 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.
|
||||
@ -4,85 +4,96 @@
|
||||
[[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.
|
||||
|
||||
@ -40,6 +40,8 @@ include::customize-outside-br.txt[]
|
||||
|
||||
include::customize-rootfs.txt[]
|
||||
|
||||
include::customize-post-image.txt[]
|
||||
|
||||
include::customize-store.txt[]
|
||||
|
||||
include::customize-packages.txt[]
|
||||
|
||||
Loading…
Reference in New Issue
Block a user