[Buildroot] Documentation improvements

[Buildroot] Documentation improvements

[Thomas Petazzoni]

Hello Samuel,

Here is a set of patches that add more details in the documentation
about /dev management, init systems and toolchain configuration, as
per our discussion a few days ago on IRC.

Besides adding information, I've also reorganized things a bit. I
think the "Embedded basics" subsection was really misplaced in "Going
further in Buildroot?s innards" section. Knowing the basics is really
not something that should be in the "Going further" part.

So what I've done is create a "Details of Buildroot configuration"
sub-section in the "Working with Buildroot" section (chapter 3), and
I've reorganized here the information coming from "Embedded
basics". I've removed a few things that are really not Buildroot
specific, and I've extended that with more details on toolchain, /dev
and init.

I also include some unrelated minor fixes to the documentation, as
separate patches.

Thanks!

Thomas

[Buildroot] [PATCH 1/7] docs/manual: add a new 'Details on Buildroot configuration' section

[Thomas Petazzoni]

As discussed with Samuel Martin, there are a few questions about some
Buildroot configuration aspects that come very often on the IRC
channel and on the mailing-list. Topics such as the /dev management
and init systems are often raised.

Therefore, this patch adds a new section that provides details about
the Buildroot configuration possibilities. It does not aim at
replacing the help text of each configuration option, but rather to
complement them by providing more background. Having those
informations in the manual will also make it easier for us to point
newcomers to the right place in the documentation when they have
questions.

Note that this section will replace the "Embedded basics" section that
comes way too late in the manual. This is done in a followup commit.

Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 docs/manual/configure.txt    |  151 ++++++++++++++++++++++++++++++++++++++++++
 docs/manual/working-with.txt |    2 +
 2 files changed, 153 insertions(+)
 create mode 100644 docs/manual/configure.txt

diff --git a/docs/manual/configure.txt b/docs/manual/configure.txt
new file mode 100644
index 0000000..2c7987d
--- /dev/null
+++ b/docs/manual/configure.txt
@@ -0,0 +1,151 @@
+// -*- 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.
diff --git a/docs/manual/working-with.txt b/docs/manual/working-with.txt
index 4ea9239..b62bacd 100644
--- a/docs/manual/working-with.txt
+++ b/docs/manual/working-with.txt
@@ -6,6 +6,8 @@ Working with Buildroot
 This section explains how you can customize Buildroot to fit your
 needs.
 
+include::configure.txt[]
+
 include::make-tips.txt[]
 
 include::customize.txt[]
-- 
1.7.9.5

[Buildroot] [PATCH 2/7] docs/manual: Slightly improve the introduction

[Thomas Petazzoni]

Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 docs/manual/introduction.txt |   15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/docs/manual/introduction.txt b/docs/manual/introduction.txt
index 9353f8c..a567cec 100644
--- a/docs/manual/introduction.txt
+++ b/docs/manual/introduction.txt
@@ -3,11 +3,16 @@
 About Buildroot
 ===============
 
-Buildroot provides a full-featured environment for cross-development.
-Buildroot is able to generate a cross-compilation toolchain, a root
-filesystem, a Linux kernel image and a bootloader for your target.
-Buildroot can be used for any combination of these options,
-independently.
+Buildroot is a tool that simplifies and automates the process of
+building a complete Linux system for an embedded system, using
+cross-compilation.
+
+In order to achieve this, Buildroot is able to generate a
+cross-compilation toolchain, a root filesystem, a Linux kernel image
+and a bootloader for your target. Buildroot can be used for any
+combination of these options, independently (you can for example use
+an existing cross-compilation toolchain, and build only your root
+filesystem with Buildroot).
 
 Buildroot is useful mainly for people working with embedded systems.
 Embedded systems often use processors that are not the regular x86
-- 
1.7.9.5

[Buildroot] [PATCH 3/7] docs/manual: add details on toolchain configuration

