126 lines
4.9 KiB
Plaintext
126 lines
4.9 KiB
Plaintext
// -*- mode:doc; -*-
|
|
// vim: set syntax=asciidoc:
|
|
|
|
== Buildroot quick start
|
|
|
|
*Important*: you can and should *build everything as a normal user*. There
|
|
is no need to be root to configure and use Buildroot. By running all
|
|
commands as a regular user, you protect your system against packages
|
|
behaving badly during compilation and installation.
|
|
|
|
The first step when using Buildroot is to create a configuration.
|
|
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].
|
|
|
|
From the buildroot directory, run
|
|
|
|
--------------------
|
|
$ make menuconfig
|
|
--------------------
|
|
|
|
for the original curses-based configurator, or
|
|
|
|
--------------------
|
|
$ make nconfig
|
|
--------------------
|
|
|
|
for the new curses-based configurator, or
|
|
|
|
--------------------
|
|
$ make xconfig
|
|
--------------------
|
|
|
|
for the Qt-based configurator, or
|
|
|
|
--------------------
|
|
$ make gconfig
|
|
--------------------
|
|
|
|
for the GTK-based configurator.
|
|
|
|
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. Refer to xref:requirement[] for more details,
|
|
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. Refer to xref:configure[]
|
|
for details on some specific configuration aspects.
|
|
|
|
Once everything is configured, the configuration tool generates a
|
|
+.config+ file that contains the entire configuration. This file will be
|
|
read by the top-level Makefile.
|
|
|
|
To start the build process, simply run:
|
|
|
|
--------------------
|
|
$ make
|
|
--------------------
|
|
|
|
By default, Buildroot does not support top-level parallel build, so
|
|
running +make -jN+ is not necessary. There is however experimental
|
|
support for top-level parallel build, see
|
|
xref:top-level-parallel-build[].
|
|
|
|
The `make` command will generally perform the following steps:
|
|
|
|
* download source files (as required);
|
|
* configure, build and install the cross-compilation toolchain, or
|
|
simply import an external toolchain;
|
|
* configure, build and 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. These are the files you need to put
|
|
on your target system.
|
|
|
|
* +build/+ where all the components are built (this includes tools
|
|
needed by Buildroot on the host and packages compiled for the
|
|
target). This directory contains one subdirectory for each of these
|
|
components.
|
|
|
|
* +host/+ contains both the tools built for the host, and the sysroot
|
|
of the target toolchain. The former is an installation of tools
|
|
compiled for the host that are needed for the proper execution of
|
|
Buildroot, including the cross-compilation toolchain. The latter
|
|
is a hierarchy similar to a root filesystem hierarchy. It contains
|
|
the headers and libraries of all user-space packages that provide
|
|
and install libraries used by other packages. 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.
|
|
|
|
* +staging/+ is a symlink to the target toolchain sysroot inside
|
|
+host/+, which exists for backwards compatibility.
|
|
|
|
* +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.
|
|
|
|
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 features and applications you enabled.
|
|
|
|
More details about the "make" command usage are given in
|
|
xref:make-tips[].
|