manual: rework using.txt and update common-usage.txt

Consider the second chapter: "starting-up", as a tutorial.
Assuming that, using.txt only contains the very first commands used to get
configure and build its very first target system.

So, the following subsection from using.txt have been to common-usage.txt:
- Offline builds
- Building out-of-tree
- Environment variables

Signed-off-by: Samuel Martin <s.martin49@gmail.com>
Signed-off-by: Peter Korsgaard <jacmet@sunsite.dk>

1 files changed, 95 insertions, 0 deletions

diff --git a/docs/manual/common-usage.txt b/docs/manual/common-usage.txt
index b3436063e..c08c10ea6 100644
--- a/docs/manual/common-usage.txt
+++ b/docs/manual/common-usage.txt
@@ -4,3 +4,98 @@ 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', '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
+  the actual 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
+  the actual 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
+  the actual recommended way of setting it.
+
+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
+--------------------