kumquat-buildroot/docs/manual/customize-toolchain.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

50 lines
1.6 KiB
Plaintext

// -*- mode:doc; -*-
// vim: set syntax=asciidoc:
[[toolchain-custom]]
=== Customizing the toolchain
There are three distinct types of toolchain backend supported in Buildroot,
available under the menu +Toolchain+, invoking +make menuconfig+.
==== Using the external toolchain backend
There is no way of tuning an external toolchain since Buildroot does not
generate it.
It also requires to set the Buildroot settings according to the toolchain ones
(see xref:external-toolchain-backend[]).
When using an external toolchain, Buildroot generates a wrapper program,
that transparently passes the appropriate options (according to the
configuration) to the external toolchain programs. In case you need to
debug this wrapper to check exactly what arguments are passed, you can
set the environment variable +BR2_DEBUG_WRAPPER+ to either one of:
* +0+, empty or not set: no debug
* +1+: trace all arguments on a single line
* +2+: trace one argument per line
==== Using the internal Buildroot toolchain backend
The internal Buildroot toolchain backend allows to generate toolchains
based on http://www.uclibc.org/[uClibc],
https://www.gnu.org/software/libc/[glibc] and
http://www.eglibc.org/[eglibc].
Generation of (e)glibc-based toolchains is still experimental in
Buildroot.
It allows to tune major settings, such as:
* Linux headers version;
* C library configuration (only available for
http://www.uclibc.org/[uClibc], see xref:uclibc-custom[uClibc]);
* Binutils, GCC, Gdb and toolchain options.
These settings are available after selecting the +Buildroot toolchain+ type in
the menu +Toolchain+.