| // -*- mode:doc; -*- |
| // vim: set syntax=asciidoc: |
| |
| [[configure]] |
| Details on Buildroot configuration |
| ---------------------------------- |
| |
| All the configuration options in +make *config+ have a help text |
| providing details about the option. However, a number of topics |
| require additional details that cannot easily be covered in the help |
| text and are there covered in the following sections. |
| |
| Cross-compilation toolchain |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| 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. |
| |
| Buildroot provides different solutions to build, or use existing |
| cross-compilation toolchains: |
| |
| * The *internal toolchain backend*, called +Buildroot toolchain+ in |
| the configuration interface. |
| |
| * The *external toolchain backend*, called +External toolchain+ in |
| the configuration interface. |
| |
| * The *Crosstool-NG toolchain backend*, called +Crosstool-NG |
| toolchain+ in the configuration interface. |
| |
| The choice between these three solutions is done using the +Toolchain |
| 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. |
| |
| [[internal-toolchain-backend]] |
| Internal toolchain backend |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| 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. |
| |
| This backend is the historical backend of Buildroot, and has been |
| limited for a long time to the usage of the |
| http://www.uclibc.org[uClibc C library]. Support for the _eglibc_ C |
| library has been added in 2013 and is at this point considered |
| experimental. See the _External toolchain backend_ and _Crosstool-NG |
| toolchain backend_ for other solutions to use _glibc_ or _eglibc_. |
| |
| 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 |
| _Linux kernel headers_ (i.e, the +.h+ files from the kernel), which |
| 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. |
| |
| * Change the version and the configuration of the uClibc C library |
| (if uClibc is selected). The default options are usually |
| fine. However, if you really need to specifically customize the |
| configuration of your uClibc C library, you can pass a specific |
| configuration file here. Or alternatively, you can run the +make |
| uclibc-menuconfig+ command to get access to uClibc's configuration |
| interface. Note 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. |
| |
| * Change the version of the GCC compiler and binutils. |
| |
| * Select a number of toolchain options (uClibc only): whether the |
| toolchain should have largefile support (i.e support for files |
| larger than 2 GB on 32 bits systems), IPv6 support, RPC support |
| (used mainly for NFS), wide-char support, locale support (for |
| internationalization), C++ support, 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. |
| |
| 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_. |
| |
| [[external-toolchain-backend]] |
| External toolchain backend |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| 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 |
| from ADI], http://git.xilinx.com/[Xilinx toolchains for Microblaze], |
| etc.) and is capable of downloading them automatically, or it can be |
| pointed to a custom toolchain, either available for download or |
| installed locally. |
| |
| 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 |
| useful for toolchains generated using crosstool-NG. 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 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++. At the beginning of the execution, Buildroot will tell you if |
| 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. |
| |
| We do not support toolchains from the |
| http://www.denx.de/wiki/DULG/ELDK[ELDK] of Denx, for two reasons: |
| |
| * The ELDK does not contain a pure toolchain (i.e just the compiler, |
| binutils, the C and C++ libraries), but a toolchain that comes 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. |
| |
| * The ELDK toolchains have a completely non-standard custom mechanism |
| to handle multiple library variants. Instead of using the standard |
| GCC 'multilib' mechanism, the ARM ELDK uses different symbolic links |
| to the compiler to differentiate between library variants (for ARM |
| soft-float and ARM VFP), and the PowerPC ELDK compiler uses a |
| +CROSS_COMPILE+ environment variable. This non-standard behaviour |
| makes it difficult to support ELDK in Buildroot. |
| |
| We also do not support using the distribution toolchain (i.e the |
| gcc/binutils/C library installed by your distribution) as the |
| toolchain to build software for the target. This is because your |
| distribution toolchain is not a "pure" toolchain (i.e only with the |
| 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 |
| be used as an external toolchain in Buildroot, our recommandation is |
| 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. |
| |
| [[crosstool-ng-toolchain-backend]] |
| Crosstool-NG toolchain backend |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| The _Crosstool-NG toolchain backend_ integrates the |
| http://crosstool-ng.org[Crosstool-NG] project with |
| Buildroot. Crosstool-NG is a highly-configurable, versatile and |
| well-maintained tool to build cross-compilation toolchains. |
| |
| If you select the +Crosstool-NG toolchain+ option in +Toolchain Type+, |
| then you will be offered to: |
| |
| * Choose which C library you want to use. Crosstool-NG supports the |
| three most important C libraries used in Linux systems: glibc, |
| eglibc and uClibc |
| |
| * Choose a custom Crosstool-NG configuration file. Buildroot has its |
| own default configuration file (one per C library choice), but you |
| can provide your own. Another option is to run +make |
| ctng-menuconfig+ to get access to the Crosstool-NG configuration |
| interface. However, note that all Buildroot packages have only been |
| tested with the default Crosstool-NG configurations. |
| |
| * Choose a number of toolchain options (rather limited if glibc or |
| eglibc are used, or numerous if uClibc is used) |
| |
| When you will start the Buildroot build process, Buildroot will |
| download and install the Crosstool-NG tool, build and install its |
| required dependencies, and then run Crosstool-NG with the provided |
| configuration. |
| |
| Advantages of this backend: |
| |
| * Not limited to uClibc: glibc and eglibc are supported. |
| |
| * Vast possibilities of toolchain configuration. |
| |
| Drawbacks of this backend: |
| |
| * Crosstool-NG is not perfectly integrated with Buildroot. For |
| example, Crosstool-NG has its own download infrastructure, not |
| integrated with the one in Buildroot (for example a Buildroot +make |
| source+ will not download all the source code tarballs needed by |
| Crosstool-NG). |
| |
| * The toolchain is completely rebuilt from scratch if you do a +make |
| clean+. |
| |
| /dev management |
| ~~~~~~~~~~~~~~~ |
| |
| 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 |
| (i.e they persist accross reboots), and there is nothing that will |
| 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 |
| system. This filesystem is not persistent accross reboots: it is |
| 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 |
| responsability to enable those two options (if you fail to do so, |
| your Buildroot system will not boot). |
| |
| * The third solution is *Dynamic using 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 |
| http://git.busybox.net/busybox/tree/docs/mdev.txt. |
| |
| * The fourth solution is *Dynamic using udev*. This method also |
| relies on the _devtmpfs_ virtual filesystem detailed above, but |
| adds the +udev+ userspace daemon on top of it. +udev+ 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 |
| and is sometimes mandatory for some system components (systemd for |
| example). +udev+ is the mechanism used in most desktop Linux |
| distributions. For more details about +udev+, see |
| http://en.wikipedia.org/wiki/Udev. |
| |
| The Buildroot developers recommandation is to start with the *Dynamic |
| using devtmpfs only* solution, until you have the need for userspace |
| to be notified when devices are added/removed, or if firmwares are |
| needed, in which case *Dynamic using mdev* is usually a good solution. |
| |
| init system |
| ~~~~~~~~~~~ |
| |
| 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+: |
| |
| * The first solution is *Busybox*. Amongst many programs, Busybox has |
| an implementation of a basic +init+ program, which is sufficient |
| for most embedded systems. Enabling the +BR2_INIT_BUSYBOX+ will |
| ensure Busybox will build and install its +init+ program. This is |
| the default solution in Buildroot. The Busybox +init+ program will |
| 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 |
| Busybox +inittab+ syntax is special: do not use a random +inittab+ |
| documentation from the Internet to learn about Busybox |
| +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 |
| one from Busybox). The default +inittab+ installed with this init |
| 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+ |
| brings a fairly big number of large dependencies: +dbus+, +glib+ |
| 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 |
| *Busybox init* as it is sufficient for most embedded |
| systems. *systemd* can be used for more complex situations. |