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
60  Note that the arguments from +BR2_ROOTFS_POST_SCRIPT_ARGS+ will also be
61  passed to post-image and post-fakeroot scripts. If you want to use
62  arguments that are only used for the post-build scripts you can use
63  +BR2_ROOTFS_POST_BUILD_SCRIPT_ARGS+.
64
65+
66In addition, you may also use these environment variables:
67
68  - +BR2_CONFIG+: the path to the Buildroot .config file
69  - +CONFIG_DIR+: the directory containing the .config file, and
70    therefore the top-level Buildroot Makefile to use (which is
71    correct for both in-tree and out-of-tree builds)
72  - +HOST_DIR+, +STAGING_DIR+, +TARGET_DIR+: see
73    xref:generic-package-reference[]
74  - +BUILD_DIR+: the directory where packages are extracted and built
75  - +BINARIES_DIR+: the place where all binary files (aka images) are
76    stored
77  - +BASE_DIR+: the base output directory
78
79Below three more methods of customizing the target filesystem are
80described, but they are not recommended.
81
82Direct modification of the target filesystem::
83+
84For temporary modifications, you can modify the target filesystem
85  directly and rebuild the image. The target filesystem is available
86  under +output/target/+. After making your changes, run +make+ to
87  rebuild the target filesystem image.
88+
89This method allows you to do anything to the target filesystem, but if
90  you need to clean your Buildroot tree using +make clean+, these
91  changes will be lost. Such cleaning is necessary in several cases,
92  refer to xref:full-rebuild[] for details. This solution is therefore
93  only useful for quick tests: _changes do not survive the +make clean+
94  command_. Once you have validated your changes, you should make sure
95  that they will persist after a +make clean+, using a root filesystem
96  overlay or a post-build script.
97
98Custom target skeleton (+BR2_ROOTFS_SKELETON_CUSTOM+)::
99+
100The root filesystem image is created from a target skeleton, on top of
101  which all packages install their files. The skeleton is copied to the
102  target directory +output/target+ before any package is built and
103  installed. The default target skeleton provides the standard Unix
104  filesystem layout and some basic init scripts and configuration files.
105+
106If the default skeleton (available under +system/skeleton+) does not
107  match your needs, you would typically use a root filesystem overlay or
108  post-build script to adapt it. However, if the default skeleton is
109  entirely different than what you need, using a custom skeleton may be
110  more suitable.
111+
112To enable this feature, enable config option
113  +BR2_ROOTFS_SKELETON_CUSTOM+ and set +BR2_ROOTFS_SKELETON_CUSTOM_PATH+
114  to the path of your custom skeleton. Both options are available in the
115  +System configuration+ menu. If you specify a relative path, it will
116  be relative to the root of the Buildroot tree.
117+
118Custom skeletons don't need to contain the '/bin', '/lib' or '/sbin'
119  directories, since they are created automatically during the build.
120  When +BR2_ROOTFS_MERGED_USR+ is enabled, then the custom skeleton must
121  not contain the '/bin', '/lib' or '/sbin' directories, as Buildroot
122  will create them as symbolic links to the relevant folders in '/usr'.
123  In such a situation, should the skeleton have any programs or
124  libraries, they should be placed in '/usr/bin', '/usr/sbin' and
125  '/usr/lib'.
126+
127This method is not recommended because it duplicates the entire
128  skeleton, which prevents taking advantage of the fixes or improvements
129  brought to the default skeleton in later Buildroot releases.
130
131Post-fakeroot scripts (+BR2_ROOTFS_POST_FAKEROOT_SCRIPT+)::
132+
133When aggregating the final images, some parts of the process requires
134  root rights: creating device nodes in `/dev`, setting permissions or
135  ownership to files and directories... To avoid requiring actual root
136  rights, Buildroot uses +fakeroot+ to simulate root rights. This is not
137  a complete substitute for actually being root, but is enough for what
138  Buildroot needs.
139+
140Post-fakeroot scripts are shell scripts that are called at the 'end' of
141  the fakeroot phase, 'right before' the filesystem image generator is
142  called. As such, they are called in the fakeroot context.
143+
144Post-fakeroot scripts can be useful in case you need to tweak the
145  filesystem to do modifications that are usually only available to the
146  root user.
147+
148.Note:
149It is recommended to use the existing mechanisms to set file permissions
150  or create entries in `/dev` (see xref:customize-device-permission[]) or
151  to create users (see xref:customize-users[])
152+
153.Note:
154The difference between post-build scripts (above) and fakeroot scripts,
155  is that post-build scripts are not called in the fakeroot context.
156+
157.Note:
158Using `fakeroot` is not an absolute substitute for actually being root.
159  `fakeroot` only ever fakes the file access rights and types (regular,
160  block-or-char device...) and uid/gid; these are emulated in-memory.
161
162include::customize-device-permission-tables.adoc[]
163