cirros-testvm/src-cirros/buildroot-2015.05/build/docs/manual/configure.txt

   1 // -*- mode:doc; -*-
   2 // vim: set syntax=asciidoc:
   3
   4 [[configure]]
   5 == Buildroot configuration
   6
   7 All the configuration options in +make *config+ have a help text
   8 providing details about the option.
   9
  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:
  12
  13 * in _menuconfig_, the search tool is called by pressing +/+;
  14 * in _xconfig_, the search tool is called by pressing +Ctrl+ + +f+.
  15
  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.
  21
  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.
  26
  27 === Cross-compilation toolchain
  28
  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]).
  35
  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)].
  47
  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
  51 development host).
  52
  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.
  62
  63 Buildroot provides two solutions for the cross-compilation toolchain:
  64
  65  * The *internal toolchain backend*, called +Buildroot toolchain+ in
  66    the configuration interface.
  67
  68  * The *external toolchain backend*, called +External toolchain+ in
  69    the configuration interface.
  70
  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.
  75
  76 [[internal-toolchain-backend]]
  77 ==== Internal toolchain backend
  78
  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.
  82
  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].
  87
  88 Once you have selected this backend, a number of options appear. The
  89 most important ones allow to:
  90
  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
 107    your Linux kernel.
 108
 109  * Change the version of the GCC compiler, binutils and the C library.
 110
 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
 124    longer build.
 125
 126 It is worth noting that whenever one of those options is modified,
 127 then the entire toolchain and system must be rebuilt. See
 128 xref:full-rebuild[].
 129
 130 Advantages of this backend:
 131
 132 * Well integrated with Buildroot
 133 * Fast, only builds what's necessary
 134
 135 Drawbacks of this backend:
 136
 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_.
 140
 141 [[external-toolchain-backend]]
 142 ==== External toolchain backend
 143
 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.
 154
 155 Then, you have three solutions to use an external toolchain:
 156
 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.
 162
 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
 169   toolchain.
 170
 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.
 184
 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
 190 developers.
 191
 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.
 199
 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.
 208
 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.
 214
 215 Advantages of this backend:
 216
 217 * Allows to use well-known and well-tested cross-compilation
 218   toolchains.
 219
 220 * Avoids the build time of the cross-compilation toolchain, which is
 221   often very significant in the overall build time of an embedded
 222   Linux system.
 223
 224 * Not limited to uClibc: glibc and eglibc toolchains are supported.
 225
 226 Drawbacks of this backend:
 227
 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.
 231
 232 ===== External toolchain wrapper
 233
 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:
 239
 240 * +0+, empty or not set: no debug
 241
 242 * +1+: trace all arguments on a single line
 243
 244 * +2+: trace one argument per line
 245
 246 === /dev management
 247
 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
 253 kernel.
 254
 255 Under +System configuration+, +/dev management+, Buildroot offers four
 256 different solutions to handle the +/dev+ directory :
 257
 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[].
 281
 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).
 297
 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.
 316
 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.
 326
 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.
 331
 332 Note that if +systemd+ is chosen as init system, /dev management will
 333 be performed by the +udev+ program provided by +systemd+.
 334
 335 === init system
 336
 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.).
 341
 342 Buildroot allows to use three different types of init systems, which
 343 can be chosen from +System configuration+, +Init system+:
 344
 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).
 360
 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+.
 369
 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.
 382
 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.