buildrootschalter/docs/manual/configure.txt

// -*- mode:doc -*- ;

[[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.

/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.