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 7is no need to be root to configure and use Buildroot. By running all 8commands as a regular user, you protect your system against packages 9behaving badly during compilation and installation. 10 11The first step when using Buildroot is to create a configuration. 12Buildroot has a nice configuration tool similar to the one you can 13find in the http://www.kernel.org/[Linux kernel] or in 14http://www.busybox.net/[BusyBox]. 15 16From the buildroot directory, run 17 18-------------------- 19 $ make menuconfig 20-------------------- 21 22for the original curses-based configurator, or 23 24-------------------- 25 $ make nconfig 26-------------------- 27 28for the new curses-based configurator, or 29 30-------------------- 31 $ make xconfig 32-------------------- 33 34for the Qt-based configurator, or 35 36-------------------- 37 $ make gconfig 38-------------------- 39 40for the GTK-based configurator. 41 42All of these "make" commands will need to build a configuration 43utility (including the interface), so you may need to install 44"development" packages for relevant libraries used by the 45configuration utilities. Refer to xref:requirement[] for more details, 46specifically the xref:requirement-optional[optional requirements] 47to get the dependencies of your favorite interface. 48 49For each menu entry in the configuration tool, you can find associated 50help that describes the purpose of the entry. Refer to xref:configure[] 51for details on some specific configuration aspects. 52 53Once everything is configured, the configuration tool generates a 54+.config+ file that contains the entire configuration. This file will be 55read by the top-level Makefile. 56 57To start the build process, simply run: 58 59-------------------- 60 $ make 61-------------------- 62 63By default, Buildroot does not support top-level parallel build, so 64running +make -jN+ is not necessary. There is however experimental 65support for top-level parallel build, see 66xref:top-level-parallel-build[]. 67 68The `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 78Buildroot output is stored in a single directory, +output/+. 79This 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* +host/+ contains both the tools built for the host, and the sysroot 91 of the target toolchain. The former is an installation of tools 92 compiled for the host that are needed for the proper execution of 93 Buildroot, including the cross-compilation toolchain. The latter 94 is a hierarchy similar to a root filesystem hierarchy. It contains 95 the headers and libraries of all user-space packages that provide 96 and install libraries used by other packages. However, this 97 directory is 'not' intended to be the root filesystem for the target: 98 it contains a lot of development files, unstripped binaries and 99 libraries that make it far too big for an embedded system. These 100 development files are used to compile libraries and applications for 101 the target that depend on other libraries. 102 103* +staging/+ is a symlink to the target toolchain sysroot inside 104 +host/+, which exists for backwards compatibility. 105 106* +target/+ which contains 'almost' the complete root filesystem for 107 the target: everything needed is present except the device files in 108 +/dev/+ (Buildroot can't create them because Buildroot doesn't run 109 as root and doesn't want to run as root). Also, it doesn't have the correct 110 permissions (e.g. setuid for the busybox binary). Therefore, this directory 111 *should not be used on your target*. Instead, you should use one of 112 the images built in the +images/+ directory. If you need an 113 extracted image of the root filesystem for booting over NFS, then 114 use the tarball image generated in +images/+ and extract it as 115 root. Compared to +staging/+, +target/+ contains only the files and 116 libraries needed to run the selected target applications: the 117 development files (headers, etc.) are not present, the binaries are 118 stripped. 119 120These commands, +make menuconfig|nconfig|gconfig|xconfig+ and +make+, are the 121basic ones that allow to easily and quickly generate images fitting 122your needs, with all the features and applications you enabled. 123 124More details about the "make" command usage are given in 125xref:make-tips[]. 126