2 // vim: set syntax=asciidoc:
5 == Buildroot configuration
7 All the configuration options in +make *config+ have a help text
8 providing details about the option.
10 The +make *config+ commands also offer a search tool. Read the help
11 message in the different frontend menus to know how to use it:
13 * in _menuconfig_, the search tool is called by pressing +/+;
14 * in _xconfig_, the search tool is called by pressing +Ctrl+ + +f+.
16 The result of the search shows the help message of the matching items.
17 In _menuconfig_, numbers in the left column provide a shortcut to the
18 corresponding entry. Just type this number to directly jump to the
19 entry, or to the containing menu in case the entry is not selectable due
20 to a missing dependency.
22 Although the menu structure and the help text of the entries should be
23 sufficiently self-explanatory, a number of topics require additional
24 explanation that cannot easily be covered in the help text and are
25 therefore covered in the following sections.
27 === Cross-compilation toolchain
29 A compilation toolchain is the set of tools that allows you to compile
30 code for your system. It consists of a compiler (in our case, +gcc+),
31 binary utils like assembler and linker (in our case, +binutils+) and a
32 C standard library (for example
33 http://www.gnu.org/software/libc/libc.html[GNU Libc],
34 http://www.uclibc.org/[uClibc]).
36 The system installed on your development station certainly already has
37 a compilation toolchain that you can use to compile an application
38 that runs on your system. If you're using a PC, your compilation
39 toolchain runs on an x86 processor and generates code for an x86
40 processor. Under most Linux systems, the compilation toolchain uses
41 the GNU libc (glibc) as the C standard library. This compilation
42 toolchain is called the "host compilation toolchain". The machine on
43 which it is running, and on which you're working, is called the "host
44 system" footnote:[This terminology differs from what is used by GNU
45 configure, where the host is the machine on which the application will
46 run (which is usually the same as target)].
48 The compilation toolchain is provided by your distribution, and
49 Buildroot has nothing to do with it (other than using it to build a
50 cross-compilation toolchain and other tools that are run on the
53 As said above, the compilation toolchain that comes with your system
54 runs on and generates code for the processor in your host system. As
55 your embedded system has a different processor, you need a
56 cross-compilation toolchain - a compilation toolchain that runs on
57 your _host system_ but generates code for your _target system_ (and
58 target processor). For example, if your host system uses x86 and your
59 target system uses ARM, the regular compilation toolchain on your host
60 runs on x86 and generates code for x86, while the cross-compilation
61 toolchain runs on x86 and generates code for ARM.
63 Buildroot provides two solutions for the cross-compilation toolchain:
65 * The *internal toolchain backend*, called +Buildroot toolchain+ in
66 the configuration interface.
68 * The *external toolchain backend*, called +External toolchain+ in
69 the configuration interface.
71 The choice between these two solutions is done using the +Toolchain
72 Type+ option in the +Toolchain+ menu. Once one solution has been
73 chosen, a number of configuration options appear, they are detailed in
74 the following sections.
76 [[internal-toolchain-backend]]
77 ==== Internal toolchain backend
79 The _internal toolchain backend_ is the backend where Buildroot builds
80 by itself a cross-compilation toolchain, before building the userspace
81 applications and libraries for your target embedded system.
83 This backend supports several C libraries:
84 http://www.uclibc.org[uClibc], the
85 http://www.gnu.org/software/libc/libc.html[glibc] and
86 http://www.eglibc.org[eglibc].
88 Once you have selected this backend, a number of options appear. The
89 most important ones allow to:
91 * Change the version of the Linux kernel headers used to build the
92 toolchain. This item deserves a few explanations. In the process of
93 building a cross-compilation toolchain, the C library is being
94 built. This library provides the interface between userspace
95 applications and the Linux kernel. In order to know how to "talk"
96 to the Linux kernel, the C library needs to have access to the
97 _Linux kernel headers_ (i.e. the +.h+ files from the kernel), which
98 define the interface between userspace and the kernel (system
99 calls, data structures, etc.). Since this interface is backward
100 compatible, the version of the Linux kernel headers used to build
101 your toolchain do not need to match _exactly_ the version of the
102 Linux kernel you intend to run on your embedded system. They only
103 need to have a version equal or older to the version of the Linux
104 kernel you intend to run. If you use kernel headers that are more
105 recent than the Linux kernel you run on your embedded system, then
106 the C library might be using interfaces that are not provided by
109 * Change the version of the GCC compiler, binutils and the C library.
111 * Select a number of toolchain options (uClibc only): whether the
112 toolchain should have RPC support (used mainly for NFS),
113 wide-char support, locale support (for internationalization),
114 C++ support or thread support. Depending on which options you choose,
115 the number of userspace applications and libraries visible in
116 Buildroot menus will change: many applications and libraries require
117 certain toolchain options to be enabled. Most packages show a comment
118 when a certain toolchain option is required to be able to enable
119 those packages. If needed, you can further refine the uClibc
120 configuration by running +make uclibc-menuconfig+. Note however that
121 all packages in Buildroot are tested against the default uClibc
122 configuration bundled in Buildroot: if you deviate from this
123 configuration by removing features from uClibc, some packages may no
126 It is worth noting that whenever one of those options is modified,
127 then the entire toolchain and system must be rebuilt. See
130 Advantages of this backend:
132 * Well integrated with Buildroot
133 * Fast, only builds what's necessary
135 Drawbacks of this backend:
137 * Rebuilding the toolchain is needed when doing +make clean+, which
138 takes time. If you're trying to reduce your build time, consider
139 using the _External toolchain backend_.
141 [[external-toolchain-backend]]
142 ==== External toolchain backend
144 The _external toolchain backend_ allows to use existing pre-built
145 cross-compilation toolchains. Buildroot knows about a number of
146 well-known cross-compilation toolchains (from
147 http://www.linaro.org[Linaro] for ARM,
148 http://www.mentor.com/embedded-software/sourcery-tools/sourcery-codebench/editions/lite-edition/[Sourcery
149 CodeBench] for ARM, x86, x86-64, PowerPC, MIPS and SuperH,
150 https://blackfin.uclinux.org/gf/project/toolchain[Blackfin toolchains
151 from Analog Devices], etc.) and is capable of downloading them
152 automatically, or it can be pointed to a custom toolchain, either
153 available for download or installed locally.
155 Then, you have three solutions to use an external toolchain:
157 * Use a predefined external toolchain profile, and let Buildroot
158 download, extract and install the toolchain. Buildroot already knows
159 about a few CodeSourcery, Linaro, Blackfin and Xilinx toolchains.
160 Just select the toolchain profile in +Toolchain+ from the
161 available ones. This is definitely the easiest solution.
163 * Use a predefined external toolchain profile, but instead of having
164 Buildroot download and extract the toolchain, you can tell Buildroot
165 where your toolchain is already installed on your system. Just
166 select the toolchain profile in +Toolchain+ through the available
167 ones, unselect +Download toolchain automatically+, and fill the
168 +Toolchain path+ text entry with the path to your cross-compiling
171 * Use a completely custom external toolchain. This is particularly
172 useful for toolchains generated using crosstool-NG or with Buildroot
173 itself. To do this, select the +Custom toolchain+ solution in the
174 +Toolchain+ list. You need to fill the +Toolchain path+, +Toolchain
175 prefix+ and +External toolchain C library+ options. Then, you have
176 to tell Buildroot what your external toolchain supports. If your
177 external toolchain uses the 'glibc' library, you only have to tell
178 whether your toolchain supports C\++ or not and whether it has
179 built-in RPC support. If your external toolchain uses the 'uClibc'
180 library, then you have to tell Buildroot if it supports RPC,
181 wide-char, locale, program invocation, threads and C++.
182 At the beginning of the execution, Buildroot will tell you if
183 the selected options do not match the toolchain configuration.
185 Our external toolchain support has been tested with toolchains from
186 CodeSourcery and Linaro, toolchains generated by
187 http://crosstool-ng.org[crosstool-NG], and toolchains generated by
188 Buildroot itself. In general, all toolchains that support the
189 'sysroot' feature should work. If not, do not hesitate to contact the
192 We do not support toolchains or SDK generated by OpenEmbedded or
193 Yocto, because these toolchains are not pure toolchains (i.e. just the
194 compiler, binutils, the C and C++ libraries). Instead these toolchains
195 come with a very large set of pre-compiled libraries and
196 programs. Therefore, Buildroot cannot import the 'sysroot' of the
197 toolchain, as it would contain hundreds of megabytes of pre-compiled
198 libraries that are normally built by Buildroot.
200 We also do not support using the distribution toolchain (i.e. the
201 gcc/binutils/C library installed by your distribution) as the
202 toolchain to build software for the target. This is because your
203 distribution toolchain is not a "pure" toolchain (i.e. only with the
204 C/C++ library), so we cannot import it properly into the Buildroot
205 build environment. So even if you are building a system for a x86 or
206 x86_64 target, you have to generate a cross-compilation toolchain with
207 Buildroot or crosstool-NG.
209 If you want to generate a custom toolchain for your project, that can
210 be used as an external toolchain in Buildroot, our recommendation is
211 definitely to build it with http://crosstool-ng.org[crosstool-NG]. We
212 recommend to build the toolchain separately from Buildroot, and then
213 _import_ it in Buildroot using the external toolchain backend.
215 Advantages of this backend:
217 * Allows to use well-known and well-tested cross-compilation
220 * Avoids the build time of the cross-compilation toolchain, which is
221 often very significant in the overall build time of an embedded
224 * Not limited to uClibc: glibc and eglibc toolchains are supported.
226 Drawbacks of this backend:
228 * If your pre-built external toolchain has a bug, may be hard to get a
229 fix from the toolchain vendor, unless you build your external
230 toolchain by yourself using Crosstool-NG.
232 ===== External toolchain wrapper
234 When using an external toolchain, Buildroot generates a wrapper program,
235 that transparently passes the appropriate options (according to the
236 configuration) to the external toolchain programs. In case you need to
237 debug this wrapper to check exactly what arguments are passed, you can
238 set the environment variable +BR2_DEBUG_WRAPPER+ to either one of:
240 * +0+, empty or not set: no debug
242 * +1+: trace all arguments on a single line
244 * +2+: trace one argument per line
248 On a Linux system, the +/dev+ directory contains special files, called
249 _device files_, that allow userspace applications to access the
250 hardware devices managed by the Linux kernel. Without these _device
251 files_, your userspace applications would not be able to use the
252 hardware devices, even if they are properly recognized by the Linux
255 Under +System configuration+, +/dev management+, Buildroot offers four
256 different solutions to handle the +/dev+ directory :
258 * The first solution is *Static using device table*. This is the old
259 classical way of handling device files in Linux. With this method,
260 the device files are persistently stored in the root filesystem
261 (i.e. they persist across reboots), and there is nothing that will
262 automatically create and remove those device files when hardware
263 devices are added or removed from the system. Buildroot therefore
264 creates a standard set of device files using a _device table_, the
265 default one being stored in +system/device_table_dev.txt+ in the
266 Buildroot source code. This file is processed when Buildroot
267 generates the final root filesystem image, and the _device files_
268 are therefore not visible in the +output/target+ directory. The
269 +BR2_ROOTFS_STATIC_DEVICE_TABLE+ option allows to change the
270 default device table used by Buildroot, or to add an additional
271 device table, so that additional _device files_ are created by
272 Buildroot during the build. So, if you use this method, and a
273 _device file_ is missing in your system, you can for example create
274 a +board/<yourcompany>/<yourproject>/device_table_dev.txt+ file
275 that contains the description of your additional _device files_,
276 and then you can set +BR2_ROOTFS_STATIC_DEVICE_TABLE+ to
277 +system/device_table_dev.txt
278 board/<yourcompany>/<yourproject>/device_table_dev.txt+. For more
279 details about the format of the device table file, see
280 xref:makedev-syntax[].
282 * The second solution is *Dynamic using devtmpfs only*. _devtmpfs_ is
283 a virtual filesystem inside the Linux kernel that has been
284 introduced in kernel 2.6.32 (if you use an older kernel, it is not
285 possible to use this option). When mounted in +/dev+, this virtual
286 filesystem will automatically make _device files_ appear and
287 disappear as hardware devices are added and removed from the
288 system. This filesystem is not persistent across reboots: it is
289 filled dynamically by the kernel. Using _devtmpfs_ requires the
290 following kernel configuration options to be enabled:
291 +CONFIG_DEVTMPFS+ and +CONFIG_DEVTMPFS_MOUNT+. When Buildroot is in
292 charge of building the Linux kernel for your embedded device, it
293 makes sure that those two options are enabled. However, if you
294 build your Linux kernel outside of Buildroot, then it is your
295 responsibility to enable those two options (if you fail to do so,
296 your Buildroot system will not boot).
298 * The third solution is *Dynamic using mdev*. This method also relies
299 on the _devtmpfs_ virtual filesystem detailed above (so the
300 requirement to have +CONFIG_DEVTMPFS+ and +CONFIG_DEVTMPFS_MOUNT+
301 enabled in the kernel configuration still apply), but adds the
302 +mdev+ userspace utility on top of it. +mdev+ is a program part of
303 BusyBox that the kernel will call every time a device is added or
304 removed. Thanks to the +/etc/mdev.conf+ configuration file, +mdev+
305 can be configured to for example, set specific permissions or
306 ownership on a device file, call a script or application whenever a
307 device appears or disappear, etc. Basically, it allows _userspace_
308 to react on device addition and removal events. +mdev+ can for
309 example be used to automatically load kernel modules when devices
310 appear on the system. +mdev+ is also important if you have devices
311 that require a firmware, as it will be responsible for pushing the
312 firmware contents to the kernel. +mdev+ is a lightweight
313 implementation (with fewer features) of +udev+. For more details
314 about +mdev+ and the syntax of its configuration file, see
315 http://git.busybox.net/busybox/tree/docs/mdev.txt.
317 * The fourth solution is *Dynamic using eudev*. This method also
318 relies on the _devtmpfs_ virtual filesystem detailed above, but
319 adds the +eudev+ userspace daemon on top of it. +eudev+ is a daemon
320 that runs in the background, and gets called by the kernel when a
321 device gets added or removed from the system. It is a more
322 heavyweight solution than +mdev+, but provides higher flexibility.
323 +eudev+ is a standalone version of +udev+, the original userspace
324 daemon used in most desktop Linux distributions, which is now part
325 of Systemd. For more details, see http://en.wikipedia.org/wiki/Udev.
327 The Buildroot developers recommendation is to start with the *Dynamic
328 using devtmpfs only* solution, until you have the need for userspace
329 to be notified when devices are added/removed, or if firmwares are
330 needed, in which case *Dynamic using mdev* is usually a good solution.
332 Note that if +systemd+ is chosen as init system, /dev management will
333 be performed by the +udev+ program provided by +systemd+.
337 The _init_ program is the first userspace program started by the
338 kernel (it carries the PID number 1), and is responsible for starting
339 the userspace services and programs (for example: web server,
340 graphical applications, other network servers, etc.).
342 Buildroot allows to use three different types of init systems, which
343 can be chosen from +System configuration+, +Init system+:
345 * The first solution is *BusyBox*. Amongst many programs, BusyBox has
346 an implementation of a basic +init+ program, which is sufficient
347 for most embedded systems. Enabling the +BR2_INIT_BUSYBOX+ will
348 ensure BusyBox will build and install its +init+ program. This is
349 the default solution in Buildroot. The BusyBox +init+ program will
350 read the +/etc/inittab+ file at boot to know what to do. The syntax
351 of this file can be found in
352 http://git.busybox.net/busybox/tree/examples/inittab (note that
353 BusyBox +inittab+ syntax is special: do not use a random +inittab+
354 documentation from the Internet to learn about BusyBox
355 +inittab+). The default +inittab+ in Buildroot is stored in
356 +system/skeleton/etc/inittab+. Apart from mounting a few important
357 filesystems, the main job the default inittab does is to start the
358 +/etc/init.d/rcS+ shell script, and start a +getty+ program (which
359 provides a login prompt).
361 * The second solution is *systemV*. This solution uses the old
362 traditional _sysvinit_ program, packed in Buildroot in
363 +package/sysvinit+. This was the solution used in most desktop
364 Linux distributions, until they switched to more recent
365 alternatives such as Upstart or Systemd. +sysvinit+ also works with
366 an +inittab+ file (which has a slightly different syntax than the
367 one from BusyBox). The default +inittab+ installed with this init
368 solution is located in +package/sysvinit/inittab+.
370 * The third solution is *systemd*. +systemd+ is the new generation
371 init system for Linux. It does far more than traditional _init_
372 programs: aggressive parallelization capabilities, uses socket and
373 D-Bus activation for starting services, offers on-demand starting
374 of daemons, keeps track of processes using Linux control groups,
375 supports snapshotting and restoring of the system state,
376 etc. +systemd+ will be useful on relatively complex embedded
377 systems, for example the ones requiring D-Bus and services
378 communicating between each other. It is worth noting that +systemd+
379 brings a fairly big number of large dependencies: +dbus+, +udev+
380 and more. For more details about +systemd+, see
381 http://www.freedesktop.org/wiki/Software/systemd.
383 The solution recommended by Buildroot developers is to use the
384 *BusyBox init* as it is sufficient for most embedded
385 systems. *systemd* can be used for more complex situations.