[Thomas Petazzoni]

This commit adds a new section

 Working with Buildroot
  -> Details in configuration
    -> Cross-compilation toolchain

that gives a lot of details about our three toolchain backends. It
takes some elements that were previously later in the manual in
"Embedded basics" and in "External toolchain" and combines them with
more details about internal backend and Crosstool-NG backend.

The "Embedded basics" section becomes empty and is therefore
removed. A few elements have been lost in the process, but they were
considered to not be really useful, especially located so far in the
manual.

Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 docs/manual/advanced.txt           |    2 -
 docs/manual/configure.txt          |  277 ++++++++++++++++++++++++++++++++++++
 docs/manual/embedded-basics.txt    |  112 ---------------
 docs/manual/external-toolchain.txt |   88 ------------
 docs/manual/going-further.txt      |    2 -
 5 files changed, 277 insertions(+), 204 deletions(-)
 delete mode 100644 docs/manual/embedded-basics.txt
 delete mode 100644 docs/manual/external-toolchain.txt

diff --git a/docs/manual/advanced.txt b/docs/manual/advanced.txt
index ba6574c..314d300 100644
--- a/docs/manual/advanced.txt
+++ b/docs/manual/advanced.txt
@@ -5,8 +5,6 @@ Advanced usage
 
 include::using-buildroot-toolchain.txt[]
 
-include::external-toolchain.txt[]
-
 include::ccache-support.txt[]
 
 include::download-location.txt[]
diff --git a/docs/manual/configure.txt b/docs/manual/configure.txt
index 2c7987d..65e0eeb 100644
--- a/docs/manual/configure.txt
+++ b/docs/manual/configure.txt
@@ -9,6 +9,283 @@ 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
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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 is limited to
+the usage of the http://www.uclibc.org[uClibc C library] (i.e, the
+_glibc_ and _eglibc_ C libraries are not supported by this backend,
+see the _External toolchain backend_ and _Crosstool-NG toolchain
+backend_ for solutions to use either _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. 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: 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_.
+* Limited to the _uClibc_ C library.
+
+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
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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
 ~~~~~~~~~~~~~~~
 
