common-usage.txt 15 KB

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