kumquat-buildroot/docs/manual/common-usage.txt
Thomas De Schampheleire 77007ad950 manual/user guide: high-level restructuring
This patch performs some additional restructuring of the manual,
specifically in the User Guide. In detail:

- Rename 'Daily use' to 'General Buildroot usage'
- Move chapters 'make tips', 'Eclipse integration', and 'Advanced usage' as
  sections under the 'General Buildroot usage' chapter.
- Rename 'Details on Buildroot configuration' into 'Buildroot configuration'
- Rework the 'Customization' section as follows:
  - Move the short section on debugging the external toolchain wrapper into
    the rest of the explanation on external toolchains.
  - Remove the now redundant section on toolchains, as this is already
    explained in much more detail in the 'Buildroot configuration' chapter.
  - Move the sections on busybox/uclibc/kernel configuration from chapter
    'Customization' into a separate chapter 'Configuration of other
    components'.
  - Rename the remaining part of the original 'Customization' chapter into
    'Project-specific customization' and fold it together with the next
    chapter 'Storing the configuration'
- Remove the chapter 'Going further in Buildroot innards' thanks to:
  - Moving the chapter 'How Buildroot works' to the Developer guide.
  - Moving the 'Advanced Buildroot usage' section to the 'General Buildroot
    usage' chapter.
- Remove the chapter 'Hacking Buildroot' by:
  - Adding a reference to adding packages to the 'Project-specific
    customizations' chapter
  - Leaving out the explicit reference to creating board support, as this is
    part of the previous chapter already, so an extra reference is
    redundant.

Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
2014-08-21 15:39:32 +02:00

271 lines
9.3 KiB
Plaintext

