Patchwork [v2,04/11] manual: rework using.txt and update common-usage.txt

login
register
mail settings
Submitter Samuel Martin
Date May 13, 2012, 10:38 a.m.
Message ID <1336905501-9757-5-git-send-email-s.martin49@gmail.com>
Download mbox | patch
Permalink /patch/158818/
State Superseded
Headers show

Comments

Samuel Martin - May 13, 2012, 10:38 a.m.
From: Samuel MARTIN <s.martin49@gmail.com>

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>
Thomas De Schampheleire - May 16, 2012, 4:47 p.m.
On Sun, May 13, 2012 at 12:38 PM, Samuel Martin <s.martin49@gmail.com> wrote:
> From: Samuel MARTIN <s.martin49@gmail.com>
>
> 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>
>
> diff --git a/docs/manual/common-usage.txt b/docs/manual/common-usage.txt
> index ff8543f..dde1ab0 100644
> --- a/docs/manual/common-usage.txt
> +++ b/docs/manual/common-usage.txt
> @@ -2,3 +2,80 @@ 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
> +~~~~~~~~~~~~~~~~~~~~
> +
> +Buildroot 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+.

I would mention in this section that the default output directory is
'output' in the buildroot tree.

> +
> +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
> +* +BUSYBOX_CONFIG_FILE=<path/to/.config>+, path to
> +  the Busybox configuration file
> +* +BUILDROOT_DL_DIR+ to override the directory in which
> +  Buildroot stores/retrieves downloaded files
> +
> +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
> +--------------------

I would mention here that the recommended usage is to specify these
config files in the buildroot .config file instead.

> +
> +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
> +--------------------
> diff --git a/docs/manual/using.txt b/docs/manual/using.txt
> index 88dc58c..2945098 100644
> --- a/docs/manual/using.txt
> +++ b/docs/manual/using.txt
> @@ -3,8 +3,8 @@ Using Buildroot
>
>  Buildroot has a nice configuration tool similar to the one you can
>  find in the http://www.kernel.org/[Linux kernel] or in
> -http://www.busybox.net/[Busybox]. Note that you can (and should) build
> -everything as a normal user. There is no need to be root to configure
> +http://www.busybox.net/[Busybox]. Note that you can *and should build
> +everything as a normal user*. There is no need to be root to configure
>  and use Buildroot. The first step is to run the configuration
>  assistant:
>
> @@ -27,12 +27,11 @@ or
>  to run the Qt or GTK-based configurators.
>
>  All of these "make" commands will need to build a configuration
> -utility, so you may need to install "development" packages for
> -relevant libraries used by the configuration utilities. On Debian-like
> -systems, the +libncurses5-dev+ package is required to use the
> -'menuconfig' interface, +libqt4-dev+ is required to use the 'xconfig'
> -interface, and +libglib2.0-dev, libgtk2.0-dev and libglade2-dev+ are
> -needed to use the 'gconfig' interface.
> +utility (including the interface), so you may need to install
> +"development" packages for relevant libraries used by the
> +configuration utilities. Check the xref:requirement[] to know what
> +Buildroot needs, and specifically the xref:requirement-optional[system requirements]
> +to get the dependencies of favourite interface.

s/favourite/favorite/
as we generally use American style words (as you did before with honor, ...)

>
>  For each menu entry in the configuration tool, you can find associated
>  help that describes the purpose of the entry.
> @@ -54,9 +53,9 @@ tell Buildroot to run each package compilation with +make -jN+.
>  This command will generally perform the following steps:
>
>  * Download source files (as required)
> -* Configure, build and install the cross-compiling toolchain if an
> -  internal toolchain is used, or import a toolchain if an external
> -  toolchain is used
> +* Configure, build and install the cross-compiling toolchain using the
> +  appropiate toolchain backend is used, or simply import a toolchain
> +  if an external toolchain is used

s/appropiate/appropriate/
s/is used//


