86a415df8a
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>
135 lines
4.7 KiB
Plaintext
135 lines
4.7 KiB
Plaintext
// -*- mode:doc -*- ;
|
|
|
|
[[outside-br-custom]]
|
|
=== Keeping customizations outside Buildroot
|
|
|
|
The Buildroot community recommends and encourages upstreaming to the
|
|
official Buildroot version the packages and board support that are
|
|
written by developers. However, it is sometimes not possible or
|
|
desirable because some of these packages or board support are highly
|
|
specific or proprietary.
|
|
|
|
In this case, Buildroot users are offered two choices:
|
|
|
|
* They can add their packages, board support and configuration files
|
|
directly within the Buildroot tree, and maintain them by using
|
|
branches in a version control system.
|
|
|
|
* They can use the +BR2_EXTERNAL+ mechanism, which allows to keep
|
|
package recipes, board support and configuration files outside of
|
|
the Buildroot tree, while still having them nicely integrated in
|
|
the build logic. The following paragraphs give details on how to
|
|
use +BR2_EXTERNAL+.
|
|
|
|
+BR2_EXTERNAL+ is an environment variable that can be used to point to
|
|
a directory that contains Buildroot customizations. It can be passed
|
|
to any Buildroot +make+ invocation. It is automatically saved in the
|
|
hidden +.br-external+ file in the output directory. By doing this,
|
|
there is no need to pass +BR2_EXTERNAL+ at every +make+ invocation. It
|
|
can however be changed at any time by passing a new value, and can be
|
|
removed by passing an empty value.
|
|
|
|
*Note:* the +BR2_EXTERNAL+ path can be either an absolute or a relative path,
|
|
but if it's passed as a relative path, it is important to note that it
|
|
is interpreted relative to the main Buildroot source directory, *not*
|
|
the Buildroot output directory.
|
|
|
|
Some examples:
|
|
|
|
-----
|
|
buildroot/ $ make BR2_EXTERNAL=/path/to/foobar menuconfig
|
|
-----
|
|
|
|
Starting from now on, external definitions from the +/path/to/foobar+
|
|
directory will be used:
|
|
|
|
-----
|
|
buildroot/ $ make
|
|
buildroot/ $ make legal-info
|
|
-----
|
|
|
|
We can switch to another external definitions directory at any time:
|
|
|
|
-----
|
|
buildroot/ $ make BR2_EXTERNAL=/where/we/have/barfoo xconfig
|
|
-----
|
|
|
|
Or disable the usage of external definitions:
|
|
|
|
-----
|
|
buildroot/ $ make BR2_EXTERNAL= xconfig
|
|
-----
|
|
|
|
+BR2_EXTERNAL+ then allows three different things:
|
|
|
|
* One can store all the board-specific configuration files there,
|
|
such as the kernel configuration, the root filesystem overlay, or
|
|
any other configuration file for which Buildroot allows to set its
|
|
location. The +BR2_EXTERNAL+ value is available within the
|
|
Buildroot configuration using +$(BR2_EXTERNAL)+. As an example, one
|
|
could set the +BR2_ROOTFS_OVERLAY+ Buildroot option to
|
|
+$(BR2_EXTERNAL)/board/<boardname>/overlay/+ (to specify a root
|
|
filesystem overlay), or the +BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE+
|
|
Buildroot option to
|
|
+$(BR2_EXTERNAL)/board/<boardname>/kernel.config+ (to specify the
|
|
location of the kernel configuration file). To achieve this, it is
|
|
recommended but not mandatory, to store those details in
|
|
directories called +board/<boardname>/+ under +BR2_EXTERNAL+. This
|
|
matches the directory structure used within Buildroot.
|
|
|
|
* One can store package recipes (i.e. +Config.in+ and
|
|
+<packagename>.mk+), or even custom configuration options and make
|
|
logic. Buildroot automatically includes +BR2_EXTERNAL/Config.in+ to
|
|
make it appear in the top-level configuration menu, and includes
|
|
+BR2_EXTERNAL/external.mk+ with the rest of the makefile logic.
|
|
Providing those two files is mandatory, but they can be empty.
|
|
+
|
|
The main usage of this is to store package recipes. The recommended
|
|
way to do this is to write a +BR2_EXTERNAL/Config.in+ that looks
|
|
like:
|
|
+
|
|
------
|
|
source "$BR2_EXTERNAL/package/package1/Config.in"
|
|
source "$BR2_EXTERNAL/package/package2/Config.in"
|
|
------
|
|
+
|
|
Then, have a +BR2_EXTERNAL/external.mk+ file that looks like:
|
|
+
|
|
------
|
|
include $(sort $(wildcard $(BR2_EXTERNAL)/package/*/*.mk))
|
|
------
|
|
+
|
|
And then in +BR2_EXTERNAL/package/package1+ and
|
|
+BR2_EXTERNAL/package/package2+ create normal Buildroot package
|
|
recipes, as explained in xref:adding-packages[].
|
|
|
|
* One can store Buildroot defconfigs in the +configs+ subdirectory of
|
|
+BR2_EXTERNAL+. Buildroot will automatically show them in the
|
|
output of +make help+ and allow them to be loaded with the normal
|
|
+make <name>_defconfig+ command. They will be visible under the
|
|
+User-provided configs:+' label in the 'make help' output.
|
|
|
|
In the end, a typical +BR2_EXTERNAL+ directory organization would
|
|
generally be:
|
|
|
|
-----
|
|
$(BR2_EXTERNAL)/
|
|
+-- Config.in
|
|
+-- external.mk
|
|
+-- board/
|
|
| +-- <boardname>/
|
|
| +-- linux.config
|
|
| +-- overlay/
|
|
| +-- etc/
|
|
| +-- <some file>
|
|
+-- configs/
|
|
| +-- <boardname>_defconfig
|
|
+-- package/
|
|
+-- package1/
|
|
| +-- Config.in
|
|
| +-- package1.mk
|
|
+-- package2/
|
|
+-- Config.in
|
|
+-- package2.mk
|
|
------
|