// -*- mode:doc; -*-
// vim: set syntax=asciidoc:
== General Buildroot usage
include::make-tips.txt[]
include::rebuilding-packages.txt[]
=== Offline builds
If you intend to do an offline build and just want to download
all sources that you previously selected in the configurator
('menuconfig', 'nconfig', 'xconfig' or 'gconfig'), then issue:
--------------------
$ make source
--------------------
You can now disconnect or copy the content of your +dl+
directory to the build-host.
=== Building out-of-tree
As default, everything built by Buildroot is stored in the directory
+output+ in the Buildroot tree.
Buildroot also supports building out of tree with a syntax similar to
the Linux kernel. To use it, add +O=<directory>+ to the make command
line:
--------------------
$ make O=/tmp/build
--------------------
Or:
--------------------
$ cd /tmp/build; make O=$PWD -C path/to/buildroot
--------------------
All the output files will be located under +/tmp/build+. If the +O+
path does not exist, Buildroot will create it.
*Note:* the +O+ path can be either an absolute or a relative path, but if it's
passed as a relative path, it is important to note that it is interpreted
relative to the main Buildroot source directory, *not* the current working
directory.
When using out-of-tree builds, the Buildroot +.config+ and temporary
files are also stored in the output directory. This means that you can
safely run multiple builds in parallel using the same source tree as
long as they use unique output directories.
For ease of use, Buildroot generates a Makefile wrapper in the output
directory - so after the first run, you no longer need to pass +O=<...>+
and +-C <...>+, simply run (in the output directory):
--------------------
$ make <target>
--------------------
[[env-vars]]
=== Environment variables
Buildroot also honors some environment variables, when they are passed
to +make+ or set in the environment:
* +HOSTCXX+, the host C++ compiler to use
* +HOSTCC+, the host C compiler to use
* +UCLIBC_CONFIG_FILE=<path/to/.config>+, path to
the uClibc configuration file, used to compile uClibc, if an
internal toolchain is being built.
+
Note that the uClibc configuration file can also be set from the
configuration interface, so through the Buildroot +.config+ file; this
is the recommended way of setting it.
+
* +BUSYBOX_CONFIG_FILE=<path/to/.config>+, path to
the BusyBox configuration file.
+
Note that the BusyBox configuration file can also be set from the
configuration interface, so through the Buildroot +.config+ file; this
is the recommended way of setting it.
+
* +BR2_DL_DIR+ to override the directory in which
Buildroot stores/retrieves downloaded files
+
Note that the Buildroot download directory can also be set from the
configuration interface, so through the Buildroot +.config+ file; this
is the recommended way of setting it.
* +BR2_GRAPH_ALT+, if set and non-empty, to use an alternate color-scheme in
build-time graphs
* +BR2_GRAPH_OUT+ to set the filetype of generated graphs, either +pdf+ (the
default), or +png+.
* +BR2_GRAPH_DEPS_OPTS+ to pass extra options to the dependency graph; see
xref:graph-depends[] for the accepted options
* +BR2_GRAPH_DOT_OPTS+ is passed verbatim as options to the +dot+ utility to
draw the dependency graph.
An example that uses config files located in the toplevel directory and
in your $HOME:
--------------------
$ make UCLIBC_CONFIG_FILE=uClibc.config BUSYBOX_CONFIG_FILE=$HOME/bb.config
--------------------
If you want to use a compiler other than the default +gcc+
or +g+++ for building helper-binaries on your host, then do
--------------------
$ make HOSTCXX=g++-4.3-HEAD HOSTCC=gcc-4.3-HEAD
--------------------
=== Dealing efficiently with filesystem images
Filesystem images can get pretty big, depending on the filesystem you choose,
the number of packages, whether you provisioned free space... Yet, some
locations in the filesystems images may just be _empty_ (e.g. a long run of
'zeroes'); such a file is called a _sparse_ file.
Most tools can handle sparse files efficiently, and will only store or write
those parts of a sparse file that are not empty.
For example:
* +tar+ accepts the +-S+ option to tell it to only store non-zero blocks
of sparse files:
** +tar cf archive.tar -S [files...]+ will efficiently store sparse files
in a tarball
** +tar xf archive.tar -S+ will efficiently store sparse files extracted
from a tarball
* +cp+ accepts the +--sparse=WHEN+ option (+WHEN+ is one of +auto+,
+never+ or +always+):
** +cp --sparse=always source.file dest.file+ will make +dest.file+ a
sparse file if +source.file+ has long runs of zeroes
Other tools may have similar options. Please consult their respective man
pages.
You can use sparse files if you need to store the filesystem images (e.g.
to transfer from one machine to another), or if you need to send them (e.g.
to the Q&A team).
Note however that flashing a filesystem image to a device while using the
sparse mode of +dd+ may result in a broken filesystem (e.g. the block bitmap
of an ext2 filesystem may be corrupted; or, if you have sparse files in
your filesystem, those parts may not be all-zeroes when read back). You
should only use sparse files when handling files on the build machine, not
when transferring them to an actual device that will be used on the target.
=== Graphing the dependencies between packages
[[graph-depends]]
One of Buildroot's jobs is to know the dependencies between packages,
and make sure they are built in the right order. These dependencies
can sometimes be quite complicated, and for a given system, it is
often not easy to understand why such or such package was brought into
the build by Buildroot.
In order to help understanding the dependencies, and therefore better
understand what is the role of the different components in your
embedded Linux system, Buildroot is capable of generating dependency
graphs.
To generate a dependency graph of the full system you have compiled,
simply run:
------------------------
make graph-depends
------------------------
You will find the generated graph in
+output/graphs/graph-depends.pdf+.
If your system is quite large, the dependency graph may be too complex
and difficult to read. It is therefore possible to generate the
dependency graph just for a given package:
------------------------
make <pkg>-graph-depends
------------------------
You will find the generated graph in
+output/graph/<pkg>-graph-depends.pdf+.
Note that the dependency graphs are generated using the +dot+ tool
from the _Graphviz_ project, which you must have installed on your
system to use this feature. In most distributions, it is available as
the +graphviz+ package.
By default, the dependency graphs are generated in the PDF
format. However, by passing the +BR2_GRAPH_OUT+ environment variable, you
can switch to other output formats, such as PNG, PostScript or
SVG. All formats supported by the +-T+ option of the +dot+ tool are
supported.
--------------------------------
BR2_GRAPH_OUT=svg make graph-depends
--------------------------------
The +graph-depends+ behaviour can be controlled by setting options in the
+BR2_GRAPH_DEPS_OPTS+ environment variable. The accepted options are:
* +--depth N+, +-d N+, to limit the dependency depth to +N+ levels. The
default, +0+, means no limit.
* +--transitive+, +--no-transitive+, to draw (or not) the transitive
dependencies. The default is to not draw transitive dependencies.
* +--colours R,T,H+, the comma-separated list of colours to draw the
root package (+R+), the target packages (+T+) and the host packages
(+H+). Defaults to: +lightblue,grey,gainsboro+
--------------------------------
BR2_GRAPH_DEPS_OPTS='-d 3 --no-transitive --colours=red,green,blue' make graph-depends
--------------------------------
=== Graphing the build duration
[[graph-duration]]
When the build of a system takes a long time, it is sometimes useful
to be able to understand which packages are the longest to build, to
see if anything can be done to speed up the build. In order to help
such build time analysis, Buildroot collects the build time of each
step of each package, and allows to generate graphs from this data.
To generate the build time graph after a build, run:
----------------
make graph-build
----------------
This will generate a set of files in +output/graphs+ :
* +build.hist-build.pdf+, a histogram of the build time for each
package, ordered in the build order.
* +build.hist-duration.pdf+, a histogram of the build time for each
package, ordered by duration (longest first)
* +build.hist-name.pdf+, a histogram of the build time for each
package, order by package name.
* +build.pie-packages.pdf+, a pie chart of the build time per package
* +build.pie-steps.pdf+, a pie chart of the global time spent in each
step of the packages build process.
This +graph-build+ target requires the Python Matplotlib and Numpy
libraries to be installed (+python-matplotlib+ and +python-numpy+ on
most distributions), and also the +argparse+ module if you're using a
Python version older than 2.7 (+python-argparse+ on most
distributions).
By default, the output format for the graph is PDF, but a different
format can be selected using the +BR2_GRAPH_OUT+ environment variable. The
only other format supported is PNG:
----------------
BR2_GRAPH_OUT=png make graph-build
----------------
include::eclipse-integration.txt[]
include::advanced.txt[]