docs/manual/common-usage.txt

   1 // -*- mode:doc; -*-
   2 // vim: set syntax=asciidoc:
   3
   4 == General Buildroot usage
   5
   6 include::make-tips.txt[]
   7
   8 include::rebuilding-packages.txt[]
   9
  10 === Offline builds
  11
  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:
  15
  16 --------------------
  17  $ make source
  18 --------------------
  19
  20 You can now disconnect or copy the content of your +dl+
  21 directory to the build-host.
  22
  23 === Building out-of-tree
  24
  25 As default, everything built by Buildroot is stored in the directory
  26 +output+ in the Buildroot tree.
  27
  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
  30 line:
  31
  32 --------------------
  33  $ make O=/tmp/build
  34 --------------------
  35
  36 Or:
  37
  38 --------------------
  39  $ cd /tmp/build; make O=$PWD -C path/to/buildroot
  40 --------------------
  41
  42 All the output files will be located under +/tmp/build+. If the +O+
  43 path 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
  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
  48 directory.
  49
  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.
  54
  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):
  58
  59 --------------------
  60  $ make <target>
  61 --------------------
  62
  63 [[env-vars]]
  64
  65 === Environment variables
  66
  67 Buildroot also honors some environment variables, when they are passed
  68 to +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; this
  95   is the recommended way of setting it.
  96 * +BR2_GRAPH_ALT+, if set and non-empty, to use an alternate color-scheme in
  97   build-time graphs
  98 * +BR2_GRAPH_OUT+ to set the filetype of generated graphs, either +pdf+ (the
  99   default), or +png+.
 100 * +BR2_GRAPH_DEPS_OPTS+ to pass extra options to the dependency graph; see
 101   xref:graph-depends[] for the accepted options
 102 * +BR2_GRAPH_DOT_OPTS+ is passed verbatim as options to the +dot+ utility to
 103   draw the dependency graph.
 104
 105 An example that uses config files located in the toplevel directory and
 106 in your $HOME:
 107
 108 --------------------
 109  $ make UCLIBC_CONFIG_FILE=uClibc.config BUSYBOX_CONFIG_FILE=$HOME/bb.config
 110 --------------------
 111
 112 If you want to use a compiler other than the default +gcc+
 113 or +g+++ for building helper-binaries on your host, then do
 114
 115 --------------------
 116  $ make HOSTCXX=g++-4.3-HEAD HOSTCC=gcc-4.3-HEAD
 117 --------------------
 118
 119 === Dealing efficiently with filesystem images
 120
 121 Filesystem images can get pretty big, depending on the filesystem you choose,
 122 the number of packages, whether you provisioned free space... Yet, some
 123 locations in the filesystems images may just be _empty_ (e.g. a long run of
 124 'zeroes'); such a file is called a _sparse_ file.
 125
 126 Most tools can handle sparse files efficiently, and will only store or write
 127 those parts of a sparse file that are not empty.
 128
 129 For example:
 130
 131 * +tar+ accepts the +-S+ option to tell it to only store non-zero blocks
 132   of sparse files:
 133 ** +tar cf archive.tar -S [files...]+ will efficiently store sparse files
 134    in a tarball
 135 ** +tar xf archive.tar -S+ will efficiently store sparse files extracted
 136    from a tarball
 137
 138 * +cp+ accepts the +--sparse=WHEN+ option (+WHEN+ is one of +auto+,
 139   +never+ or +always+):
 140 ** +cp --sparse=always source.file dest.file+ will make +dest.file+ a
 141    sparse file if +source.file+ has long runs of zeroes
 142
 143 Other tools may have similar options. Please consult their respective man
 144 pages.
 145
 146 You can use sparse files if you need to store the filesystem images (e.g.
 147 to transfer from one machine to another), or if you need to send them (e.g.
 148 to the Q&A team).
 149
 150 Note however that flashing a filesystem image to a device while using the
 151 sparse mode of +dd+ may result in a broken filesystem (e.g. the block bitmap
 152 of an ext2 filesystem may be corrupted; or, if you have sparse files in
 153 your filesystem, those parts may not be all-zeroes when read back). You
 154 should only use sparse files when handling files on the build machine, not
 155 when transferring them to an actual device that will be used on the target.
 156
 157 === Graphing the dependencies between packages
 158
 159 [[graph-depends]]
 160
 161 One of Buildroot's jobs is to know the dependencies between packages,
 162 and make sure they are built in the right order. These dependencies
 163 can sometimes be quite complicated, and for a given system, it is
 164 often not easy to understand why such or such package was brought into
 165 the build by Buildroot.
 166
 167 In order to help understanding the dependencies, and therefore better
 168 understand what is the role of the different components in your
 169 embedded Linux system, Buildroot is capable of generating dependency
 170 graphs.
 171
 172 To generate a dependency graph of the full system you have compiled,
 173 simply run:
 174
 175 ------------------------
 176 make graph-depends
 177 ------------------------
 178
 179 You will find the generated graph in
 180 +output/graphs/graph-depends.pdf+.
 181
 182 If your system is quite large, the dependency graph may be too complex
 183 and difficult to read. It is therefore possible to generate the
 184 dependency graph just for a given package:
 185
 186 ------------------------
 187 make <pkg>-graph-depends
 188 ------------------------
 189
 190 You will find the generated graph in
 191 +output/graph/<pkg>-graph-depends.pdf+.
 192
 193 Note that the dependency graphs are generated using the +dot+ tool
 194 from the _Graphviz_ project, which you must have installed on your
 195 system to use this feature. In most distributions, it is available as
 196 the +graphviz+ package.
 197
 198 By default, the dependency graphs are generated in the PDF
 199 format. However, by passing the +BR2_GRAPH_OUT+ environment variable, you
 200 can switch to other output formats, such as PNG, PostScript or
 201 SVG. All formats supported by the +-T+ option of the +dot+ tool are
 202 supported.
 203
 204 --------------------------------
 205 BR2_GRAPH_OUT=svg make graph-depends
 206 --------------------------------
 207
 208 The +graph-depends+ behaviour can be controlled by setting options in the
 209 +BR2_GRAPH_DEPS_OPTS+ environment variable. The accepted options are:
 210
 211 * +--depth N+, +-d N+, to limit the dependency depth to +N+ levels. The
 212   default, +0+, means no limit.
 213
 214 * +--stop-on PKG+, +-s PKG+, to stop the graph on the package +PKG+.
 215   +PKG+ can be an actual package name, a glob, or the keyword 'virtual'
 216   (to stop on virtual packages). The package is still present on the
 217   graph, but its dependencies are not.
 218
 219 * +--exclude PKG+, +-x PKG+, like +--stop-on+, but also omits +PKG+ from
 220   the graph.
 221
 222 * +--transitive+, +--no-transitive+, to draw (or not) the transitive
 223   dependencies. The default is to not draw transitive dependencies.
 224
 225 * +--colours R,T,H+, the comma-separated list of colours to draw the
 226   root package (+R+), the target packages (+T+) and the host packages
 227   (+H+). Defaults to: +lightblue,grey,gainsboro+
 228
 229 --------------------------------
 230 BR2_GRAPH_DEPS_OPTS='-d 3 --no-transitive --colours=red,green,blue' make graph-depends
 231 --------------------------------
 232
 233 === Graphing the build duration
 234
 235 [[graph-duration]]
 236
 237 When the build of a system takes a long time, it is sometimes useful
 238 to be able to understand which packages are the longest to build, to
 239 see if anything can be done to speed up the build. In order to help
 240 such build time analysis, Buildroot collects the build time of each
 241 step of each package, and allows to generate graphs from this data.
 242
 243 To generate the build time graph after a build, run:
 244
 245 ----------------
 246 make graph-build
 247 ----------------
 248
 249 This will generate a set of files in +output/graphs+ :
 250
 251 * +build.hist-build.pdf+, a histogram of the build time for each
 252   package, ordered in the build order.
 253
 254 * +build.hist-duration.pdf+, a histogram of the build time for each
 255   package, ordered by duration (longest first)
 256
 257 * +build.hist-name.pdf+, a histogram of the build time for each
 258   package, order by package name.
 259
 260 * +build.pie-packages.pdf+, a pie chart of the build time per package
 261
 262 * +build.pie-steps.pdf+, a pie chart of the global time spent in each
 263   step of the packages build process.
 264
 265 This +graph-build+ target requires the Python Matplotlib and Numpy
 266 libraries to be installed (+python-matplotlib+ and +python-numpy+ on
 267 most distributions), and also the +argparse+ module if you're using a
 268 Python version older than 2.7 (+python-argparse+ on most
 269 distributions).
 270
 271 By default, the output format for the graph is PDF, but a different
 272 format can be selected using the +BR2_GRAPH_OUT+ environment variable. The
 273 only other format supported is PNG:
 274
 275 ----------------
 276 BR2_GRAPH_OUT=png make graph-build
 277 ----------------
 278
 279 === Graphing the filesystem size contribution of packages
 280
 281 When your target system grows, it is sometimes useful to understand
 282 how much each Buildroot package is contributing to the overall root
 283 filesystem size. To help with such an analysis, Buildroot collects
 284 data about files installed by each package and using this data,
 285 generates a graph and CSV files detailing the size contribution of
 286 the different packages.
 287
 288 To generate these data after a build, run:
 289
 290 ----------------
 291 make graph-size
 292 ----------------
 293
 294 This will generate:
 295
 296 * +output/graphs/graph-size.pdf+, a pie chart of the contribution of
 297   each package to the overall root filesystem size
 298
 299 * +output/graphs/package-size-stats.csv+, a CSV file giving the size
 300   contribution of each package to the overall root filesystem size
 301
 302 * +output/graphs/file-size-stats.csv+, a CSV file giving the size
 303   contribution of each installed file to the package it belongs, and
 304   to the overall filesystem size.
 305
 306 This +graph-size+ target requires the Python Matplotlib library to be
 307 installed (+python-matplotlib+ on most distributions), and also the
 308 +argparse+ module if you're using a Python version older than 2.7
 309 (+python-argparse+ on most distributions).
 310
 311 Just like for the duration graph, a +BR2_GRAPH_OUT+ environment is
 312 supported to adjust the output file format. See xref:graph-depends[]
 313 for details about this environment variable.
 314
 315 .Note
 316 The collected filesystem size data is only meaningful after a complete
 317 clean rebuild. Be sure to run +make clean all+ before using +make
 318 graph-size+.
 319
 320 include::eclipse-integration.txt[]
 321
 322 include::advanced.txt[]