2013-02-13 13:59:02 +01:00
|
|
|
// -*- mode:doc; -*-
|
|
|
|
|
// vim: set syntax=asciidoc:
|
2012-11-11 04:14:42 +01:00
|
|
|
|
|
|
|
|
[[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
|
2011-10-10 10:46:39 +02:00
|
|
|
|
2014-08-31 15:14:30 +02:00
|
|
|
Besides changing the configuration through +make *config+,
|
|
|
|
|
there are a few other ways to customize the resulting target filesystem.
|
2011-10-10 10:46:39 +02:00
|
|
|
|
2014-08-31 15:14:30 +02:00
|
|
|
The two recommended methods, which can co-exist, are root filesystem
|
|
|
|
|
overlay(s) and post build script(s).
|
2011-10-10 10:46:39 +02:00
|
|
|
|
2014-08-31 15:14:30 +02:00
|
|
|
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.
|
2014-09-18 21:39:34 +02:00
|
|
|
+
|
|
|
|
|
As shown in xref:customize-dir-structure[], the recommended path for
|
|
|
|
|
this overlay is +board/<company>/<boardname>/rootfs-overlay+.
|
2013-02-05 08:16:00 +01:00
|
|
|
|
2014-08-31 15:14:30 +02:00
|
|
|
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
|
2013-02-05 08:16:00 +01:00
|
|
|
target filesystem. You should, however, use this feature with care.
|
|
|
|
|
Whenever you find that a certain package generates wrong or unneeded
|
2013-02-25 12:31:23 +01:00
|
|
|
files, you should fix that package rather than work around it with some
|
|
|
|
|
post-build cleanup scripts.
|
2014-08-31 15:14:30 +02:00
|
|
|
+
|
2014-09-18 21:39:34 +02:00
|
|
|
As shown in xref:customize-dir-structure[], the recommended path for
|
|
|
|
|
this script is +board/<company>/<boardname>/post_build.sh+.
|
|
|
|
|
+
|
2014-08-31 15:14:30 +02:00
|
|
|
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:
|
2011-10-10 10:46:39 +02:00
|
|
|
|
2014-08-31 15:14:30 +02:00
|
|
|
- +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
|
2013-02-07 12:58:47 +01:00
|
|
|
|
2014-08-31 15:14:30 +02:00
|
|
|
Below two more methods of customizing the target filesystem are
|
|
|
|
|
described, but they are not recommended.
|
2013-02-07 12:58:44 +01:00
|
|
|
|
2014-08-31 15:14:30 +02:00
|
|
|
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.
|
2013-02-07 12:58:44 +01:00
|
|
|
|
2014-08-31 15:14:30 +02:00
|
|
|
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.
|
2014-09-18 21:39:29 +02:00
|
|
|
|
|
|
|
|
include::customize-device-permission-tables.txt[]
|
