kumquat-buildroot/docs/manual/customize-outside-br.txt

135 lines
4.7 KiB
Plaintext
Raw Normal View History

// -*- mode:doc -*- ;
[[outside-br-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
=== 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
------