diff --git a/docs/manual/embedded-basics.txt b/docs/manual/embedded-basics.txt
deleted file mode 100644
index fdadf62..0000000
--- a/docs/manual/embedded-basics.txt
+++ /dev/null
@@ -1,112 +0,0 @@
-// -*- mode:doc; -*-
-
-Embedded system basics
-----------------------
-
-When developing an embedded system, there are a number of choices to
-address:
-
-* the cross-toolchain: target architecture/C library/...
-* the bootloader
-* kernel options
-* the device management
-* the init system
-* the package selection (busybox vs. "real" programs, ...)
-* ...
-
-Some of these may be influenced by the target hardware.
-
-Some of the choices may also add some constraints when you develop the
-final application for which your target is designed (e.g. some
-functions may be provided by some C libraries and missing in some
-others, ...). So, these choices should be carefully made.
-
-Buildroot allows you to set most of these options to fit your needs.
-
-Moreover, Buildroot provides an infrastructure for reproducing the
-build process of your kernel, cross-toolchain, and embedded root
-filesystem. Being able to reproduce the build process will be useful
-when a component needs to be patched or updated or when another person
-is supposed to take over the project.
-
-[[cross-compilation-and-cross-toolchain]]
-Cross-compilation & cross-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] or
-http://www.fefe.de/dietlibc/[dietlibc]).
-
-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.
-
-Even if your embedded system uses an x86 processor, you might be
-interested in Buildroot for two reasons:
-
-* The compilation toolchain on your host certainly uses the GNU Libc
-  which is a complete but huge C standard library. Instead of using
-  GNU Libc on your target system, you can use uClibc which is a tiny C
-  standard library. If you want to use this C library, then you need a
-  compilation toolchain to generate binaries linked with it. Buildroot
-  can do that for you.
-
-* Buildroot automates the building of a root filesystem with all
-  needed tools like busybox. That makes it much easier than doing it
-  by hand.
-
-You might wonder why such a tool is needed when you can compile +gcc+,
-+binutils+, +uClibc+ and all the other tools by hand. Of course doing
-so is possible, but dealing with all of the configure options and
-problems of every +gcc+ or +binutils+ version is very time-consuming
-and uninteresting.  Buildroot automates this process through the use
-of Makefiles and has a collection of patches for each +gcc+ and
-+binutils+ version to make them work on most architectures.
-
-Buildroot offers a number of options and settings that can be tuned
-when defining the cross-toolchain (refer to xref:toolchain-custom[]).
-
-[[bootloader]]
-Bootloader
-~~~~~~~~~~
-
-TODO
-
-[[device-management]]
-Device management
-~~~~~~~~~~~~~~~~~
-
-TODO
-
-[[init-system]]
-Init system
-~~~~~~~~~~~
-
-TODO
diff --git a/docs/manual/external-toolchain.txt b/docs/manual/external-toolchain.txt
deleted file mode 100644
index 6124fe4..0000000
--- a/docs/manual/external-toolchain.txt
+++ /dev/null
@@ -1,88 +0,0 @@
-// -*- mode:doc -*- ;
-
-[[external-toolchain]]
-Using an external toolchain
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Using an already existing toolchain is useful for different
-reasons:
-
-* you already have a toolchain that is known to work for your specific
-  CPU
-
-* you want to speed up the Buildroot build process by skipping the
-  long toolchain build part
-
-* the toolchain generation feature of Buildroot is not sufficiently
-  flexible for you (for example if you need to generate a system with
-  'glibc' instead of 'uClibc')
-
-Buildroot supports using existing toolchains through a mechanism
-called 'external toolchain'. The external toolchain mechanism is
-enabled in the +Toolchain+ menu, by selecting +External toolchain+ in
-+Toolchain type+.
-
-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.
diff --git a/docs/manual/going-further.txt b/docs/manual/going-further.txt
index 15324c4..070e0a3 100644
--- a/docs/manual/going-further.txt
+++ b/docs/manual/going-further.txt
@@ -3,8 +3,6 @@
 Going further in Buildroot's innards
 ====================================
 
-include::embedded-basics.txt[]
-
 include::how-buildroot-works.txt[]
 
 include::advanced.txt[]
-- 
1.7.9.5

[Buildroot] [PATCH 4/7] docs/manual: remove FAQ entry about 'depends on' vs. 'select'

[Thomas Petazzoni]

The FAQ is before the section on package development, and only covers
user issues, not developer issues, so the FAQ entry about 'depends on'
vs. 'select' really doesn't have its place here.

And the 'depends on' vs. 'select' issue is already covered in a later
section, see
http://buildroot.org/downloads/manual/manual.html#depends-on-vs-select.

Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 docs/manual/faq-troubleshooting.txt |   11 -----------
 1 file changed, 11 deletions(-)

diff --git a/docs/manual/faq-troubleshooting.txt b/docs/manual/faq-troubleshooting.txt
index 5a22702..5d9531b 100644
--- a/docs/manual/faq-troubleshooting.txt
+++ b/docs/manual/faq-troubleshooting.txt
@@ -89,17 +89,6 @@ If you need documentation data on your target anyway, then Buildroot
 is not suitable for your purpose, and you should look for a _real
 distribution_ (see: xref:faq-no-compiler-on-target[]).
 
-[[faq-depends-on-vs-select]]
-+Config.in+: _depends on_ vs _select_
--------------------------------------
-
-When adding a new package to Buildroot, you will most likely have to
-deal with expressing the dependencies of this package.
-
-In the +Config.in+ file, dependencies may be expressed following two
-semantics.
-See xref:depends-on-vs-select[choosing between _depends_ and _select_].
-
 [[faq-why-not-visible-package]]
 Why are some packages not visible in the Buildroot config menu?
 ---------------------------------------------------------------
