docs/manual/quickstart.txt

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