kumquat-buildroot/docs/manual/how-buildroot-works.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

70 lines
2.6 KiB
Plaintext

// -*- mode:doc; -*-
// vim: set syntax=asciidoc:
== How Buildroot works
As mentioned above, Buildroot is basically a set of Makefiles that
download, configure, and compile software with the correct options. It
also includes patches for various software packages - mainly the ones
involved in the cross-compilation toolchain (+gcc+, +binutils+ and
+uClibc+).
There is basically one Makefile per software package, and they are
named with the +.mk+ extension. Makefiles are split into many different
parts.
* The +toolchain/+ directory contains the Makefiles
and associated files for all software related to the
cross-compilation toolchain: +binutils+, +gcc+, +gdb+,
+kernel-headers+ and +uClibc+.
* The +arch/+ directory contains the definitions for all the processor
architectures that are supported by Buildroot.
* The +package/+ directory contains the Makefiles and
associated files for all user-space tools and libraries that Buildroot
can compile and add to the target root filesystem. There is one
sub-directory per package.
* The +linux/+ directory contains the Makefiles and associated files for
the Linux kernel.
* The +boot/+ directory contains the Makefiles and associated files for
the bootloaders supported by Buildroot.
* The +system/+ directory contains support for system integration, e.g.
the target filesystem skeleton and the selection of an init system.
* The +fs/+ directory contains the Makefiles and
associated files for software related to the generation of the
target root filesystem image.
Each directory contains at least 2 files:
* +something.mk+ is the Makefile that downloads, configures,
compiles and installs the package +something+.
* +Config.in+ is a part of the configuration tool
description file. It describes the options related to the
package.
The main Makefile performs the following steps (once the
configuration is done):
* Create all the output directories: +staging+, +target+, +build+,
etc. in the output directory (+output/+ by default,
another value can be specified using +O=+)
* Generate the toolchain target. When an internal toolchain is used, this
means generating the cross-compilation toolchain. When an external
toolchain is used, this means checking the features of the external
toolchain and importing it into the Buildroot environment.
* Generate all the targets listed in the +TARGETS+ variable. This
variable is filled by all the individual components'
Makefiles. Generating these targets will trigger the compilation of
the userspace packages (libraries, programs), the kernel, the
bootloader and the generation of the root filesystem images,
depending on the configuration.