docs/manual/using.txt

   1 // -*- mode:doc; -*-
   2
   3 Using Buildroot
   4 ---------------
   5
   6 Buildroot has a nice configuration tool similar to the one you can
   7 find in the http://www.kernel.org/[Linux kernel] or in
   8 http://www.busybox.net/[Busybox]. Note that you can *and should build
   9 everything as a normal user*. There is no need to be root to configure
  10 and use Buildroot. The first step is to run the configuration
  11 assistant:
  12
  13 --------------------
  14  $ make menuconfig
  15 --------------------
  16
  17 to run the curses-based configurator, or
  18
  19 --------------------
  20  $ make xconfig
  21 --------------------
  22
  23 or
  24
  25 --------------------
  26  $ make gconfig
  27 --------------------
  28
  29 to run the Qt or GTK-based configurators.
  30
  31 All of these "make" commands will need to build a configuration
  32 utility (including the interface), so you may need to install
  33 "development" packages for relevant libraries used by the
  34 configuration utilities. Check xref:requirement[] to know what
  35 Buildroot needs, and specifically the xref:requirement-optional[optional requirements]
  36 to get the dependencies of your favorite interface.
  37
  38 For each menu entry in the configuration tool, you can find associated
  39 help that describes the purpose of the entry.
  40
  41 Once everything is configured, the configuration tool generates a
  42 +.config+ file that contains the description of your
  43 configuration. It will be used by the Makefiles to do what's needed.
  44
  45 Let's go:
  46
  47 --------------------
  48  $ make
  49 --------------------
  50
  51 You *should never* use +make -jN+ with Buildroot: it does not support
  52 'top-level parallel make'. Instead, use the +BR2_JLEVEL+ option to
  53 tell Buildroot to run each package compilation with +make -jN+.
  54
  55 The `make` command will generally perform the following steps:
  56
  57 * download source files (as required);
  58 * configure, build and install the cross-compiling toolchain using the
  59   appropriate toolchain backend, or simply import an external toolchain;
  60 * build/install selected target packages;
  61 * build a kernel image, if selected;
  62 * build a bootloader image, if selected;
  63 * create a root filesystem in selected formats.
  64
  65 Buildroot output is stored in a single directory, +output/+.
  66 This directory contains several subdirectories:
  67
  68 * +images/+ where all the images (kernel image, bootloader and root
  69   filesystem images) are stored.
  70
  71 * +build/+ where all the components except for the cross-compilation
  72   toolchain are built (this includes tools needed to run Buildroot on
  73   the host and packages compiled for the target). The +build/+
  74   directory contains one subdirectory for each of these components.
  75
  76 * +staging/+ which contains a hierarchy similar to a root filesystem
  77   hierarchy. This directory contains the installation of the
  78   cross-compilation toolchain and all the userspace packages selected
  79   for the target. However, this directory is 'not' intended to be
  80   the root filesystem for the target: it contains a lot of development
  81   files, unstripped binaries and libraries that make it far too big
  82   for an embedded system. These development files are used to compile
  83   libraries and applications for the target that depend on other
  84   libraries.
  85
  86 * +target/+ which contains 'almost' the complete root filesystem for
  87   the target: everything needed is present except the device files in
  88   +/dev/+ (Buildroot can't create them because Buildroot doesn't run
  89   as root and doesn't want to run as root). Also, it doesn't have the correct
  90   permissions (e.g. setuid for the busybox binary). Therefore, this directory
  91   *should not be used on your target*.  Instead, you should use one of
  92   the images built in the +images/+ directory. If you need an
  93   extracted image of the root filesystem for booting over NFS, then
  94   use the tarball image generated in +images/+ and extract it as
  95   root. Compared to +staging/+, +target/+ contains only the files and
  96   libraries needed to run the selected target applications: the
  97   development files (headers, etc.) are not present, the binaries are
  98   stripped.
  99
 100 * +host/+ contains the installation of tools compiled for the host
 101   that are needed for the proper execution of Buildroot, including the
 102   cross-compilation toolchain.
 103
 104 * +toolchain/+ contains the build directories for the various
 105   components of the cross-compilation toolchain.
 106
 107 These commands, +make menuconfig|gconfig|xconfig+ and +make+, are the
 108 basic ones that allow to easily and quickly generate images fitting
 109 your needs, with all the supports and applications you enabled.
 110
 111 More details about the "make" command usage are given in
 112 xref:make-tips[].