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
|
|
|
|
2012-11-11 04:14:45 +01:00
|
|
|
Besides changing one or another configuration through +make *config+,
|
2012-11-27 12:59:16 +01:00
|
|
|
there are a few ways to customize the resulting target filesystem.
|
2011-10-10 10:46:39 +02:00
|
|
|
|
|
|
|
|
* 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
|
2013-02-07 12:58:47 +01:00
|
|
|
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.
|
2011-10-10 10:46:39 +02:00
|
|
|
|
2013-02-05 08:16:00 +01:00
|
|
|
* Create a filesystem overlay: a tree of files that are copied directly
|
|
|
|
|
over the target filesystem after it has been built. Set
|
2013-02-07 12:58:10 +01:00
|
|
|
+BR2_ROOTFS_OVERLAY+ to the top of the tree. +.git+, +.svn+, +.hg+
|
|
|
|
|
directories, +.empty+ files and files ending with +~+ are excluded.
|
2013-02-05 08:16:00 +01:00
|
|
|
_Among these first 3 methods, this one should be preferred_.
|
|
|
|
|
|
2013-02-25 12:31:23 +01:00
|
|
|
* 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
|
2012-11-11 04:14:45 +01:00
|
|
|
found in the +System configuration+ menu. The destination root
|
2013-02-25 12:31:23 +01:00
|
|
|
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
|
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.
|
2013-01-13 12:52:20 +01:00
|
|
|
You may also use these variables in your post-build script:
|
2014-02-04 16:18:52 +01:00
|
|
|
- +BR2_CONFIG+: the path to the Buildroot .config file
|
2013-01-13 12:52:20 +01:00
|
|
|
- +HOST_DIR+, +STAGING_DIR+, +TARGET_DIR+: see
|
|
|
|
|
xref:generic-package-reference[]
|
2013-11-11 16:03:26 +01:00
|
|
|
- +BUILD_DIR+: the directory where packages are extracted and built
|
2013-01-13 12:52:20 +01:00
|
|
|
- +BINARIES_DIR+: the place where all binary files (aka images) are
|
|
|
|
|
stored
|
2013-01-14 10:02:29 +01:00
|
|
|
- +BASE_DIR+: the base output directory
|
2011-10-10 10:46:39 +02:00
|
|
|
|
2013-02-07 12:58:47 +01:00
|
|
|
* 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
|
2013-02-25 12:31:23 +01:00
|
|
|
skeleton. The recommended method is to use the _post-build scripts_
|
2013-02-07 12:58:47 +01:00
|
|
|
mechanism described in the previous item.
|
|
|
|
|
|
2013-02-25 12:31:23 +01:00
|
|
|
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
|
2013-02-07 12:58:44 +01:00
|
|
|
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
|
2013-02-25 12:31:23 +01:00
|
|
|
+BR2_ROOTFS_POST_IMAGE_SCRIPT+ configuration option. This option can be
|
|
|
|
|
found in the +System configuration+ menu as well.
|
2013-02-07 12:58:44 +01:00
|
|
|
|
|
|
|
|
Each of those scripts will be called with the path to the +images+
|
2013-07-10 00:00:31 +02:00
|
|
|
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.
|
2013-02-07 12:58:44 +01:00
|
|
|
|
|
|
|
|
Just like for the _post-build scripts_ mentioned above, you also have
|
|
|
|
|
access to the following environment variables from your _post-image
|
2014-02-04 16:18:52 +01:00
|
|
|
scripts_: +BR2_CONFIG+, +BUILD_DIR+, +HOST_DIR+, +STAGING_DIR+,
|
2013-11-11 16:03:26 +01:00
|
|
|
+TARGET_DIR+, +BINARIES_DIR+ and +BASE_DIR+.
|
2013-07-10 00:00:31 +02:00
|
|
|
|
|
|
|
|
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.
|