-- 
1.7.9.5

[Buildroot] [PATCH 5/7] docs/manual: remove incorrect prerequites

[Thomas Petazzoni]

The development files for zlib or netpbm are not needed, and neither
is python-xcbgen. None of these are present in the chroot used in the
autobuilders, and anyway if those would be needed, it would be a
Buildroot bug and not something to be mentionned in the documentation.

Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 docs/manual/prerequisite.txt |    5 -----
 1 file changed, 5 deletions(-)

diff --git a/docs/manual/prerequisite.txt b/docs/manual/prerequisite.txt
index 17660b7..b8bc906 100644
--- a/docs/manual/prerequisite.txt
+++ b/docs/manual/prerequisite.txt
@@ -74,10 +74,5 @@ development context (further details: refer to xref:download-infra[]).
 ** +qt4+ to use the 'xconfig' interface
 ** +glib2+, +gtk2+ and +glade2+ to use the 'gconfig' interface
 
-* Development libraries:
-** +zlib1+
-** +netpbm10+ (for +fbtest+)
-** +python-xcbgen+ (for +Matchbox+ on Debian based system)
-
 * Documentation generation tools:
 ** +asciidoc+
-- 
1.7.9.5

[Buildroot] [PATCH 6/7] docs/manual: mention Java-related optional dependencies

[Thomas Petazzoni]

Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 docs/manual/prerequisite.txt |    5 +++++
 1 file changed, 5 insertions(+)

diff --git a/docs/manual/prerequisite.txt b/docs/manual/prerequisite.txt
index b8bc906..21e4627 100644
--- a/docs/manual/prerequisite.txt
+++ b/docs/manual/prerequisite.txt
@@ -74,5 +74,10 @@ development context (further details: refer to xref:download-infra[]).
 ** +qt4+ to use the 'xconfig' interface
 ** +glib2+, +gtk2+ and +glade2+ to use the 'gconfig' interface
 
+* Java-related packages, if the Java Classpath needs to be built for
+  the target system:
+** The +javac+ compiler
+** The +jar+ tool
+
 * Documentation generation tools:
 ** +asciidoc+
-- 
1.7.9.5

[Buildroot] [PATCH 7/7] docs/manual: do not suggest to create a symlink for shared download directory

[Thomas Petazzoni]

Creating a symbolic link for the download directory is really not a
useful suggestion, since we have the much better solution of the
BUILDROOT_DL_DIR environment variable. So emphasize this solution
instead, and remove the suggestion of the symbolic link.

Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 docs/manual/download-location.txt |   23 ++++++++---------------
 1 file changed, 8 insertions(+), 15 deletions(-)

diff --git a/docs/manual/download-location.txt b/docs/manual/download-location.txt
index 4befe0a..36a1356 100644
--- a/docs/manual/download-location.txt
+++ b/docs/manual/download-location.txt
@@ -3,25 +3,18 @@
 Location of downloaded packages
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The various tarballs that are downloaded by Buildroot are all stored in
-+DL_DIR+, which by default is the +dl+ directory. If you want
+The various tarballs that are downloaded by Buildroot are all stored
+in +BR2_DL_DIR+, which by default is the +dl+ directory. If you want
 to keep a complete version of Buildroot which is known to be working
 with the associated tarballs, you can make a copy of this directory.
-This will allow you to regenerate the toolchain and the target filesystem
-with exactly the same versions.
+This will allow you to regenerate the toolchain and the target
+filesystem with exactly the same versions.
 
 If you maintain several Buildroot trees, it might be better to have a
