From patchwork Sun Aug 31 13:14:30 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Thomas De Schampheleire X-Patchwork-Id: 384538 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from silver.osuosl.org (silver.osuosl.org [140.211.166.136]) by ozlabs.org (Postfix) with ESMTP id AC559140187 for ; Sun, 31 Aug 2014 23:14:47 +1000 (EST) Received: from localhost (localhost [127.0.0.1]) by silver.osuosl.org (Postfix) with ESMTP id 015952F4CD; Sun, 31 Aug 2014 13:14:47 +0000 (UTC) X-Virus-Scanned: amavisd-new at osuosl.org Received: from silver.osuosl.org ([127.0.0.1]) by localhost (.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id pvsAMbO++bEH; Sun, 31 Aug 2014 13:14:44 +0000 (UTC) Received: from ash.osuosl.org (ash.osuosl.org [140.211.166.34]) by silver.osuosl.org (Postfix) with ESMTP id 1F4282F535; Sun, 31 Aug 2014 13:14:44 +0000 (UTC) X-Original-To: buildroot@lists.busybox.net Delivered-To: buildroot@osuosl.org Received: from hemlock.osuosl.org (hemlock.osuosl.org [140.211.166.133]) by ash.osuosl.org (Postfix) with ESMTP id D6C331C1091 for ; Sun, 31 Aug 2014 13:14:42 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by hemlock.osuosl.org (Postfix) with ESMTP id D471D89552 for ; Sun, 31 Aug 2014 13:14:42 +0000 (UTC) X-Virus-Scanned: amavisd-new at osuosl.org Received: from hemlock.osuosl.org ([127.0.0.1]) by localhost (.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id pd0cSW1unIJh for ; Sun, 31 Aug 2014 13:14:41 +0000 (UTC) X-Greylist: domain auto-whitelisted by SQLgrey-1.7.6 Received: from mail-la0-f46.google.com (mail-la0-f46.google.com [209.85.215.46]) by hemlock.osuosl.org (Postfix) with ESMTPS id 52F4A894EC for ; Sun, 31 Aug 2014 13:14:41 +0000 (UTC) Received: by mail-la0-f46.google.com with SMTP id pv20so4841021lab.33 for ; Sun, 31 Aug 2014 06:14:39 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=content-type:mime-version:content-transfer-encoding:subject :message-id:user-agent:date:from:to:cc; bh=/8VqupHbY5PBoA6MeWb6en+RuBn18eBR0KklaHU9eqk=; b=mafQQ0tOnL0PScVK0lMnMrgBQ1AOsY8wOTCRsi7/ovmeoWGNgCsXdrPo5ia6nU93rr S4vb4BXAvA93Wz2nMDgFQ0kqkpYdgy0KlFH/W27NwjwdjhIocfuAqDbva0yFc5JHHN7M +1a840TnNF/l4/03rfx/13zggWxuQjEr/actAA9g81Xqq+l/y0dyE0xo0UYev4Asc1Hx U0a0a30sfEOEbMkRRALsUFQkMjhKRD7nZ99J1FTm3UxSW/cWAuG4hCa6mQ0D/acfq2fV xvB282ZH8jMxlCNG353TRZ3KYB3vUSpGPSLbIy2hDNRMDOKlrzf8WQU+fS8aNu34Jk9/ FjhA== X-Received: by 10.112.34.47 with SMTP id w15mr2174928lbi.84.1409490879480; Sun, 31 Aug 2014 06:14:39 -0700 (PDT) Received: from [127.0.0.1] (d54c62eeb.access.telenet.be. [84.198.46.235]) by mx.google.com with ESMTPSA id xe10sm8643476lbb.37.2014.08.31.06.14.38 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Sun, 31 Aug 2014 06:14:38 -0700 (PDT) MIME-Version: 1.0 X-Mercurial-Node: 32d666f0bce6eda213345c6497969d62940a65b0 Message-Id: <32d666f0bce6eda21334.1409490870@localhost> User-Agent: Mercurial-patchbomb/3.0.2 Date: Sun, 31 Aug 2014 15:14:30 +0200 From: Thomas De Schampheleire To: buildroot@buildroot.org Cc: thomas.petazzoni@free-electrons.com, yann.morin.1998@free.fr Subject: [Buildroot] [PATCH v2 for 2014.08] manual/user guide/customization: rework section on rootfs customization X-BeenThere: buildroot@busybox.net X-Mailman-Version: 2.1.14 Precedence: list List-Id: Discussion and development of buildroot List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: buildroot-bounces@busybox.net Sender: buildroot-bounces@busybox.net 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 --- v2: add missing file (noticed by Yann) docs/manual/customize-post-image.txt | 37 ++++++ docs/manual/customize-rootfs.txt | 153 ++++++++++++++------------ docs/manual/customize.txt | 2 + 3 files changed, 121 insertions(+), 71 deletions(-) diff --git a/docs/manual/customize-post-image.txt b/docs/manual/customize-post-image.txt new file mode 100644 --- /dev/null +++ b/docs/manual/customize-post-image.txt @@ -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. diff --git a/docs/manual/customize-rootfs.txt b/docs/manual/customize-rootfs.txt --- a/docs/manual/customize-rootfs.txt +++ b/docs/manual/customize-rootfs.txt @@ -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. diff --git a/docs/manual/customize.txt b/docs/manual/customize.txt --- a/docs/manual/customize.txt +++ b/docs/manual/customize.txt @@ -40,6 +40,8 @@ include::customize-rootfs.txt[] +include::customize-post-image.txt[] + include::customize-store.txt[] include::customize-packages.txt[]