abd4124e5f
As reported by Ryan, it is not well-known that most tools can deal efficiently with big sparse files. Add a section in the manual about this, with tar and cp used as examples, and a hinting to the man pages for the others. Reported-by: Ryan Barnett <rjbarnet@rockwellcollins.com> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr> Cc: Ryan Barnett <rjbarnet@rockwellcollins.com> Cc: Peter Korsgaard <jacmet@uclibc.org> Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com> Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
146 lines
4.8 KiB
Plaintext
146 lines
4.8 KiB
Plaintext
// -*- mode:doc; -*-
|
|
// vim: set syntax=asciidoc:
|
|
|
|
Daily use
|
|
---------
|
|
|
|
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+.
|
|
|
|
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.
|
|
+
|
|
* +BUILDROOT_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.
|
|
* +GRAPH_ALT+, if set and non-empty, to use an alternate color-scheme in
|
|
build-time graphs
|
|
* +GRAPH_OUT+ to set the filetype of generated graphs, either +pdf+ (the
|
|
default), or +png+.
|
|
|
|
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_ (eg. 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 (eg.
|
|
to transfer from one machine to another), of if you need to send them (eg.
|
|
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 (eg. 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.
|