1// -*- mode:doc; -*- 2// vim: set syntax=asciidoc: 3 4== General Buildroot usage 5 6include::make-tips.txt[] 7 8include::rebuilding-packages.txt[] 9 10=== Offline builds 11 12If you intend to do an offline build and just want to download 13all sources that you previously selected in the configurator 14('menuconfig', 'nconfig', 'xconfig' or 'gconfig'), then issue: 15 16-------------------- 17 $ make source 18-------------------- 19 20You can now disconnect or copy the content of your +dl+ 21directory to the build-host. 22 23=== Building out-of-tree 24 25As default, everything built by Buildroot is stored in the directory 26+output+ in the Buildroot tree. 27 28Buildroot also supports building out of tree with a syntax similar to 29the Linux kernel. To use it, add +O=<directory>+ to the make command 30line: 31 32-------------------- 33 $ make O=/tmp/build 34-------------------- 35 36Or: 37 38-------------------- 39 $ cd /tmp/build; make O=$PWD -C path/to/buildroot 40-------------------- 41 42All the output files will be located under +/tmp/build+. If the +O+ 43path does not exist, Buildroot will create it. 44 45*Note:* the +O+ path can be either an absolute or a relative path, but if it's 46passed as a relative path, it is important to note that it is interpreted 47relative to the main Buildroot source directory, *not* the current working 48directory. 49 50When using out-of-tree builds, the Buildroot +.config+ and temporary 51files are also stored in the output directory. This means that you can 52safely run multiple builds in parallel using the same source tree as 53long as they use unique output directories. 54 55For ease of use, Buildroot generates a Makefile wrapper in the output 56directory - so after the first run, you no longer need to pass +O=<...>+ 57and +-C <...>+, simply run (in the output directory): 58 59-------------------- 60 $ make <target> 61-------------------- 62 63[[env-vars]] 64 65=== Environment variables 66 67Buildroot also honors some environment variables, when they are passed 68to +make+ or set in the environment: 69 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. 75 + 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. 79 + 80* +BUSYBOX_CONFIG_FILE=<path/to/.config>+, path to 81 the BusyBox configuration file. 82 + 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. 86 + 87* +BR2_CCACHE_DIR+ to override the directory where 88 Buildroot stores the cached files when using ccache. 89 + 90* +BR2_DL_DIR+ to override the directory in which 91 Buildroot stores/retrieves downloaded files. 92 + 93 Note that the Buildroot download directory can also be set from the 94 configuration interface, so through the Buildroot +.config+ file. See 95 xref:download-location[] for more details on how you can set the download 96 directory. 97* +BR2_GRAPH_ALT+, if set and non-empty, to use an alternate color-scheme in 98 build-time graphs 99* +BR2_GRAPH_OUT+ to set the filetype of generated graphs, either +pdf+ (the 100 default), or +png+. 101* +BR2_GRAPH_DEPS_OPTS+ to pass extra options to the dependency graph; see 102 xref:graph-depends[] for the accepted options 103* +BR2_GRAPH_DOT_OPTS+ is passed verbatim as options to the +dot+ utility to 104 draw the dependency graph. 105* +BR2_GRAPH_SIZE_OPTS+ to pass extra options to the size graph; see 106 xref:graph-size[] for the acepted options 107 108An example that uses config files located in the toplevel directory and 109in your $HOME: 110 111-------------------- 112 $ make UCLIBC_CONFIG_FILE=uClibc.config BUSYBOX_CONFIG_FILE=$HOME/bb.config 113-------------------- 114 115If you want to use a compiler other than the default +gcc+ 116or +g+++ for building helper-binaries on your host, then do 117 118-------------------- 119 $ make HOSTCXX=g++-4.3-HEAD HOSTCC=gcc-4.3-HEAD 120-------------------- 121 122=== Dealing efficiently with filesystem images 123 124Filesystem images can get pretty big, depending on the filesystem you choose, 125the number of packages, whether you provisioned free space... Yet, some 126locations in the filesystems images may just be _empty_ (e.g. a long run of 127'zeroes'); such a file is called a _sparse_ file. 128 129Most tools can handle sparse files efficiently, and will only store or write 130those parts of a sparse file that are not empty. 131 132For example: 133 134* +tar+ accepts the +-S+ option to tell it to only store non-zero blocks 135 of sparse files: 136** +tar cf archive.tar -S [files...]+ will efficiently store sparse files 137 in a tarball 138** +tar xf archive.tar -S+ will efficiently store sparse files extracted 139 from a tarball 140 141* +cp+ accepts the +--sparse=WHEN+ option (+WHEN+ is one of +auto+, 142 +never+ or +always+): 143** +cp --sparse=always source.file dest.file+ will make +dest.file+ a 144 sparse file if +source.file+ has long runs of zeroes 145 146Other tools may have similar options. Please consult their respective man 147pages. 148 149You can use sparse files if you need to store the filesystem images (e.g. 150to transfer from one machine to another), or if you need to send them (e.g. 151to the Q&A team). 152 153Note however that flashing a filesystem image to a device while using the 154sparse mode of +dd+ may result in a broken filesystem (e.g. the block bitmap 155of an ext2 filesystem may be corrupted; or, if you have sparse files in 156your filesystem, those parts may not be all-zeroes when read back). You 157should only use sparse files when handling files on the build machine, not 158when transferring them to an actual device that will be used on the target. 159 160=== Details about packages 161 162[[package-details]] 163 164Buildroot can produce a JSON blurb that describes the set of enabled 165packages in the current configuration, together with their 166dependencies, licenses and other metadata. This JSON blurb is produced 167by using the +show-info+ make target: 168 169------------------------ 170make show-info 171------------------------ 172 173Buildroot can also produce details about packages as HTML and JSON 174output using the +pkg-stats+ make target. Amongst other things, these 175details include whether known CVEs (security vulnerabilities) affect 176the packages in your current configuration. It also shows if there is 177a newer upstream version for those packages. 178 179------------------------ 180make pkg-stats 181------------------------ 182 183=== Graphing the dependencies between packages 184 185[[graph-depends]] 186 187One of Buildroot's jobs is to know the dependencies between packages, 188and make sure they are built in the right order. These dependencies 189can sometimes be quite complicated, and for a given system, it is 190often not easy to understand why such or such package was brought into 191the build by Buildroot. 192 193In order to help understanding the dependencies, and therefore better 194understand what is the role of the different components in your 195embedded Linux system, Buildroot is capable of generating dependency 196graphs. 197 198To generate a dependency graph of the full system you have compiled, 199simply run: 200 201------------------------ 202make graph-depends 203------------------------ 204 205You will find the generated graph in 206+output/graphs/graph-depends.pdf+. 207 208If your system is quite large, the dependency graph may be too complex 209and difficult to read. It is therefore possible to generate the 210dependency graph just for a given package: 211 212------------------------ 213make <pkg>-graph-depends 214------------------------ 215 216You will find the generated graph in 217+output/graph/<pkg>-graph-depends.pdf+. 218 219Note that the dependency graphs are generated using the +dot+ tool 220from the _Graphviz_ project, which you must have installed on your 221system to use this feature. In most distributions, it is available as 222the +graphviz+ package. 223 224By default, the dependency graphs are generated in the PDF 225format. However, by passing the +BR2_GRAPH_OUT+ environment variable, you 226can switch to other output formats, such as PNG, PostScript or 227SVG. All formats supported by the +-T+ option of the +dot+ tool are 228supported. 229 230-------------------------------- 231BR2_GRAPH_OUT=svg make graph-depends 232-------------------------------- 233 234The +graph-depends+ behaviour can be controlled by setting options in the 235+BR2_GRAPH_DEPS_OPTS+ environment variable. The accepted options are: 236 237* +--depth N+, +-d N+, to limit the dependency depth to +N+ levels. The 238 default, +0+, means no limit. 239 240* +--stop-on PKG+, +-s PKG+, to stop the graph on the package +PKG+. 241 +PKG+ can be an actual package name, a glob, the keyword 'virtual' 242 (to stop on virtual packages), or the keyword 'host' (to stop on 243 host packages). The package is still present on the graph, but its 244 dependencies are not. 245 246* +--exclude PKG+, +-x PKG+, like +--stop-on+, but also omits +PKG+ from 247 the graph. 248 249* +--transitive+, +--no-transitive+, to draw (or not) the transitive 250 dependencies. The default is to not draw transitive dependencies. 251 252* +--colors R,T,H+, the comma-separated list of colors to draw the 253 root package (+R+), the target packages (+T+) and the host packages 254 (+H+). Defaults to: +lightblue,grey,gainsboro+ 255 256-------------------------------- 257BR2_GRAPH_DEPS_OPTS='-d 3 --no-transitive --colors=red,green,blue' make graph-depends 258-------------------------------- 259 260=== Graphing the build duration 261 262[[graph-duration]] 263 264When the build of a system takes a long time, it is sometimes useful 265to be able to understand which packages are the longest to build, to 266see if anything can be done to speed up the build. In order to help 267such build time analysis, Buildroot collects the build time of each 268step of each package, and allows to generate graphs from this data. 269 270To generate the build time graph after a build, run: 271 272---------------- 273make graph-build 274---------------- 275 276This will generate a set of files in +output/graphs+ : 277 278* +build.hist-build.pdf+, a histogram of the build time for each 279 package, ordered in the build order. 280 281* +build.hist-duration.pdf+, a histogram of the build time for each 282 package, ordered by duration (longest first) 283 284* +build.hist-name.pdf+, a histogram of the build time for each 285 package, order by package name. 286 287* +build.pie-packages.pdf+, a pie chart of the build time per package 288 289* +build.pie-steps.pdf+, a pie chart of the global time spent in each 290 step of the packages build process. 291 292This +graph-build+ target requires the Python Matplotlib and Numpy 293libraries to be installed (+python-matplotlib+ and +python-numpy+ on 294most distributions), and also the +argparse+ module if you're using a 295Python version older than 2.7 (+python-argparse+ on most 296distributions). 297 298By default, the output format for the graph is PDF, but a different 299format can be selected using the +BR2_GRAPH_OUT+ environment variable. The 300only other format supported is PNG: 301 302---------------- 303BR2_GRAPH_OUT=png make graph-build 304---------------- 305 306[[graph-size]] 307=== Graphing the filesystem size contribution of packages 308 309When your target system grows, it is sometimes useful to understand 310how much each Buildroot package is contributing to the overall root 311filesystem size. To help with such an analysis, Buildroot collects 312data about files installed by each package and using this data, 313generates a graph and CSV files detailing the size contribution of 314the different packages. 315 316To generate these data after a build, run: 317 318---------------- 319make graph-size 320---------------- 321 322This will generate: 323 324* +output/graphs/graph-size.pdf+, a pie chart of the contribution of 325 each package to the overall root filesystem size 326 327* +output/graphs/package-size-stats.csv+, a CSV file giving the size 328 contribution of each package to the overall root filesystem size 329 330* +output/graphs/file-size-stats.csv+, a CSV file giving the size 331 contribution of each installed file to the package it belongs, and 332 to the overall filesystem size. 333 334This +graph-size+ target requires the Python Matplotlib library to be 335installed (+python-matplotlib+ on most distributions), and also the 336+argparse+ module if you're using a Python version older than 2.7 337(+python-argparse+ on most distributions). 338 339Just like for the duration graph, a +BR2_GRAPH_OUT+ environment variable 340is supported to adjust the output file format. See xref:graph-depends[] 341for details about this environment variable. 342 343Additionally, one may set the environment variable +BR2_GRAPH_SIZE_OPTS+ 344to further control the generated graph. Accepted options are: 345 346* `--size-limit X`, `-l X`, will group all packages which individual 347 contribution is below `X` percent, to a single entry labelled _Others_ 348 in the graph. By default, `X=0.01`, which means packages each 349 contributing less than 1% are grouped under _Others_. Accepted values 350 are in the range `[0.0..1.0]`. 351 352* `--iec`, `--binary`, `--si`, `--decimal`, to use IEC (binary, powers 353 of 1024) or SI (decimal, powers of 1000; the default) prefixes. 354 355* `--biggest-first`, to sort packages in decreasing size order, rather 356 than in increasing size order. 357 358.Note 359The collected filesystem size data is only meaningful after a complete 360clean rebuild. Be sure to run +make clean all+ before using +make 361graph-size+. 362 363To compare the root filesystem size of two different Buildroot compilations, 364for example after adjusting the configuration or when switching to another 365Buildroot release, use the +size-stats-compare+ script. It takes two 366+file-size-stats.csv+ files (produced by +make graph-size+) as input. 367Refer to the help text of this script for more details: 368 369---------------- 370utils/size-stats-compare -h 371---------------- 372 373[[top-level-parallel-build]] 374=== Top-level parallel build 375 376.Note 377This section deals with a very experimental feature, which is known to 378break even in some non-unusual situations. Use at your own risk. 379 380Buildroot has always been capable of using parallel build on a per 381package basis: each package is built by Buildroot using +make -jN+ (or 382the equivalent invocation for non-make-based build systems). The level 383of parallelism is by default number of CPUs + 1, but it can be 384adjusted using the +BR2_JLEVEL+ configuration option. 385 386Until 2020.02, Buildroot was however building packages in a serial 387fashion: each package was built one after the other, without 388parallelization of the build between packages. As of 2020.02, 389Buildroot has experimental support for *top-level parallel build*, 390which allows some signicant build time savings by building packages 391that have no dependency relationship in parallel. This feature is 392however marked as experimental and is known not to work in some cases. 393 394In order to use top-level parallel build, one must: 395 396. Enable the option +BR2_PER_PACKAGE_DIRECTORIES+ in the Buildroot 397configuration 398 399. Use +make -jN+ when starting the Buildroot build 400 401Internally, the +BR2_PER_PACKAGE_DIRECTORIES+ will enable a mechanism 402called *per-package directories*, which will have the following 403effects: 404 405* Instead of a global _target_ directory and a global _host_ directory 406 common to all packages, per-package _target_ and _host_ directories 407 will be used, in +$(O)/per-package/<pkg>/target/+ and 408 +$(O)/per-package/<pkg>/host/+ respectively. Those folders will be 409 populated from the corresponding folders of the package dependencies 410 at the beginning of +<pkg>+ build. The compiler and all other tools 411 will therefore only be able to see and access files installed by 412 dependencies explicitly listed by +<pkg>+. 413 414* At the end of the build, the global _target_ and _host_ directories 415 will be populated, located in +$(O)/target+ and +$(O)/host+ 416 respectively. This means that during the build, those folders will 417 be empty and it's only at the very end of the build that they will 418 be populated. 419 420include::eclipse-integration.txt[] 421 422include::advanced.txt[] 423