| // -*- 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[]. |