-shared download location. This can be accessed by creating a symbolic
-link from the +dl+ directory to the shared download location:
-
------------------
- $ ln -s <shared download location> dl
------------------
-
-Another way of accessing a shared download location is to create the
-+BUILDROOT_DL_DIR+ environment variable.  If this is set, then the
-value of DL_DIR in the project is overridden. The following line
-should be added to +<~/.bashrc>+.
+shared download location. This can be achieved by pointing the
++BUILDROOT_DL_DIR+ environment variable to a directory.  If this is
+set, then the value of +BR2_DL_DIR+ in the Buildroot configuration is
+overridden. The following line should be added to +<~/.bashrc>+.
 
 -----------------
  $ export BUILDROOT_DL_DIR <shared download location>
-- 
1.7.9.5

[Buildroot] Documentation improvements

[Samuel Martin]

Hi Thomas,

2012/12/29 Thomas Petazzoni <thomas.petazzoni@free-electrons.com>:
> Hello Samuel,
>
> Here is a set of patches that add more details in the documentation
> about /dev management, init systems and toolchain configuration, as
> per our discussion a few days ago on IRC.
>
> Besides adding information, I've also reorganized things a bit. I
> think the "Embedded basics" subsection was really misplaced in "Going
> further in Buildroot?s innards" section. Knowing the basics is really
> not something that should be in the "Going further" part.
>
> So what I've done is create a "Details of Buildroot configuration"
> sub-section in the "Working with Buildroot" section (chapter 3), and
> I've reorganized here the information coming from "Embedded
> basics". I've removed a few things that are really not Buildroot
> specific, and I've extended that with more details on toolchain, /dev
> and init.
>
> I also include some unrelated minor fixes to the documentation, as
> separate patches.

Great work! :-)

Thanks,

-- 
Samuel

[Buildroot] [PATCH 1/7] docs/manual: add a new 'Details on Buildroot configuration' section

[Samuel Martin]

Hi Thomas, all,

2012/12/29 Thomas Petazzoni <thomas.petazzoni@free-electrons.com>:
> As discussed with Samuel Martin, there are a few questions about some
> Buildroot configuration aspects that come very often on the IRC
> channel and on the mailing-list. Topics such as the /dev management
> and init systems are often raised.
>
> Therefore, this patch adds a new section that provides details about
> the Buildroot configuration possibilities. It does not aim at
> replacing the help text of each configuration option, but rather to
> complement them by providing more background. Having those
> informations in the manual will also make it easier for us to point
> newcomers to the right place in the documentation when they have
> questions.
>
> Note that this section will replace the "Embedded basics" section that
> comes way too late in the manual. This is done in a followup commit.
>
> Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
Acked-by: Samuel Martin <s.martin49@gmail.com>

Definitely, 2 new sections that should help a lot of people.

Regards,

-- 
Samuel

[Buildroot] [PATCH 2/7] docs/manual: Slightly improve the introduction

[Samuel Martin]

Hi Thomas, all,

2012/12/29 Thomas Petazzoni <thomas.petazzoni@free-electrons.com>:
> Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
Acked-by: Samuel Martin <s.martin49@gmail.com>

Regards,

-- 
Sam

[Buildroot] [PATCH 3/7] docs/manual: add details on toolchain configuration

[Samuel Martin]

Hi Thomas, all,

2012/12/29 Thomas Petazzoni <thomas.petazzoni@free-electrons.com>:
> This commit adds a new section
>
>  Working with Buildroot
>   -> Details in configuration
>     -> Cross-compilation toolchain
>
> that gives a lot of details about our three toolchain backends. It
> takes some elements that were previously later in the manual in
> "Embedded basics" and in "External toolchain" and combines them with
> more details about internal backend and Crosstool-NG backend.
>
> The "Embedded basics" section becomes empty and is therefore
> removed. A few elements have been lost in the process, but they were
> considered to not be really useful, especially located so far in the
> manual.
>
> Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
Acked-by: Samuel Martin <s.martin49@gmail.com>

Regards,

-- 
Sam

