kumquat-buildroot/docs/manual/customize-rootfs.txt

108 lines
4.9 KiB
Plaintext
Raw Normal View History

// -*- mode:doc; -*-
// vim: set syntax=asciidoc:
[[rootfs-custom]]
manual: use one-line titles instead of two-line titles (trivial) Asciidoc supports two syntaxes for section titles: two-line titles (title plus underline consisting of a particular symbol), and one-line titles (title prefixed with a specific number of = signs). The two-line title underlines are: Level 0 (top level): ====================== Level 1: ---------------------- Level 2: ~~~~~~~~~~~~~~~~~~~~~~ Level 3: ^^^^^^^^^^^^^^^^^^^^^^ Level 4 (bottom level): ++++++++++++++++++++++ and the one-line title prefixes: = Document Title (level 0) = == Section title (level 1) == === Section title (level 2) === ==== Section title (level 3) ==== ===== Section title (level 4) ===== The buildroot manual is currenly using the two-line titles, but this has multiple disadvantages: - asciidoc also uses some of the underline symbols for other purposes (like preformatted code, example blocks, ...), which makes it difficult to do mass replacements, such as a planned follow-up patch that needs to move all sections one level down. - it is difficult to remember which level a given underline symbol (=-~^+) corresponds to, while counting = signs is easy. This patch changes all two-level titles to one-level titles in the manual. The bulk of the change was done with the following Python script, except for the level 1 titles (-----) as these underlines are also used for literal code blocks. This patch only changes the titles, no other changes. In adding-packages-directory.txt, I did add missing newlines between some titles and their content. ---------------------------------------------------------------------------- #!/usr/bin/env python import sys import mmap import re for input in sys.argv[1:]: f = open(input, 'r+') f.flush() s = mmap.mmap(f.fileno(), 0) # Level 0 (top level): ====================== = # Level 1: ---------------------- == # Level 2: ~~~~~~~~~~~~~~~~~~~~~~ === # Level 3: ^^^^^^^^^^^^^^^^^^^^^^ ==== # Level 4 (bottom level): ++++++++++++++++++++++ ===== def replace_title(s, symbol, replacement): pattern = re.compile(r'(.+\n)\%s{2,}\n' % symbol, re.MULTILINE) return pattern.sub(r'%s \1' % replacement, s) new = s new = replace_title(new, '=', '=') new = replace_title(new, '+', '=====') new = replace_title(new, '^', '====') new = replace_title(new, '~', '===') #new = replace_title(new, '-', '==') s.seek(0) s.write(new) s.resize(s.tell()) s.close() f.close() ---------------------------------------------------------------------------- Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2014-05-02 07:47:30 +02:00
=== 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/<company>/<boardname>/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/<company>/<boardname>/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[]