1// -*- mode:doc; -*- 2// vim: set syntax=asciidoc: 3 4[[rootfs-custom]] 5=== Customizing the generated target filesystem 6 7Besides changing the configuration through +make *config+, 8there are a few other ways to customize the resulting target filesystem. 9 10The two recommended methods, which can co-exist, are root filesystem 11overlay(s) and post build script(s). 12 13Root filesystem overlays (+BR2_ROOTFS_OVERLAY+):: 14+ 15A filesystem overlay is a tree of files that is copied directly 16 over the target filesystem after it has been built. To enable this 17 feature, set config option +BR2_ROOTFS_OVERLAY+ (in the +System 18 configuration+ menu) to the root of the overlay. You can even specify 19 multiple overlays, space-separated. If you specify a relative path, 20 it will be relative to the root of the Buildroot tree. Hidden 21 directories of version control systems, like +.git+, +.svn+, +.hg+, 22 etc., files called +.empty+ and files ending in +~+ are excluded from 23 the copy. 24+ 25When +BR2_ROOTFS_MERGED_USR+ is enabled, then the overlay must not 26 contain the '/bin', '/lib' or '/sbin' directories, as Buildroot will 27 create them as symbolic links to the relevant folders in '/usr'. In 28 such a situation, should the overlay have any programs or libraries, 29 they should be placed in '/usr/bin', '/usr/sbin' and '/usr/lib'. 30+ 31As shown in xref:customize-dir-structure[], the recommended path for 32 this overlay is +board/<company>/<boardname>/rootfs-overlay+. 33 34Post-build scripts (+BR2_ROOTFS_POST_BUILD_SCRIPT+):: 35+ 36Post-build scripts are shell scripts called 'after' Buildroot builds 37 all the selected software, but 'before' the rootfs images are 38 assembled. To enable this feature, specify a space-separated list of 39 post-build scripts in config option +BR2_ROOTFS_POST_BUILD_SCRIPT+ (in 40 the +System configuration+ menu). If you specify a relative path, it 41 will be relative to the root of the Buildroot tree. 42+ 43Using post-build scripts, you can remove or modify any file in your 44 target filesystem. You should, however, use this feature with care. 45 Whenever you find that a certain package generates wrong or unneeded 46 files, you should fix that package rather than work around it with some 47 post-build cleanup scripts. 48+ 49As shown in xref:customize-dir-structure[], the recommended path for 50 this script is +board/<company>/<boardname>/post_build.sh+. 51+ 52The post-build scripts are run with the main Buildroot tree as current 53 working directory. The path to the target filesystem is passed as the 54 first argument to each script. If the config option 55 +BR2_ROOTFS_POST_SCRIPT_ARGS+ is not empty, these arguments will be 56 passed to the script too. All the scripts will be passed the exact 57 same set of arguments, it is not possible to pass different sets of 58 arguments to each script. 59+ 60In addition, you may also use these environment variables: 61 62 - +BR2_CONFIG+: the path to the Buildroot .config file 63 - +CONFIG_DIR+: the directory containing the .config file, and 64 therefore the top-level Buildroot Makefile to use (which is 65 correct for both in-tree and out-of-tree builds) 66 - +HOST_DIR+, +STAGING_DIR+, +TARGET_DIR+: see 67 xref:generic-package-reference[] 68 - +BUILD_DIR+: the directory where packages are extracted and built 69 - +BINARIES_DIR+: the place where all binary files (aka images) are 70 stored 71 - +BASE_DIR+: the base output directory 72 73Below three more methods of customizing the target filesystem are 74described, but they are not recommended. 75 76Direct modification of the target filesystem:: 77+ 78For temporary modifications, you can modify the target filesystem 79 directly and rebuild the image. The target filesystem is available 80 under +output/target/+. After making your changes, run +make+ to 81 rebuild the target filesystem image. 82+ 83This method allows you to do anything to the target filesystem, but if 84 you need to clean your Buildroot tree using +make clean+, these 85 changes will be lost. Such cleaning is necessary in several cases, 86 refer to xref:full-rebuild[] for details. This solution is therefore 87 only useful for quick tests: _changes do not survive the +make clean+ 88 command_. Once you have validated your changes, you should make sure 89 that they will persist after a +make clean+, using a root filesystem 90 overlay or a post-build script. 91 92Custom target skeleton (+BR2_ROOTFS_SKELETON_CUSTOM+):: 93+ 94The root filesystem image is created from a target skeleton, on top of 95 which all packages install their files. The skeleton is copied to the 96 target directory +output/target+ before any package is built and 97 installed. The default target skeleton provides the standard Unix 98 filesystem layout and some basic init scripts and configuration files. 99+ 100If the default skeleton (available under +system/skeleton+) does not 101 match your needs, you would typically use a root filesystem overlay or 102 post-build script to adapt it. However, if the default skeleton is 103 entirely different than what you need, using a custom skeleton may be 104 more suitable. 105+ 106To enable this feature, enable config option 107 +BR2_ROOTFS_SKELETON_CUSTOM+ and set +BR2_ROOTFS_SKELETON_CUSTOM_PATH+ 108 to the path of your custom skeleton. Both options are available in the 109 +System configuration+ menu. If you specify a relative path, it will 110 be relative to the root of the Buildroot tree. 111+ 112Custom skeletons don't need to contain the '/bin', '/lib' or '/sbin' 113 directories, since they are created automatically during the build. 114 When +BR2_ROOTFS_MERGED_USR+ is enabled, then the custom skeleton must 115 not contain the '/bin', '/lib' or '/sbin' directories, as Buildroot 116 will create them as symbolic links to the relevant folders in '/usr'. 117 In such a situation, should the skeleton have any programs or 118 libraries, they should be placed in '/usr/bin', '/usr/sbin' and 119 '/usr/lib'. 120+ 121This method is not recommended because it duplicates the entire 122 skeleton, which prevents taking advantage of the fixes or improvements 123 brought to the default skeleton in later Buildroot releases. 124 125Post-fakeroot scripts (+BR2_ROOTFS_POST_FAKEROOT_SCRIPT+):: 126+ 127When aggregating the final images, some parts of the process requires 128 root rights: creating device nodes in `/dev`, setting permissions or 129 ownership to files and directories... To avoid requiring actual root 130 rights, Buildroot uses +fakeroot+ to simulate root rights. This is not 131 a complete substitute for actually being root, but is enough for what 132 Buildroot needs. 133+ 134Post-fakeroot scripts are shell scripts that are called at the 'end' of 135 the fakeroot phase, 'right before' the filesystem image generator is 136 called. As such, they are called in the fakeroot context. 137+ 138Post-fakeroot scripts can be useful in case you need to tweak the 139 filesystem to do modifications that are usually only available to the 140 root user. 141+ 142.Note: 143It is recommended to use the existing mechanisms to set file permissions 144 or create entries in `/dev` (see xref:customize-device-permission[]) or 145 to create users (see xref:customize-users[]) 146+ 147.Note: 148The difference between post-build scripts (above) and fakeroot scripts, 149 is that post-build scripts are not called in the fakeroot context. 150+ 151.Note: 152Using `fakeroot` is not an absolute substitute for actually being root. 153 `fakeroot` only ever fakes the file access rights and types (regular, 154 block-or-char device...) and uid/gid; these are emulated in-memory. 155 156include::customize-device-permission-tables.txt[] 157