Commit 77007ad9 authored by Thomas De Schampheleire's avatar Thomas De Schampheleire Committed by Thomas Petazzoni
Browse files

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: default avatarThomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: default avatarThomas Petazzoni <thomas.petazzoni@free-electrons.com>
parent 3afdf89f

docs/manual/common-usage.txt

+7 −1
Original line number Diff line number Diff line 
// -*- mode:doc; -*-

// vim: set syntax=asciidoc:



== Daily use

== General Buildroot usage



include::make-tips.txt[]



include::rebuilding-packages.txt[]
@@ -262,3 +264,7 @@ only other format supported is PNG: 
----------------

BR2_GRAPH_OUT=png make graph-build

----------------



include::eclipse-integration.txt[]



include::advanced.txt[]

docs/manual/configure.txt

+24 −1
Original line number Diff line number Diff line
@@ -2,7 +2,7 @@ 
// vim: set syntax=asciidoc:



[[configure]]

== Details on Buildroot configuration

== Buildroot configuration



All the configuration options in +make *config+ have a help text

providing details about the option. However, a number of topics
@@ -215,6 +215,20 @@ Drawbacks of this backend: 
  fix from the toolchain vendor, unless you build your external

  toolchain by yourself using Crosstool-NG.



===== External toolchain wrapper



When using an external toolchain, Buildroot generates a wrapper program,

that transparently passes the appropriate options (according to the

configuration) to the external toolchain programs. In case you need to

debug this wrapper to check exactly what arguments are passed, you can

set the environment variable +BR2_DEBUG_WRAPPER+ to either one of:



* +0+, empty or not set: no debug



* +1+: trace all arguments on a single line



* +2+: trace one argument per line



=== /dev management



On a Linux system, the +/dev+ directory contains special files, called
@@ -355,3 +369,12 @@ can be chosen from +System configuration+, +Init system+: 
The solution recommended by Buildroot developers is to use the

*BusyBox init* as it is sufficient for most embedded

systems. *systemd* can be used for more complex situations.



== Configuration of other components



include::customize-busybox-config.txt[]



include::customize-uclibc-config.txt[]



include::customize-kernel-config.txt[]

docs/manual/customize-store.txt

+2 −7
Original line number Diff line number Diff line 
// -*- mode:doc; -*-

// vim: set syntax=asciidoc:



[[customize-store]]

== Storing the configuration

[[customize-store-basics]]

=== Basics for storing the configuration



When you have a buildroot configuration that you are satisfied with and

you want to share it with others, put it under revision control or move
@@ -12,11 +12,6 @@ consists of the buildroot configuration, the configuration files for 
packages that you use (kernel, busybox, uClibc, ...), and your rootfs

modifications.





[[customize-store-basics]]

=== Basics for storing the configuration





[[customize-store-buildroot-config]]

==== Buildroot configuration

docs/manual/customize-toolchain.txt

deleted100644 → 0
+0 −49
Original line number Diff line number Diff line 
// -*- mode:doc; -*-

// vim: set syntax=asciidoc:



[[toolchain-custom]]

=== Customizing the toolchain



There are three distinct types of toolchain backend supported in Buildroot,

available under the menu +Toolchain+, invoking +make menuconfig+.



==== Using the external toolchain backend



There is no way of tuning an external toolchain since Buildroot does not

generate it.



It also requires to set the Buildroot settings according to the toolchain ones

(see xref:external-toolchain-backend[]).



When using an external toolchain, Buildroot generates a wrapper program,

that transparently passes the appropriate options (according to the

configuration) to the external toolchain programs. In case you need to

debug this wrapper to check exactly what arguments are passed, you can

set the environment variable +BR2_DEBUG_WRAPPER+ to either one of:



* +0+, empty or not set: no debug



* +1+: trace all arguments on a single line



* +2+: trace one argument per line



==== Using the internal Buildroot toolchain backend



The internal Buildroot toolchain backend allows to generate toolchains

based on http://www.uclibc.org/[uClibc],

https://www.gnu.org/software/libc/[glibc] and

http://www.eglibc.org/[eglibc].

Generation of (e)glibc-based toolchains is still experimental in

Buildroot.



It allows to tune major settings, such as:



* Linux headers version;



* C library configuration (only available for

  http://www.uclibc.org/[uClibc], see xref:uclibc-custom[uClibc]);



* Binutils, GCC, Gdb and toolchain options.



These settings are available after selecting the +Buildroot toolchain+ type in

the menu +Toolchain+.

docs/manual/customize.txt

+6 −8
Original line number Diff line number Diff line 
// -*- mode:doc; -*-

// vim: set syntax=asciidoc:



== Customization

== Project-specific customization



include::customize-rootfs.txt[]



include::customize-busybox-config.txt[]

The following sections describe the various way in which you can

customize Buildroot for a given project.



include::customize-uclibc-config.txt[]

For instructions on how to add new packages to Buildroot, refer to

xref:adding-packages[]



include::customize-kernel-config.txt[]



include::customize-toolchain.txt[]

include::customize-rootfs.txt[]



include::customize-store.txt[]