X-Git-Url: https://review.fuel-infra.org/gitweb?a=blobdiff_plain;ds=sidebyside;f=cirros-testvm%2Fsrc-cirros%2Fbuildroot-2015.05%2Fdocs%2Fmanual%2Fcustomize-rootfs.txt;fp=cirros-testvm%2Fsrc-cirros%2Fbuildroot-2015.05%2Fdocs%2Fmanual%2Fcustomize-rootfs.txt;h=558bd724ddca6238a54fb17d53f745aabae1da5c;hb=b0a0f15dfaa205161a7fcb20cf1b8cd4948c2ef3;hp=0000000000000000000000000000000000000000;hpb=c6ac3cd55ee2da956195eee393b0882105dfad4e;p=packages%2Ftrusty%2Fcirros-testvm.git diff --git a/cirros-testvm/src-cirros/buildroot-2015.05/docs/manual/customize-rootfs.txt b/cirros-testvm/src-cirros/buildroot-2015.05/docs/manual/customize-rootfs.txt new file mode 100644 index 0000000..558bd72 --- /dev/null +++ b/cirros-testvm/src-cirros/buildroot-2015.05/docs/manual/customize-rootfs.txt @@ -0,0 +1,107 @@ +// -*- 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. ++ +As shown in xref:customize-dir-structure[], the recommended path for + this overlay is +board///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///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. ++ +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[] + - +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 + +Below two 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. ++ +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-device-permission-tables.txt[]