kumquat-buildroot/docs/manual/using.txt

// -*- mode:doc; -*-
// vim: set syntax=asciidoc:

Using Buildroot
---------------

Buildroot has a nice configuration tool similar to the one you can
find in the http://www.kernel.org/[Linux kernel] or in
http://www.busybox.net/[Busybox]. Note that you can *and should build
everything as a normal user*. There is no need to be root to configure
and use Buildroot. The first step is to run the configuration
assistant:

--------------------
 $ make menuconfig
--------------------

to run the curses-based configurator, or

--------------------
 $ make xconfig
--------------------

or

--------------------
 $ make gconfig
--------------------

to run the Qt or GTK-based configurators.

All of these "make" commands will need to build a configuration
utility (including the interface), so you may need to install
"development" packages for relevant libraries used by the
configuration utilities. Check xref:requirement[] to know what
Buildroot needs, and specifically the xref:requirement-optional[optional requirements]
to get the dependencies of your favorite interface.

For each menu entry in the configuration tool, you can find associated
help that describes the purpose of the entry.

Once everything is configured, the configuration tool generates a
+.config+ file that contains the description of your
configuration. It will be used by the Makefiles to do what's needed.

Let's go:

--------------------
 $ make
--------------------

You *should never* use +make -jN+ with Buildroot: it does not support
'top-level parallel make'. Instead, use the +BR2_JLEVEL+ option to
tell Buildroot to run each package compilation with +make -jN+.

The `make` command will generally perform the following steps:

* download source files (as required);
* configure, build and install the cross-compiling toolchain using the
  appropriate toolchain backend, or simply import an external toolchain;
* build/install selected target packages;
* build a kernel image, if selected;
* build a bootloader image, if selected;
* create a root filesystem in selected formats.

Buildroot output is stored in a single directory, +output/+.
This directory contains several subdirectories:

* +images/+ where all the images (kernel image, bootloader and root
  filesystem images) are stored.

* +build/+ where all the components except for the cross-compilation
  toolchain are built (this includes tools needed to run Buildroot on
  the host and packages compiled for the target). The +build/+
  directory contains one subdirectory for each of these components.

* +staging/+ which contains a hierarchy similar to a root filesystem
  hierarchy. This directory contains the installation of the
  cross-compilation toolchain and all the userspace packages selected
  for the target. However, this directory is 'not' intended to be
  the root filesystem for the target: it contains a lot of development
  files, unstripped binaries and libraries that make it far too big
  for an embedded system. These development files are used to compile
  libraries and applications for the target that depend on other
  libraries.

* +target/+ which contains 'almost' the complete root filesystem for
  the target: everything needed is present except the device files in
  +/dev/+ (Buildroot can't create them because Buildroot doesn't run
  as root and doesn't want to run as root). Also, it doesn't have the correct
  permissions (e.g. setuid for the busybox binary). Therefore, this directory
  *should not be used on your target*.  Instead, you should use one of
  the images built in the +images/+ directory. If you need an
  extracted image of the root filesystem for booting over NFS, then
  use the tarball image generated in +images/+ and extract it as
  root. Compared to +staging/+, +target/+ contains only the files and
  libraries needed to run the selected target applications: the
  development files (headers, etc.) are not present, the binaries are
  stripped.

* +host/+ contains the installation of tools compiled for the host
  that are needed for the proper execution of Buildroot, including the
  cross-compilation toolchain.

* +toolchain/+ contains the build directories for the various
  components of the cross-compilation toolchain.

These commands, +make menuconfig|gconfig|xconfig+ and +make+, are the
basic ones that allow to easily and quickly generate images fitting
your needs, with all the supports and applications you enabled.

More details about the "make" command usage are given in
xref:make-tips[].