common-usage.txt 9.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270
  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_DL_DIR+ to override the directory in which
  66. Buildroot stores/retrieves downloaded files
  67. +
  68. Note that the Buildroot download directory can also be set from the
  69. configuration interface, so through the Buildroot +.config+ file; this
  70. is the recommended way of setting it.
  71. * +BR2_GRAPH_ALT+, if set and non-empty, to use an alternate color-scheme in
  72. build-time graphs
  73. * +BR2_GRAPH_OUT+ to set the filetype of generated graphs, either +pdf+ (the
  74. default), or +png+.
  75. * +BR2_GRAPH_DEPS_OPTS+ to pass extra options to the dependency graph; see
  76. xref:graph-depends[] for the accepted options
  77. * +BR2_GRAPH_DOT_OPTS+ is passed verbatim as options to the +dot+ utility to
  78. draw the dependency graph.
  79. An example that uses config files located in the toplevel directory and
  80. in your $HOME:
  81. --------------------
  82. $ make UCLIBC_CONFIG_FILE=uClibc.config BUSYBOX_CONFIG_FILE=$HOME/bb.config
  83. --------------------
  84. If you want to use a compiler other than the default +gcc+
  85. or +g+++ for building helper-binaries on your host, then do
  86. --------------------
  87. $ make HOSTCXX=g++-4.3-HEAD HOSTCC=gcc-4.3-HEAD
  88. --------------------
  89. === Dealing efficiently with filesystem images
  90. Filesystem images can get pretty big, depending on the filesystem you choose,
  91. the number of packages, whether you provisioned free space... Yet, some
  92. locations in the filesystems images may just be _empty_ (e.g. a long run of
  93. 'zeroes'); such a file is called a _sparse_ file.
  94. Most tools can handle sparse files efficiently, and will only store or write
  95. those parts of a sparse file that are not empty.
  96. For example:
  97. * +tar+ accepts the +-S+ option to tell it to only store non-zero blocks
  98. of sparse files:
  99. ** +tar cf archive.tar -S [files...]+ will efficiently store sparse files
  100. in a tarball
  101. ** +tar xf archive.tar -S+ will efficiently store sparse files extracted
  102. from a tarball
  103. * +cp+ accepts the +--sparse=WHEN+ option (+WHEN+ is one of +auto+,
  104. +never+ or +always+):
  105. ** +cp --sparse=always source.file dest.file+ will make +dest.file+ a
  106. sparse file if +source.file+ has long runs of zeroes
  107. Other tools may have similar options. Please consult their respective man
  108. pages.
  109. You can use sparse files if you need to store the filesystem images (e.g.
  110. to transfer from one machine to another), or if you need to send them (e.g.
  111. to the Q&A team).
  112. Note however that flashing a filesystem image to a device while using the
  113. sparse mode of +dd+ may result in a broken filesystem (e.g. the block bitmap
  114. of an ext2 filesystem may be corrupted; or, if you have sparse files in
  115. your filesystem, those parts may not be all-zeroes when read back). You
  116. should only use sparse files when handling files on the build machine, not
  117. when transferring them to an actual device that will be used on the target.
  118. === Graphing the dependencies between packages
  119. [[graph-depends]]
  120. One of Buildroot's jobs is to know the dependencies between packages,
  121. and make sure they are built in the right order. These dependencies
  122. can sometimes be quite complicated, and for a given system, it is
  123. often not easy to understand why such or such package was brought into
  124. the build by Buildroot.
  125. In order to help understanding the dependencies, and therefore better
  126. understand what is the role of the different components in your
  127. embedded Linux system, Buildroot is capable of generating dependency
  128. graphs.
  129. To generate a dependency graph of the full system you have compiled,
  130. simply run:
  131. ------------------------
  132. make graph-depends
  133. ------------------------
  134. You will find the generated graph in
  135. +output/graphs/graph-depends.pdf+.
  136. If your system is quite large, the dependency graph may be too complex
  137. and difficult to read. It is therefore possible to generate the
  138. dependency graph just for a given package:
  139. ------------------------
  140. make <pkg>-graph-depends
  141. ------------------------
  142. You will find the generated graph in
  143. +output/graph/<pkg>-graph-depends.pdf+.
  144. Note that the dependency graphs are generated using the +dot+ tool
  145. from the _Graphviz_ project, which you must have installed on your
  146. system to use this feature. In most distributions, it is available as
  147. the +graphviz+ package.
  148. By default, the dependency graphs are generated in the PDF
  149. format. However, by passing the +BR2_GRAPH_OUT+ environment variable, you
  150. can switch to other output formats, such as PNG, PostScript or
  151. SVG. All formats supported by the +-T+ option of the +dot+ tool are
  152. supported.
  153. --------------------------------
  154. BR2_GRAPH_OUT=svg make graph-depends
  155. --------------------------------
  156. The +graph-depends+ behaviour can be controlled by setting options in the
  157. +BR2_GRAPH_DEPS_OPTS+ environment variable. The accepted options are:
  158. * +--depth N+, +-d N+, to limit the dependency depth to +N+ levels. The
  159. default, +0+, means no limit.
  160. * +--transitive+, +--no-transitive+, to draw (or not) the transitive
  161. dependencies. The default is to not draw transitive dependencies.
  162. * +--colours R,T,H+, the comma-separated list of colours to draw the
  163. root package (+R+), the target packages (+T+) and the host packages
  164. (+H+). Defaults to: +lightblue,grey,gainsboro+
  165. --------------------------------
  166. BR2_GRAPH_DEPS_OPTS='-d 3 --no-transitive --colours=red,green,blue' make graph-depends
  167. --------------------------------
  168. === Graphing the build duration
  169. [[graph-duration]]
  170. When the build of a system takes a long time, it is sometimes useful
  171. to be able to understand which packages are the longest to build, to
  172. see if anything can be done to speed up the build. In order to help
  173. such build time analysis, Buildroot collects the build time of each
  174. step of each package, and allows to generate graphs from this data.
  175. To generate the build time graph after a build, run:
  176. ----------------
  177. make graph-build
  178. ----------------
  179. This will generate a set of files in +output/graphs+ :
  180. * +build.hist-build.pdf+, a histogram of the build time for each
  181. package, ordered in the build order.
  182. * +build.hist-duration.pdf+, a histogram of the build time for each
  183. package, ordered by duration (longest first)
  184. * +build.hist-name.pdf+, a histogram of the build time for each
  185. package, order by package name.
  186. * +build.pie-packages.pdf+, a pie chart of the build time per package
  187. * +build.pie-steps.pdf+, a pie chart of the global time spent in each
  188. step of the packages build process.
  189. This +graph-build+ target requires the Python Matplotlib and Numpy
  190. libraries to be installed (+python-matplotlib+ and +python-numpy+ on
  191. most distributions), and also the +argparse+ module if you're using a
  192. Python version older than 2.7 (+python-argparse+ on most
  193. distributions).
  194. By default, the output format for the graph is PDF, but a different
  195. format can be selected using the +BR2_GRAPH_OUT+ environment variable. The
  196. only other format supported is PNG:
  197. ----------------
  198. BR2_GRAPH_OUT=png make graph-build
  199. ----------------
  200. include::eclipse-integration.txt[]
  201. include::advanced.txt[]