kumquat-buildroot/docs/manual/using.txt

120 lines
4.5 KiB
Plaintext
Raw Normal View History

// -*- 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
--------------------
or
--------------------
$ make nconfig
--------------------
to run the old or new 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|nconfig|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[].