kumquat-buildroot/docs/manual/customize-rootfs.txt
Thomas De Schampheleire 86a415df8a 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 10:27:59 +02:00

89 lines
4.8 KiB
Plaintext

// -*- mode:doc; -*-
// vim: set syntax=asciidoc:
[[rootfs-custom]]
=== Customizing the generated target filesystem
Besides changing one or another configuration through +make *config+,
there are a few ways to customize the resulting target filesystem.
* 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
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.
* Create a filesystem overlay: a tree of files that are copied directly
over the target filesystem after it has been built. Set
+BR2_ROOTFS_OVERLAY+ to the top of the tree. +.git+, +.svn+, +.hg+
directories, +.empty+ files and files ending with +~+ are excluded.
_Among these first 3 methods, this one should be preferred_.
* 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
found in the +System configuration+ menu. The destination root
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
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.
You may also use these variables in your post-build script:
- +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
* 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
skeleton. The recommended method is to use the _post-build scripts_
mechanism described in the previous item.
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
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
+BR2_ROOTFS_POST_IMAGE_SCRIPT+ configuration option. This option can be
found in the +System configuration+ menu as well.
Each of those scripts will be called with the path to the +images+
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.
Just like for the _post-build scripts_ mentioned above, you also have
access to the following environment variables from your _post-image
scripts_: +BR2_CONFIG+, +BUILD_DIR+, +HOST_DIR+, +STAGING_DIR+,
+TARGET_DIR+, +BINARIES_DIR+ and +BASE_DIR+.
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.