>  * Build/install selected target packages
>  * Build a kernel image, if selected
>  * Build a bootloader image, if selected
> @@ -103,78 +102,9 @@ This directory contains several subdirectories:
>  * +toolchain/+ contains the build directories for the various
>   components of the cross-compilation toolchain.
>
> -Offline builds
> ---------------
> +These commands, +make menuconfig|gconfig|xconfig+ and +make+, are the
> +basic ones that allow to easily and quickly generate images fitting
> +your needs, with all the supports and applications you enabled.
>
> -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
> ---------------------
> -
> -Buildroot 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>
> ---------------------
> -
> -Environment variables
> ----------------------
> -[[env-vars]]
> -
> -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
> -* +BUSYBOX_CONFIG_FILE=<path/to/.config>+, path to
> -  the Busybox configuration file
> -* +BUILDROOT_DL_DIR+ to override the directory in which
> -  Buildroot stores/retrieves downloaded files
> -
> -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
> ---------------------
> +More details about the "make" command usages are given in
> +xref:make-tips[].

Is it common to talk about 'command usages' ? I would have put 'command usage'.

> --
> 1.7.10.2
>
> _______________________________________________
> buildroot mailing list
> buildroot@busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot

Patch

diff --git a/docs/manual/common-usage.txt b/docs/manual/common-usage.txt
index ff8543f..dde1ab0 100644
--- a/docs/manual/common-usage.txt
+++ b/docs/manual/common-usage.txt
@@ -2,3 +2,80 @@  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
+~~~~~~~~~~~~~~~~~~~~
+
+Buildroot 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
+* +BUSYBOX_CONFIG_FILE=<path/to/.config>+, path to
+  the Busybox configuration file
+* +BUILDROOT_DL_DIR+ to override the directory in which
+  Buildroot stores/retrieves downloaded files
+
+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
+--------------------
diff --git a/docs/manual/using.txt b/docs/manual/using.txt
index 88dc58c..2945098 100644
--- a/docs/manual/using.txt
+++ b/docs/manual/using.txt
@@ -3,8 +3,8 @@  Using Buildroot
 
 Buildroot has a nice configuration tool similar to the one you can
 find in the http://www.kernel.org/[Linux kernel] or in
-http://www.busybox.net/[Busybox]. Note that you can (and should) build
-everything as a normal user. There is no need to be root to configure
+http://www.busybox.net/[Busybox]. Note that you can *and should build
+everything as a normal user*. There is no need to be root to configure
 and use Buildroot. The first step is to run the configuration
 assistant:
 
@@ -27,12 +27,11 @@  or
 to run the Qt or GTK-based configurators.
 
 All of these "make" commands will need to build a configuration
-utility, so you may need to install "development" packages for
-relevant libraries used by the configuration utilities. On Debian-like
-systems, the +libncurses5-dev+ package is required to use the
-'menuconfig' interface, +libqt4-dev+ is required to use the 'xconfig'
-interface, and +libglib2.0-dev, libgtk2.0-dev and libglade2-dev+ are
-needed to use the 'gconfig' interface.
+utility (including the interface), so you may need to install
+"development" packages for relevant libraries used by the
+configuration utilities. Check the xref:requirement[] to know what
+Buildroot needs, and specifically the xref:requirement-optional[system requirements]
+to get the dependencies of favourite interface.
 
 For each menu entry in the configuration tool, you can find associated
 help that describes the purpose of the entry.
@@ -54,9 +53,9 @@  tell Buildroot to run each package compilation with +make -jN+.
 This command will generally perform the following steps:
 
 * Download source files (as required)
-* Configure, build and install the cross-compiling toolchain if an
-  internal toolchain is used, or import a toolchain if an external
-  toolchain is used
+* Configure, build and install the cross-compiling toolchain using the
+  appropiate toolchain backend is used, or simply import a toolchain
+  if an external toolchain is used
 * Build/install selected target packages
 * Build a kernel image, if selected
 * Build a bootloader image, if selected
@@ -103,78 +102,9 @@  This directory contains several subdirectories:
 * +toolchain/+ contains the build directories for the various
   components of the cross-compilation toolchain.
 
-Offline builds
---------------
+These commands, +make menuconfig|gconfig|xconfig+ and +make+, are the
+basic ones that allow to easily and quickly generate images fitting
+your needs, with all the supports and applications you enabled.
 
-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
---------------------
-
-Buildroot 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>
---------------------
-
-Environment variables
----------------------
-[[env-vars]]
-
-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
-* +BUSYBOX_CONFIG_FILE=<path/to/.config>+, path to
-  the Busybox configuration file
-* +BUILDROOT_DL_DIR+ to override the directory in which
-  Buildroot stores/retrieves downloaded files
-
-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
---------------------
+More details about the "make" command usages are given in
+xref:make-tips[].