2013-02-13 13:59:02 +01:00
|
|
|
// -*- mode:doc; -*-
|
|
|
|
|
// vim: set syntax=asciidoc:
|
2012-12-29 05:42:27 +01:00
|
|
|
|
|
|
|
|
[[configure]]
|
2014-08-19 21:41:47 +02:00
|
|
|
== Buildroot configuration
|
2012-12-29 05:42:27 +01:00
|
|
|
|
|
|
|
|
All the configuration options in +make *config+ have a help text
|
2014-08-19 21:41:48 +02:00
|
|
|
providing details about the option.
|
|
|
|
|
|
|
|
|
|
The +make *config+ commands also offer a search tool. Read the help
|
|
|
|
|
message in the different frontend menus to know how to use it:
|
|
|
|
|
|
|
|
|
|
* in _menuconfig_, the search tool is called by pressing +/+;
|
|
|
|
|
* in _xconfig_, the search tool is called by pressing +Ctrl+ + +f+.
|
|
|
|
|
|
|
|
|
|
The result of the search shows the help message of the matching items.
|
|
|
|
|
In _menuconfig_, numbers in the left column provide a shortcut to the
|
|
|
|
|
corresponding entry. Just type this number to directly jump to the
|
|
|
|
|
entry, or to the containing menu in case the entry is not selectable due
|
|
|
|
|
to a missing dependency.
|
|
|
|
|
|
|
|
|
|
Although the menu structure and the help text of the entries should be
|
|
|
|
|
sufficiently self-explanatory, a number of topics require additional
|
|
|
|
|
explanation that cannot easily be covered in the help text and are
|
|
|
|
|
therefore covered in the following sections.
|
2012-12-29 05:42:27 +01:00
|
|
|
|
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
|
|
|
=== Cross-compilation toolchain
|
2012-12-29 05:42:29 +01:00
|
|
|
|
|
|
|
|
A compilation toolchain is the set of tools that allows you to compile
|
|
|
|
|
code for your system. It consists of a compiler (in our case, +gcc+),
|
|
|
|
|
binary utils like assembler and linker (in our case, +binutils+) and a
|
|
|
|
|
C standard library (for example
|
|
|
|
|
http://www.gnu.org/software/libc/libc.html[GNU Libc],
|
|
|
|
|
http://www.uclibc.org/[uClibc]).
|
|
|
|
|
|
|
|
|
|
The system installed on your development station certainly already has
|
|
|
|
|
a compilation toolchain that you can use to compile an application
|
|
|
|
|
that runs on your system. If you're using a PC, your compilation
|
|
|
|
|
toolchain runs on an x86 processor and generates code for an x86
|
|
|
|
|
processor. Under most Linux systems, the compilation toolchain uses
|
|
|
|
|
the GNU libc (glibc) as the C standard library. This compilation
|
|
|
|
|
toolchain is called the "host compilation toolchain". The machine on
|
|
|
|
|
which it is running, and on which you're working, is called the "host
|
|
|
|
|
system" footnote:[This terminology differs from what is used by GNU
|
|
|
|
|
configure, where the host is the machine on which the application will
|
|
|
|
|
run (which is usually the same as target)].
|
|
|
|
|
|
|
|
|
|
The compilation toolchain is provided by your distribution, and
|
|
|
|
|
Buildroot has nothing to do with it (other than using it to build a
|
|
|
|
|
cross-compilation toolchain and other tools that are run on the
|
|
|
|
|
development host).
|
|
|
|
|
|
|
|
|
|
As said above, the compilation toolchain that comes with your system
|
|
|
|
|
runs on and generates code for the processor in your host system. As
|
|
|
|
|
your embedded system has a different processor, you need a
|
|
|
|
|
cross-compilation toolchain - a compilation toolchain that runs on
|
|
|
|
|
your _host system_ but generates code for your _target system_ (and
|
|
|
|
|
target processor). For example, if your host system uses x86 and your
|
|
|
|
|
target system uses ARM, the regular compilation toolchain on your host
|
|
|
|
|
runs on x86 and generates code for x86, while the cross-compilation
|
|
|
|
|
toolchain runs on x86 and generates code for ARM.
|
|
|
|
|
|
2013-10-06 16:19:12 +02:00
|
|
|
Buildroot provides two solutions for the cross-compilation toolchain:
|
2012-12-29 05:42:29 +01:00
|
|
|
|
|
|
|
|
* The *internal toolchain backend*, called +Buildroot toolchain+ in
|
|
|
|
|
the configuration interface.
|
|
|
|
|
|
|
|
|
|
* The *external toolchain backend*, called +External toolchain+ in
|
|
|
|
|
the configuration interface.
|
|
|
|
|
|
2013-10-06 16:19:12 +02:00
|
|
|
The choice between these two solutions is done using the +Toolchain
|
2012-12-29 05:42:29 +01:00
|
|
|
Type+ option in the +Toolchain+ menu. Once one solution has been
|
|
|
|
|
chosen, a number of configuration options appear, they are detailed in
|
|
|
|
|
the following sections.
|
|
|
|
|
|
2013-02-25 12:31:21 +01:00
|
|
|
[[internal-toolchain-backend]]
|
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
|
|
|
==== Internal toolchain backend
|
2012-12-29 05:42:29 +01:00
|
|
|
|
|
|
|
|
The _internal toolchain backend_ is the backend where Buildroot builds
|
|
|
|
|
by itself a cross-compilation toolchain, before building the userspace
|
|
|
|
|
applications and libraries for your target embedded system.
|
|
|
|
|
|
2014-02-23 16:04:33 +01:00
|
|
|
This backend supports several C libraries:
|
2016-06-08 23:40:55 +02:00
|
|
|
http://www.uclibc.org[uClibc],
|
2014-02-23 16:04:33 +01:00
|
|
|
http://www.gnu.org/software/libc/libc.html[glibc] and
|
2016-06-08 23:40:55 +02:00
|
|
|
http://www.musl-libc.org[musl].
|
2012-12-29 05:42:29 +01:00
|
|
|
|
|
|
|
|
Once you have selected this backend, a number of options appear. The
|
|
|
|
|
most important ones allow to:
|
|
|
|
|
|
|
|
|
|
* Change the version of the Linux kernel headers used to build the
|
|
|
|
|
toolchain. This item deserves a few explanations. In the process of
|
|
|
|
|
building a cross-compilation toolchain, the C library is being
|
|
|
|
|
built. This library provides the interface between userspace
|
|
|
|
|
applications and the Linux kernel. In order to know how to "talk"
|
|
|
|
|
to the Linux kernel, the C library needs to have access to the
|
2014-03-28 22:24:50 +01:00
|
|
|
_Linux kernel headers_ (i.e. the +.h+ files from the kernel), which
|
2012-12-29 05:42:29 +01:00
|
|
|
define the interface between userspace and the kernel (system
|
|
|
|
|
calls, data structures, etc.). Since this interface is backward
|
|
|
|
|
compatible, the version of the Linux kernel headers used to build
|
|
|
|
|
your toolchain do not need to match _exactly_ the version of the
|
|
|
|
|
Linux kernel you intend to run on your embedded system. They only
|
|
|
|
|
need to have a version equal or older to the version of the Linux
|
|
|
|
|
kernel you intend to run. If you use kernel headers that are more
|
|
|
|
|
recent than the Linux kernel you run on your embedded system, then
|
|
|
|
|
the C library might be using interfaces that are not provided by
|
|
|
|
|
your Linux kernel.
|
|
|
|
|
|
2014-02-23 16:04:33 +01:00
|
|
|
* Change the version of the GCC compiler, binutils and the C library.
|
2012-12-29 05:42:29 +01:00
|
|
|
|
2013-06-30 21:29:13 +02:00
|
|
|
* Select a number of toolchain options (uClibc only): whether the
|
2015-04-19 14:39:58 +02:00
|
|
|
toolchain should have RPC support (used mainly for NFS),
|
|
|
|
|
wide-char support, locale support (for internationalization),
|
2015-03-30 23:07:31 +02:00
|
|
|
C++ support or thread support. Depending on which options you choose,
|
|
|
|
|
the number of userspace applications and libraries visible in
|
|
|
|
|
Buildroot menus will change: many applications and libraries require
|
|
|
|
|
certain toolchain options to be enabled. Most packages show a comment
|
|
|
|
|
when a certain toolchain option is required to be able to enable
|
|
|
|
|
those packages. If needed, you can further refine the uClibc
|
|
|
|
|
configuration by running +make uclibc-menuconfig+. Note however that
|
|
|
|
|
all packages in Buildroot are tested against the default uClibc
|
|
|
|
|
configuration bundled in Buildroot: if you deviate from this
|
|
|
|
|
configuration by removing features from uClibc, some packages may no
|
|
|
|
|
longer build.
|
2012-12-29 05:42:29 +01:00
|
|
|
|
|
|
|
|
It is worth noting that whenever one of those options is modified,
|
|
|
|
|
then the entire toolchain and system must be rebuilt. See
|
|
|
|
|
xref:full-rebuild[].
|
|
|
|
|
|
|
|
|
|
Advantages of this backend:
|
|
|
|
|
|
|
|
|
|
* Well integrated with Buildroot
|
|
|
|
|
* Fast, only builds what's necessary
|
|
|
|
|
|
|
|
|
|
Drawbacks of this backend:
|
|
|
|
|
|
|
|
|
|
* Rebuilding the toolchain is needed when doing +make clean+, which
|
|
|
|
|
takes time. If you're trying to reduce your build time, consider
|
|
|
|
|
using the _External toolchain backend_.
|
|
|
|
|
|
2013-02-25 12:31:21 +01:00
|
|
|
[[external-toolchain-backend]]
|
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
|
|
|
==== External toolchain backend
|
2012-12-29 05:42:29 +01:00
|
|
|
|
|
|
|
|
The _external toolchain backend_ allows to use existing pre-built
|
|
|
|
|
cross-compilation toolchains. Buildroot knows about a number of
|
|
|
|
|
well-known cross-compilation toolchains (from
|
|
|
|
|
http://www.linaro.org[Linaro] for ARM,
|
|
|
|
|
http://www.mentor.com/embedded-software/sourcery-tools/sourcery-codebench/editions/lite-edition/[Sourcery
|
|
|
|
|
CodeBench] for ARM, x86, x86-64, PowerPC, MIPS and SuperH,
|
|
|
|
|
https://blackfin.uclinux.org/gf/project/toolchain[Blackfin toolchains
|
2014-02-23 16:04:34 +01:00
|
|
|
from Analog Devices], etc.) and is capable of downloading them
|
|
|
|
|
automatically, or it can be pointed to a custom toolchain, either
|
|
|
|
|
available for download or installed locally.
|
2012-12-29 05:42:29 +01:00
|
|
|
|
|
|
|
|
Then, you have three solutions to use an external toolchain:
|
|
|
|
|
|
|
|
|
|
* Use a predefined external toolchain profile, and let Buildroot
|
|
|
|
|
download, extract and install the toolchain. Buildroot already knows
|
|
|
|
|
about a few CodeSourcery, Linaro, Blackfin and Xilinx toolchains.
|
|
|
|
|
Just select the toolchain profile in +Toolchain+ from the
|
|
|
|
|
available ones. This is definitely the easiest solution.
|
|
|
|
|
|
|
|
|
|
* Use a predefined external toolchain profile, but instead of having
|
|
|
|
|
Buildroot download and extract the toolchain, you can tell Buildroot
|
|
|
|
|
where your toolchain is already installed on your system. Just
|
|
|
|
|
select the toolchain profile in +Toolchain+ through the available
|
|
|
|
|
ones, unselect +Download toolchain automatically+, and fill the
|
|
|
|
|
+Toolchain path+ text entry with the path to your cross-compiling
|
|
|
|
|
toolchain.
|
|
|
|
|
|
|
|
|
|
* Use a completely custom external toolchain. This is particularly
|
2014-02-23 16:04:35 +01:00
|
|
|
useful for toolchains generated using crosstool-NG or with Buildroot
|
|
|
|
|
itself. To do this, select the +Custom toolchain+ solution in the
|
|
|
|
|
+Toolchain+ list. You need to fill the +Toolchain path+, +Toolchain
|
|
|
|
|
prefix+ and +External toolchain C library+ options. Then, you have
|
|
|
|
|
to tell Buildroot what your external toolchain supports. If your
|
|
|
|
|
external toolchain uses the 'glibc' library, you only have to tell
|
manual/configure.txt: fix C++ escaping
For asciidoc, a string like '+these are some words+' will be displayed in
monospace font. Such sequences are identified by searching for a matching
pair of + signs in the same block.
The string 'C++' also contains such + signs. In most cases, this does not
pose a problem and no escaping is necessary. However, if 'C++' occurs twice
in the same block, the + signs will be matched to each other, and asciidoc
formats all text between them as monospaced text. In this case, escaping of
one of these 'C++' occurances is necessary to get the right formatting.
In one place of the manual, there is a sentence that causes such a problem:
"you only have to tell whether your toolchain supports C++ or not and
whether it has built-in RPC support. If your external toolchain uses
the 'uClibc' library, then you have to tell Buildroot if it supports
largefile, IPv6, RPC, wide-char, locale, program invocation, threads
and C++."
Commit 082dec8ce440236b1477e568f0965f05ad241adb was based on a patch fixing
this problem in one place of the manual, but was incorrectly changed while
committing.
This patch reverts the incorrect changes in that commit, and solves the
problem correctly.
Signed-off-by: Jerzy Grzegorek <jerzy.grzegorek@trzebnica.net>
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2014-05-02 10:02:38 +02:00
|
|
|
whether your toolchain supports C\++ or not and whether it has
|
2014-02-23 16:04:35 +01:00
|
|
|
built-in RPC support. If your external toolchain uses the 'uClibc'
|
2015-04-19 14:39:58 +02:00
|
|
|
library, then you have to tell Buildroot if it supports RPC,
|
|
|
|
|
wide-char, locale, program invocation, threads and C++.
|
|
|
|
|
At the beginning of the execution, Buildroot will tell you if
|
2012-12-29 05:42:29 +01:00
|
|
|
the selected options do not match the toolchain configuration.
|
|
|
|
|
|
|
|
|
|
Our external toolchain support has been tested with toolchains from
|
|
|
|
|
CodeSourcery and Linaro, toolchains generated by
|
|
|
|
|
http://crosstool-ng.org[crosstool-NG], and toolchains generated by
|
|
|
|
|
Buildroot itself. In general, all toolchains that support the
|
|
|
|
|
'sysroot' feature should work. If not, do not hesitate to contact the
|
|
|
|
|
developers.
|
|
|
|
|
|
2014-02-23 16:04:36 +01:00
|
|
|
We do not support toolchains or SDK generated by OpenEmbedded or
|
2014-03-28 22:24:50 +01:00
|
|
|
Yocto, because these toolchains are not pure toolchains (i.e. just the
|
2014-02-23 16:04:36 +01:00
|
|
|
compiler, binutils, the C and C++ libraries). Instead these toolchains
|
|
|
|
|
come with a very large set of pre-compiled libraries and
|
|
|
|
|
programs. Therefore, Buildroot cannot import the 'sysroot' of the
|
|
|
|
|
toolchain, as it would contain hundreds of megabytes of pre-compiled
|
|
|
|
|
libraries that are normally built by Buildroot.
|
2012-12-29 05:42:29 +01:00
|
|
|
|
2014-03-28 22:24:50 +01:00
|
|
|
We also do not support using the distribution toolchain (i.e. the
|
2012-12-29 05:42:29 +01:00
|
|
|
gcc/binutils/C library installed by your distribution) as the
|
|
|
|
|
toolchain to build software for the target. This is because your
|
2014-03-28 22:24:50 +01:00
|
|
|
distribution toolchain is not a "pure" toolchain (i.e. only with the
|
2012-12-29 05:42:29 +01:00
|
|
|
C/C++ library), so we cannot import it properly into the Buildroot
|
|
|
|
|
build environment. So even if you are building a system for a x86 or
|
|
|
|
|
x86_64 target, you have to generate a cross-compilation toolchain with
|
|
|
|
|
Buildroot or crosstool-NG.
|
|
|
|
|
|
|
|
|
|
If you want to generate a custom toolchain for your project, that can
|
2014-02-07 14:21:35 +01:00
|
|
|
be used as an external toolchain in Buildroot, our recommendation is
|
2012-12-29 05:42:29 +01:00
|
|
|
definitely to build it with http://crosstool-ng.org[crosstool-NG]. We
|
|
|
|
|
recommend to build the toolchain separately from Buildroot, and then
|
|
|
|
|
_import_ it in Buildroot using the external toolchain backend.
|
|
|
|
|
|
|
|
|
|
Advantages of this backend:
|
|
|
|
|
|
|
|
|
|
* Allows to use well-known and well-tested cross-compilation
|
|
|
|
|
toolchains.
|
|
|
|
|
|
|
|
|
|
* Avoids the build time of the cross-compilation toolchain, which is
|
|
|
|
|
often very significant in the overall build time of an embedded
|
|
|
|
|
Linux system.
|
|
|
|
|
|
|
|
|
|
* Not limited to uClibc: glibc and eglibc toolchains are supported.
|
|
|
|
|
|
|
|
|
|
Drawbacks of this backend:
|
|
|
|
|
|
|
|
|
|
* If your pre-built external toolchain has a bug, may be hard to get a
|
|
|
|
|
fix from the toolchain vendor, unless you build your external
|
|
|
|
|
toolchain by yourself using Crosstool-NG.
|
|
|
|
|
|
2014-08-19 21:41:47 +02:00
|
|
|
===== External toolchain wrapper
|
|
|
|
|
|
|
|
|
|
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
|
|
|
|
|
|
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
|
|
|
=== /dev management
|
2012-12-29 05:42:27 +01:00
|
|
|
|
|
|
|
|
On a Linux system, the +/dev+ directory contains special files, called
|
|
|
|
|
_device files_, that allow userspace applications to access the
|
|
|
|
|
hardware devices managed by the Linux kernel. Without these _device
|
|
|
|
|
files_, your userspace applications would not be able to use the
|
|
|
|
|
hardware devices, even if they are properly recognized by the Linux
|
|
|
|
|
kernel.
|
|
|
|
|
|
|
|
|
|
Under +System configuration+, +/dev management+, Buildroot offers four
|
|
|
|
|
different solutions to handle the +/dev+ directory :
|
|
|
|
|
|
|
|
|
|
* The first solution is *Static using device table*. This is the old
|
|
|
|
|
classical way of handling device files in Linux. With this method,
|
|
|
|
|
the device files are persistently stored in the root filesystem
|
2014-05-31 10:26:20 +02:00
|
|
|
(i.e. they persist across reboots), and there is nothing that will
|
2012-12-29 05:42:27 +01:00
|
|
|
automatically create and remove those device files when hardware
|
|
|
|
|
devices are added or removed from the system. Buildroot therefore
|
|
|
|
|
creates a standard set of device files using a _device table_, the
|
|
|
|
|
default one being stored in +system/device_table_dev.txt+ in the
|
|
|
|
|
Buildroot source code. This file is processed when Buildroot
|
|
|
|
|
generates the final root filesystem image, and the _device files_
|
|
|
|
|
are therefore not visible in the +output/target+ directory. The
|
|
|
|
|
+BR2_ROOTFS_STATIC_DEVICE_TABLE+ option allows to change the
|
|
|
|
|
default device table used by Buildroot, or to add an additional
|
|
|
|
|
device table, so that additional _device files_ are created by
|
|
|
|
|
Buildroot during the build. So, if you use this method, and a
|
|
|
|
|
_device file_ is missing in your system, you can for example create
|
|
|
|
|
a +board/<yourcompany>/<yourproject>/device_table_dev.txt+ file
|
|
|
|
|
that contains the description of your additional _device files_,
|
|
|
|
|
and then you can set +BR2_ROOTFS_STATIC_DEVICE_TABLE+ to
|
|
|
|
|
+system/device_table_dev.txt
|
|
|
|
|
board/<yourcompany>/<yourproject>/device_table_dev.txt+. For more
|
|
|
|
|
details about the format of the device table file, see
|
|
|
|
|
xref:makedev-syntax[].
|
|
|
|
|
|
|
|
|
|
* The second solution is *Dynamic using devtmpfs only*. _devtmpfs_ is
|
|
|
|
|
a virtual filesystem inside the Linux kernel that has been
|
|
|
|
|
introduced in kernel 2.6.32 (if you use an older kernel, it is not
|
|
|
|
|
possible to use this option). When mounted in +/dev+, this virtual
|
|
|
|
|
filesystem will automatically make _device files_ appear and
|
|
|
|
|
disappear as hardware devices are added and removed from the
|
2014-05-31 10:26:20 +02:00
|
|
|
system. This filesystem is not persistent across reboots: it is
|
2012-12-29 05:42:27 +01:00
|
|
|
filled dynamically by the kernel. Using _devtmpfs_ requires the
|
|
|
|
|
following kernel configuration options to be enabled:
|
|
|
|
|
+CONFIG_DEVTMPFS+ and +CONFIG_DEVTMPFS_MOUNT+. When Buildroot is in
|
|
|
|
|
charge of building the Linux kernel for your embedded device, it
|
|
|
|
|
makes sure that those two options are enabled. However, if you
|
|
|
|
|
build your Linux kernel outside of Buildroot, then it is your
|
2014-05-31 10:26:20 +02:00
|
|
|
responsibility to enable those two options (if you fail to do so,
|
2012-12-29 05:42:27 +01:00
|
|
|
your Buildroot system will not boot).
|
|
|
|
|
|
2015-10-04 11:43:35 +02:00
|
|
|
* The third solution is *Dynamic using devtmpfs + mdev*. This method
|
|
|
|
|
also relies on the _devtmpfs_ virtual filesystem detailed above (so
|
|
|
|
|
the requirement to have +CONFIG_DEVTMPFS+ and
|
|
|
|
|
+CONFIG_DEVTMPFS_MOUNT+ enabled in the kernel configuration still
|
|
|
|
|
apply), but adds the +mdev+ userspace utility on top of it. +mdev+
|
|
|
|
|
is a program part of BusyBox that the kernel will call every time a
|
|
|
|
|
device is added or removed. Thanks to the +/etc/mdev.conf+
|
|
|
|
|
configuration file, +mdev+ can be configured to for example, set
|
|
|
|
|
specific permissions or ownership on a device file, call a script
|
|
|
|
|
or application whenever a device appears or disappear,
|
|
|
|
|
etc. Basically, it allows _userspace_ to react on device addition
|
|
|
|
|
and removal events. +mdev+ can for example be used to automatically
|
|
|
|
|
load kernel modules when devices appear on the system. +mdev+ is
|
|
|
|
|
also important if you have devices that require a firmware, as it
|
|
|
|
|
will be responsible for pushing the firmware contents to the
|
|
|
|
|
kernel. +mdev+ is a lightweight implementation (with fewer
|
|
|
|
|
features) of +udev+. For more details about +mdev+ and the syntax
|
|
|
|
|
of its configuration file, see
|
2012-12-29 05:42:27 +01:00
|
|
|
http://git.busybox.net/busybox/tree/docs/mdev.txt.
|
|
|
|
|
|
2015-10-04 11:43:35 +02:00
|
|
|
* The fourth solution is *Dynamic using devtmpfs + eudev*. This
|
|
|
|
|
method also relies on the _devtmpfs_ virtual filesystem detailed
|
|
|
|
|
above, but adds the +eudev+ userspace daemon on top of it. +eudev+
|
|
|
|
|
is a daemon that runs in the background, and gets called by the
|
|
|
|
|
kernel when a device gets added or removed from the system. It is a
|
|
|
|
|
more heavyweight solution than +mdev+, but provides higher
|
|
|
|
|
flexibility. +eudev+ is a standalone version of +udev+, the
|
|
|
|
|
original userspace daemon used in most desktop Linux distributions,
|
|
|
|
|
which is now part of Systemd. For more details, see
|
|
|
|
|
http://en.wikipedia.org/wiki/Udev.
|
2012-12-29 05:42:27 +01:00
|
|
|
|
2014-02-07 14:21:35 +01:00
|
|
|
The Buildroot developers recommendation is to start with the *Dynamic
|
2012-12-29 05:42:27 +01:00
|
|
|
using devtmpfs only* solution, until you have the need for userspace
|
|
|
|
|
to be notified when devices are added/removed, or if firmwares are
|
2015-10-04 11:43:35 +02:00
|
|
|
needed, in which case *Dynamic using devtmpfs + mdev* is usually a
|
|
|
|
|
good solution.
|
2012-12-29 05:42:27 +01:00
|
|
|
|
2014-02-07 14:21:35 +01:00
|
|
|
Note that if +systemd+ is chosen as init system, /dev management will
|
|
|
|
|
be performed by the +udev+ program provided by +systemd+.
|
|
|
|
|
|
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
|
|
|
=== init system
|
2012-12-29 05:42:27 +01:00
|
|
|
|
|
|
|
|
The _init_ program is the first userspace program started by the
|
|
|
|
|
kernel (it carries the PID number 1), and is responsible for starting
|
|
|
|
|
the userspace services and programs (for example: web server,
|
|
|
|
|
graphical applications, other network servers, etc.).
|
|
|
|
|
|
|
|
|
|
Buildroot allows to use three different types of init systems, which
|
|
|
|
|
can be chosen from +System configuration+, +Init system+:
|
|
|
|
|
|
2014-05-31 09:55:35 +02:00
|
|
|
* The first solution is *BusyBox*. Amongst many programs, BusyBox has
|
2012-12-29 05:42:27 +01:00
|
|
|
an implementation of a basic +init+ program, which is sufficient
|
|
|
|
|
for most embedded systems. Enabling the +BR2_INIT_BUSYBOX+ will
|
2014-05-31 09:55:35 +02:00
|
|
|
ensure BusyBox will build and install its +init+ program. This is
|
|
|
|
|
the default solution in Buildroot. The BusyBox +init+ program will
|
2012-12-29 05:42:27 +01:00
|
|
|
read the +/etc/inittab+ file at boot to know what to do. The syntax
|
|
|
|
|
of this file can be found in
|
|
|
|
|
http://git.busybox.net/busybox/tree/examples/inittab (note that
|
2014-05-31 09:55:35 +02:00
|
|
|
BusyBox +inittab+ syntax is special: do not use a random +inittab+
|
|
|
|
|
documentation from the Internet to learn about BusyBox
|
2012-12-29 05:42:27 +01:00
|
|
|
+inittab+). The default +inittab+ in Buildroot is stored in
|
|
|
|
|
+system/skeleton/etc/inittab+. Apart from mounting a few important
|
|
|
|
|
filesystems, the main job the default inittab does is to start the
|
|
|
|
|
+/etc/init.d/rcS+ shell script, and start a +getty+ program (which
|
|
|
|
|
provides a login prompt).
|
|
|
|
|
|
|
|
|
|
* The second solution is *systemV*. This solution uses the old
|
|
|
|
|
traditional _sysvinit_ program, packed in Buildroot in
|
|
|
|
|
+package/sysvinit+. This was the solution used in most desktop
|
|
|
|
|
Linux distributions, until they switched to more recent
|
|
|
|
|
alternatives such as Upstart or Systemd. +sysvinit+ also works with
|
|
|
|
|
an +inittab+ file (which has a slightly different syntax than the
|
2014-05-31 09:55:35 +02:00
|
|
|
one from BusyBox). The default +inittab+ installed with this init
|
2012-12-29 05:42:27 +01:00
|
|
|
solution is located in +package/sysvinit/inittab+.
|
|
|
|
|
|
|
|
|
|
* The third solution is *systemd*. +systemd+ is the new generation
|
|
|
|
|
init system for Linux. It does far more than traditional _init_
|
|
|
|
|
programs: aggressive parallelization capabilities, uses socket and
|
|
|
|
|
D-Bus activation for starting services, offers on-demand starting
|
|
|
|
|
of daemons, keeps track of processes using Linux control groups,
|
|
|
|
|
supports snapshotting and restoring of the system state,
|
|
|
|
|
etc. +systemd+ will be useful on relatively complex embedded
|
|
|
|
|
systems, for example the ones requiring D-Bus and services
|
|
|
|
|
communicating between each other. It is worth noting that +systemd+
|
2013-12-09 01:07:42 +01:00
|
|
|
brings a fairly big number of large dependencies: +dbus+, +udev+
|
2012-12-29 05:42:27 +01:00
|
|
|
and more. For more details about +systemd+, see
|
|
|
|
|
http://www.freedesktop.org/wiki/Software/systemd.
|
|
|
|
|
|
|
|
|
|
The solution recommended by Buildroot developers is to use the
|
2014-05-31 09:55:35 +02:00
|
|
|
*BusyBox init* as it is sufficient for most embedded
|
2012-12-29 05:42:27 +01:00
|
|
|
systems. *systemd* can be used for more complex situations.
|