[Buildroot] [PATCH 4/7] docs/manual: remove FAQ entry about 'depends on' vs. 'select'

[Samuel Martin]

Hi Thomas, all,

2012/12/29 Thomas Petazzoni <thomas.petazzoni@free-electrons.com>:
> The FAQ is before the section on package development, and only covers
> user issues, not developer issues, so the FAQ entry about 'depends on'
> vs. 'select' really doesn't have its place here.
I agree.

>
> And the 'depends on' vs. 'select' issue is already covered in a later
> section, see
> http://buildroot.org/downloads/manual/manual.html#depends-on-vs-select.
>
> Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
Acked-by: Samuel Martin <s.martin49@gmail.com>

Regards,

-- 
Sam

[Buildroot] [PATCH 5/7] docs/manual: remove incorrect prerequites

[Samuel Martin]

Hi Thomas, all,

2012/12/29 Thomas Petazzoni <thomas.petazzoni@free-electrons.com>:
> The development files for zlib or netpbm are not needed, and neither
> is python-xcbgen. None of these are present in the chroot used in the
> autobuilders, and anyway if those would be needed, it would be a
> Buildroot bug and not something to be mentionned in the documentation.
>
> Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
Acked-by: Samuel Martin <s.martin49@gmail.com>

Regards,

-- 
Sam

[Buildroot] [PATCH 6/7] docs/manual: mention Java-related optional dependencies

[Samuel Martin]

Hi Thomas, all,

2012/12/29 Thomas Petazzoni <thomas.petazzoni@free-electrons.com>:
> Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
Acked-by: Samuel Martin <s.martin49@gmail.com>

Regards,

-- 
Sam

[Buildroot] [PATCH 7/7] docs/manual: do not suggest to create a symlink for shared download directory

[Samuel Martin]

Hi Thomas, all,

2012/12/29 Thomas Petazzoni <thomas.petazzoni@free-electrons.com>:
> Creating a symbolic link for the download directory is really not a
> useful suggestion, since we have the much better solution of the
> BUILDROOT_DL_DIR environment variable. So emphasize this solution
> instead, and remove the suggestion of the symbolic link.
>
> Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
Acked-by: Samuel Martin <s.martin49@gmail.com>

Regards,

-- 
Sam

[Buildroot] Documentation improvements

[Peter Korsgaard]

>>>>> "Thomas" == Thomas Petazzoni <thomas.petazzoni@free-electrons.com> writes:

 Thomas> Hello Samuel,
 Thomas> Here is a set of patches that add more details in the documentation
 Thomas> about /dev management, init systems and toolchain configuration, as
 Thomas> per our discussion a few days ago on IRC.

 Thomas> Besides adding information, I've also reorganized things a bit. I
 Thomas> think the "Embedded basics" subsection was really misplaced in "Going
 Thomas> further in Buildroot?s innards" section. Knowing the basics is really
 Thomas> not something that should be in the "Going further" part.

 Thomas> So what I've done is create a "Details of Buildroot configuration"
 Thomas> sub-section in the "Working with Buildroot" section (chapter 3), and
 Thomas> I've reorganized here the information coming from "Embedded
 Thomas> basics". I've removed a few things that are really not Buildroot
 Thomas> specific, and I've extended that with more details on toolchain, /dev
 Thomas> and init.

 Thomas> I also include some unrelated minor fixes to the documentation, as
 Thomas> separate patches.

Committed series, thanks.

-- 
Bye, Peter Korsgaard

[Buildroot] Documentation improvements

[Thomas Petazzoni]

Dear Samuel Martin,

On Sat, 29 Dec 2012 22:17:44 +0100, Samuel Martin wrote:

> Great work! :-)

Thanks for your review!

Thomas
-- 
Thomas Petazzoni, Free Electrons
Kernel, drivers, real-time and embedded Linux
development, consulting, training and support.
http://free-electrons.com