2 // vim: set syntax=asciidoc:
4 == General Buildroot usage
6 include::make-tips.txt[]
8 include::rebuilding-packages.txt[]
12 If you intend to do an offline build and just want to download
13 all sources that you previously selected in the configurator
14 ('menuconfig', 'nconfig', 'xconfig' or 'gconfig'), then issue:
20 You can now disconnect or copy the content of your +dl+
21 directory to the build-host.
23 === Building out-of-tree
25 As default, everything built by Buildroot is stored in the directory
26 +output+ in the Buildroot tree.
28 Buildroot also supports building out of tree with a syntax similar to
29 the Linux kernel. To use it, add +O=<directory>+ to the make command
39 $ cd /tmp/build; make O=$PWD -C path/to/buildroot
42 All the output files will be located under +/tmp/build+. If the +O+
43 path does not exist, Buildroot will create it.
45 *Note:* the +O+ path can be either an absolute or a relative path, but if it's
46 passed as a relative path, it is important to note that it is interpreted
47 relative to the main Buildroot source directory, *not* the current working
50 When using out-of-tree builds, the Buildroot +.config+ and temporary
51 files are also stored in the output directory. This means that you can
52 safely run multiple builds in parallel using the same source tree as
53 long as they use unique output directories.
55 For ease of use, Buildroot generates a Makefile wrapper in the output
56 directory - so after the first run, you no longer need to pass +O=<...>+
57 and +-C <...>+, simply run (in the output directory):
65 === Environment variables
67 Buildroot also honors some environment variables, when they are passed
68 to +make+ or set in the environment:
70 * +HOSTCXX+, the host C++ compiler to use
71 * +HOSTCC+, the host C compiler to use
72 * +UCLIBC_CONFIG_FILE=<path/to/.config>+, path to
73 the uClibc configuration file, used to compile uClibc, if an
74 internal toolchain is being built.
76 Note that the uClibc configuration file can also be set from the
77 configuration interface, so through the Buildroot +.config+ file; this
78 is the recommended way of setting it.
80 * +BUSYBOX_CONFIG_FILE=<path/to/.config>+, path to
81 the BusyBox configuration file.
83 Note that the BusyBox configuration file can also be set from the
84 configuration interface, so through the Buildroot +.config+ file; this
85 is the recommended way of setting it.
87 * +BR2_DL_DIR+ to override the directory in which
88 Buildroot stores/retrieves downloaded files
90 Note that the Buildroot download directory can also be set from the
91 configuration interface, so through the Buildroot +.config+ file; this
92 is the recommended way of setting it.
93 * +BR2_GRAPH_ALT+, if set and non-empty, to use an alternate color-scheme in
95 * +BR2_GRAPH_OUT+ to set the filetype of generated graphs, either +pdf+ (the
97 * +BR2_GRAPH_DEPS_OPTS+ to pass extra options to the dependency graph; see
98 xref:graph-depends[] for the accepted options
99 * +BR2_GRAPH_DOT_OPTS+ is passed verbatim as options to the +dot+ utility to
100 draw the dependency graph.
102 An example that uses config files located in the toplevel directory and
106 $ make UCLIBC_CONFIG_FILE=uClibc.config BUSYBOX_CONFIG_FILE=$HOME/bb.config
109 If you want to use a compiler other than the default +gcc+
110 or +g+++ for building helper-binaries on your host, then do
113 $ make HOSTCXX=g++-4.3-HEAD HOSTCC=gcc-4.3-HEAD
116 === Dealing efficiently with filesystem images
118 Filesystem images can get pretty big, depending on the filesystem you choose,
119 the number of packages, whether you provisioned free space... Yet, some
120 locations in the filesystems images may just be _empty_ (e.g. a long run of
121 'zeroes'); such a file is called a _sparse_ file.
123 Most tools can handle sparse files efficiently, and will only store or write
124 those parts of a sparse file that are not empty.
128 * +tar+ accepts the +-S+ option to tell it to only store non-zero blocks
130 ** +tar cf archive.tar -S [files...]+ will efficiently store sparse files
132 ** +tar xf archive.tar -S+ will efficiently store sparse files extracted
135 * +cp+ accepts the +--sparse=WHEN+ option (+WHEN+ is one of +auto+,
136 +never+ or +always+):
137 ** +cp --sparse=always source.file dest.file+ will make +dest.file+ a
138 sparse file if +source.file+ has long runs of zeroes
140 Other tools may have similar options. Please consult their respective man
143 You can use sparse files if you need to store the filesystem images (e.g.
144 to transfer from one machine to another), or if you need to send them (e.g.
147 Note however that flashing a filesystem image to a device while using the
148 sparse mode of +dd+ may result in a broken filesystem (e.g. the block bitmap
149 of an ext2 filesystem may be corrupted; or, if you have sparse files in
150 your filesystem, those parts may not be all-zeroes when read back). You
151 should only use sparse files when handling files on the build machine, not
152 when transferring them to an actual device that will be used on the target.
154 === Graphing the dependencies between packages
158 One of Buildroot's jobs is to know the dependencies between packages,
159 and make sure they are built in the right order. These dependencies
160 can sometimes be quite complicated, and for a given system, it is
161 often not easy to understand why such or such package was brought into
162 the build by Buildroot.
164 In order to help understanding the dependencies, and therefore better
165 understand what is the role of the different components in your
166 embedded Linux system, Buildroot is capable of generating dependency
169 To generate a dependency graph of the full system you have compiled,
172 ------------------------
174 ------------------------
176 You will find the generated graph in
177 +output/graphs/graph-depends.pdf+.
179 If your system is quite large, the dependency graph may be too complex
180 and difficult to read. It is therefore possible to generate the
181 dependency graph just for a given package:
183 ------------------------
184 make <pkg>-graph-depends
185 ------------------------
187 You will find the generated graph in
188 +output/graph/<pkg>-graph-depends.pdf+.
190 Note that the dependency graphs are generated using the +dot+ tool
191 from the _Graphviz_ project, which you must have installed on your
192 system to use this feature. In most distributions, it is available as
193 the +graphviz+ package.
195 By default, the dependency graphs are generated in the PDF
196 format. However, by passing the +BR2_GRAPH_OUT+ environment variable, you
197 can switch to other output formats, such as PNG, PostScript or
198 SVG. All formats supported by the +-T+ option of the +dot+ tool are
201 --------------------------------
202 BR2_GRAPH_OUT=svg make graph-depends
203 --------------------------------
205 The +graph-depends+ behaviour can be controlled by setting options in the
206 +BR2_GRAPH_DEPS_OPTS+ environment variable. The accepted options are:
208 * +--depth N+, +-d N+, to limit the dependency depth to +N+ levels. The
209 default, +0+, means no limit.
211 * +--stop-on PKG+, +-s PKG+, to stop the graph on the package +PKG+.
212 +PKG+ can be an actual package name, a glob, or the keyword 'virtual'
213 (to stop on virtual packages). The package is still present on the
214 graph, but its dependencies are not.
216 * +--exclude PKG+, +-x PKG+, like +--stop-on+, but also omits +PKG+ from
219 * +--transitive+, +--no-transitive+, to draw (or not) the transitive
220 dependencies. The default is to not draw transitive dependencies.
222 * +--colours R,T,H+, the comma-separated list of colours to draw the
223 root package (+R+), the target packages (+T+) and the host packages
224 (+H+). Defaults to: +lightblue,grey,gainsboro+
226 --------------------------------
227 BR2_GRAPH_DEPS_OPTS='-d 3 --no-transitive --colours=red,green,blue' make graph-depends
228 --------------------------------
230 === Graphing the build duration
234 When the build of a system takes a long time, it is sometimes useful
235 to be able to understand which packages are the longest to build, to
236 see if anything can be done to speed up the build. In order to help
237 such build time analysis, Buildroot collects the build time of each
238 step of each package, and allows to generate graphs from this data.
240 To generate the build time graph after a build, run:
246 This will generate a set of files in +output/graphs+ :
248 * +build.hist-build.pdf+, a histogram of the build time for each
249 package, ordered in the build order.
251 * +build.hist-duration.pdf+, a histogram of the build time for each
252 package, ordered by duration (longest first)
254 * +build.hist-name.pdf+, a histogram of the build time for each
255 package, order by package name.
257 * +build.pie-packages.pdf+, a pie chart of the build time per package
259 * +build.pie-steps.pdf+, a pie chart of the global time spent in each
260 step of the packages build process.
262 This +graph-build+ target requires the Python Matplotlib and Numpy
263 libraries to be installed (+python-matplotlib+ and +python-numpy+ on
264 most distributions), and also the +argparse+ module if you're using a
265 Python version older than 2.7 (+python-argparse+ on most
268 By default, the output format for the graph is PDF, but a different
269 format can be selected using the +BR2_GRAPH_OUT+ environment variable. The
270 only other format supported is PNG:
273 BR2_GRAPH_OUT=png make graph-build
276 include::eclipse-integration.txt[]
278 include::advanced.txt[]