RFC: Manual content reorganization

index 428a182..dcc7a24 100644
@@ -1,10 +1,10 @@
 Infrastructure for autotools-based packages
--------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 [[autotargets-tutorial]]
 
 +AUTOTARGETS+ tutorial
-~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^
 
 First, let's see how to write a +.mk+ file for an autotools-based
 package, with an example :

@@ -64,7 +64,7 @@ package to be built.
 [[autotargets-reference]]
 
 +AUTOTARGETS+ reference
-~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^
 
 The main macro of the autotools package infrastructure is
 +AUTOTARGETS+. It has the same number of arguments and the

index 3e400ec..a6b2273 100644
@@ -1,10 +1,10 @@
 Infrastructure for CMake-based packages
----------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 [[cmaketargets-tutorial]]
 
 +CMAKETARGETS+ tutorial
-~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^
 
 First, let's see how to write a +.mk+ file for a CMake-based package,
 with an example :

@@ -63,7 +63,7 @@ package to be built.
 [[cmaketargets-reference]]
 
 +CMAKETARGETS+ reference
-~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 The main macro of the CMake package infrastructure is
 +CMAKETARGETS+. It has the same number of arguments and the same

index 3475827..d03dc4e 100644
@@ -1,5 +1,5 @@
 Conclusion
-----------
+~~~~~~~~~~
 
 As you can see, adding a software package to Buildroot is simply a
 matter of writing a Makefile using an  existing example and modifying it

index 2670f2f..1428f37 100644
@@ -1,5 +1,5 @@
 Package directory
------------------
+~~~~~~~~~~~~~~~~~
 
 First of all, create a directory under the +package+ directory for
 your software, for example +libfoo+.

@@ -10,7 +10,7 @@ one of these categories, then create your package directory in these.
 
 
 +Config.in+ file
-~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^
 
 Then, create a file named +Config.in+. This file will contain the
 option descriptions related to our +libfoo+ software that will be used

@@ -146,7 +146,7 @@ so, the dependency also needs to be expressed in the +.mk+ file of the
 package.
 
 The +.mk+ file
-~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^
 
 Finally, here's the hardest part. Create a file named +libfoo.mk+. It
 describes how the package should be downloaded, configured, built,

index cfcee8c..c0ad89d 100644
@@ -1,5 +1,5 @@
 Infrastructure for packages with specific build systems
--------------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 By 'packages with specific build systems' we mean all the packages
 whose build system is not one of the standard ones, such as

@@ -9,7 +9,7 @@ system is based on hand-written Makefiles or shell scripts.
 [[gentargets-tutorial]]
 
 +GENTARGETS+ Tutorial
-~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^
 
 ------------------------------
 01: #############################################################

@@ -90,7 +90,7 @@ Makefile code necessary to make your package working.
 [[gentargets-reference]]
 
 +GENTARGETS+ Reference
-~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^
 
 The +GENTARGETS+ macro takes one optional argument. This argument can
 be used to tell if the package is a target package (cross-compiled for

index 1ed834e..7eced86 100644
@@ -1,5 +1,5 @@
 Gettext integration and interaction with packages
--------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Many packages that support internationalization use the gettext
 library. Dependencies for this library are fairly complicated and

index beb25f6..25fa93c 100644
@@ -1,7 +1,5 @@
-[[handwritten-tutorial]]
-
 Manual Makefile
----------------
+~~~~~~~~~~~~~~~
 
 *NOTE: new manual makefiles should not be created, and existing manual
 makefiles should be converted either to the generic, autotools or

index 0217e9f..91649d4 100644
@@ -1,5 +1,6 @@
+[[adding-packages]]
 Adding new packages to Buildroot
-================================
+--------------------------------
 
 This section covers how new packages (userspace libraries or
 applications) can be integrated into Buildroot. It also shows how

new file mode 100644
index 0000000..f433c13
@@ -0,0 +1,10 @@
+Advanced usage
+--------------
+
+include::using-buildroot-toolchain.txt[]
+
+include::external-toolchain.txt[]
+
+include::ccache-support.txt[]
+
+include::download-location.txt[]

index d1d9d63..e8142ab 100644
@@ -1,5 +1,6 @@
+[[board-support]]
 Creating your own board support
-===============================
+-------------------------------
 
 Creating your own board support in Buildroot allows users of a
 particular hardware platform to easily build a system that is known to

index ab8cbad..37a9f92 100644
@@ -1,5 +1,6 @@
+[[ccache]]
 Using +ccache+ in Buildroot
-===========================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 http://ccache.samba.org[ccache] is a compiler cache. It stores the
 object files resulting from each compilation process, and is able to

new file mode 100644
index 0000000..ff8543f
@@ -0,0 +1,4 @@
+Daily use
+---------
+
+include::rebuilding-packages.txt[]

new file mode 100644
index 0000000..30ae800
@@ -0,0 +1,2 @@
+Contibuting to Buildroot
+========================

index 60e6a55..880fe3a 100644
@@ -1,6 +1,6 @@
-Customizing the Busybox configuration
--------------------------------------
 [[busybox-custom]]
+Customizing the Busybox configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 http://www.busybox.net/[Busybox] is very configurable, and you may
 want to customize it. You can follow these simple steps to do so. This

@@ -20,5 +20,5 @@ Otherwise, you can simply change the
 options you want to change, without using the configuration tool.
 
 If you want to use an existing config file for busybox, then see
-section xref:env-vars[].
+xref:env-vars[].
 

index 6bafe46..93470be 100644
@@ -1,5 +1,6 @@
+[[kernel-custom]]
 Customizing the Linux kernel configuration
-------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The Linux kernel configuration can be customized just like
 xref:busybox-custom[BusyBox] and xref:uclibc-custom[uClibc] using

index 8c3ea82..123c97f 100644
@@ -1,5 +1,6 @@
+[[rootfs-custom]]
 Customizing the generated target filesystem
--------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 There are a few ways to customize the resulting target filesystem:
 

index 08b60a2..b4ac4a4 100644
@@ -1,12 +1,12 @@
-Customizing the toolchain
--------------------------
 [[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.

@@ -15,7 +15,7 @@ It also requires to set the Buildroot settings according to the toolchain ones
 (see xref:external-toolchain[]).
 
 Using the internal Buildroot toolchain backend
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The internal Buildroot toolchain backend *only* allows to generate
 *http://www.uclibc.org/[uClibc]-based toolchains*.

@@ -32,7 +32,7 @@ This is directly available after selecting the +Buildroot toolchain+ type in
 the menu +Toolchain+.
 
 Using the Crosstool-NG backend
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The http://crosstool-ng.org[crosstool-NG] toolchain backend enables a rather
 limited set of settings under the Buildroot +Toolchain+ menu (ie. when invoking

index e2e6799..6db4e41 100644
@@ -1,6 +1,6 @@
-Customizing the uClibc configuration
-------------------------------------
 [[uclibc-custom]]
+Customizing the uClibc configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Just like xref:busybox-custom[BusyBox], http://www.uclibc.org/[uClibc]
 offers a lot of configuration options. They allow you to select

index e8235de..8778fdd 100644
@@ -1,5 +1,5 @@
 Customization
-=============
+-------------
 
 include::customize-rootfs.txt[]
 

new file mode 100644
index 0000000..14589c2
@@ -0,0 +1,8 @@
+Developer Guidelines
+====================
+
+include::writing-rules.txt[]
+
+include::adding-packages.txt[]
+
+include::board-support.txt[]

index cb6147f..7ac98c0 100644
@@ -1,5 +1,5 @@
 Location of downloaded packages
-===============================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 It might be useful to know that the various tarballs that are
 downloaded by the Makefiles are all stored in the +DL_DIR+ which by

new file mode 100644
index 0000000..e1c66e3
@@ -0,0 +1,2 @@
+Embedded system basics & Reasons to use Buildroot
+-------------------------------------------------

index 62eb0a3..30efe42 100644
@@ -1,6 +1,6 @@
-Using an external toolchain
-===========================
 [[external-toolchain]]
+Using an external toolchain
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Using an already existing toolchain is useful for different
 reasons:

new file mode 100644
index 0000000..df3b055
@@ -0,0 +1,2 @@
+Getting involved
+================

index 42ca009..6cfdefb 100644
@@ -1,5 +1,6 @@
+[[getting-buildroot]]
 Getting Buildroot
-=================
+-----------------
 
 Buildroot releases are made approximately every 3 months. Direct Git
 access and daily snapshots are also available, if you want more

new file mode 100644
index 0000000..67162a6
@@ -0,0 +1,8 @@
+Going further in Buildroot's innards
+====================================
+
+include::embedded-basics.txt[]
+
+include::how-buildroot-works.txt[]
+
+include::advanced.txt[]

index 481e5a4..1e86ca3 100644
@@ -1,5 +1,5 @@
 How Buildroot works
-===================
+-------------------
 
 As mentioned above, Buildroot is basically a set of Makefiles that
 download, configure, and compile software with the correct options. It

new file mode 100644
index 0000000..3d741a9
@@ -0,0 +1,4 @@
+Legal notice
+============
+
+TODO

new file mode 100644
index 0000000..646efdf
@@ -0,0 +1,2 @@
+'make' tips
+-----------

index 732b50c..3e7a7ef 100644
@@ -11,24 +11,25 @@ image::logo.png[]
 
 include::introduction.txt[]
 
-include::getting.txt[]
+include::starting-up.txt[]
 
-include::using.txt[]
 
-include::customize.txt[]
 
-include::rebuilding-packages.txt[]
+include::working-with.txt[]
 
-include::how-buildroot-works.txt[]
+include::troubleshooting.txt[]
 
-include::using-buildroot-toolchain.txt[]
 
-include::external-toolchain.txt[]
 
-include::ccache-support.txt[]
+include::going-further.txt[]
 
-include::download-location.txt[]
+include::developer-guide.txt[]
+
+include::get-involved.txt[]
+
+include::contribute.txt[]
+
+include::legal-notice.txt[]
 
-include::adding-packages.txt[]
 
 include::appendix.txt[]

new file mode 100644
index 0000000..f50672b
@@ -0,0 +1,2 @@
+System requirements
+-------------------

index 9a41a88..6e4ee2f 100644
@@ -1,5 +1,5 @@
 Understanding how to rebuild packages
-=====================================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 One of the most common questions asked by Buildroot users is how to
 rebuild a given package or how to remove a package without rebuilding

new file mode 100644
index 0000000..3a74ea6
@@ -0,0 +1,9 @@
+Starting up
+===========
+
+include::prerequisite.txt[]
+
+include::getting.txt[]
+
+include::using.txt[]
+

new file mode 100644
index 0000000..4eddddd
@@ -0,0 +1,2 @@
+Troubleshooting
+===============

index 712e9a8..24e797f 100644
@@ -1,5 +1,5 @@
 Using the generated toolchain outside Buildroot
-===============================================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You may want to compile, for your target, your own programs or other
 software that are not packaged in Buildroot. In order to do this you

new file mode 100644
index 0000000..01f1041
@@ -0,0 +1,12 @@
+Working with Buildroot
+======================
+[[working-with-br]]
+
+include::make-tips.txt[]
+
+include::customize.txt[]
+
+include::common-usage.txt[]
+
+Tweaking Buildroot
+------------------

new file mode 100644
index 0000000..284cee2
@@ -0,0 +1,11 @@
+Writing rules
+-------------
+
++Config.in+ file
+~~~~~~~~~~~~~~~~
+
+The +.mk+ file
+~~~~~~~~~~~~~~
+
+The documentation
+~~~~~~~~~~~~~~~~~

index e1c66e3..bf14d7c 100644
@@ -1,2 +1,67 @@
 Embedded system basics & Reasons to use Buildroot
 -------------------------------------------------
+
+Cross-compilation & cross-toolchain
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A compilation toolchain is the set of tools that allows you to compile
+code for your system. It consists of a compiler (in our case, +gcc+),
+binary utils like assembler and linker (in our case, +binutils+) and a
+C standard library (for example
+http://www.gnu.org/software/libc/libc.html[GNU Libc],
+http://www.uclibc.org/[uClibc] or
+http://www.fefe.de/dietlibc/[dietlibc]). The system installed on your
+development station certainly already has a compilation toolchain that
+you can use to compile an application that runs on your system. If
+you're using a PC, your compilation toolchain runs on an x86 processor
+and generates code for an x86 processor. Under most Linux systems, the
+compilation toolchain uses the GNU libc (glibc) as the C standard
+library.  This compilation toolchain is called the "host compilation
+toolchain". The machine on which it is running, and on which you're
+working, is called the "host system". The compilation toolchain is
+provided by your distribution, and Buildroot has nothing to do with it
+(other than using it to build a cross-compilation toolchain and other
+tools that are run on the development host).
+
+As said above, the compilation toolchain that comes with your system
+runs on and generates code for the processor in your host system. As
+your embedded system has a different processor, you need a
+cross-compilation toolchain - a compilation toolchain that runs on
+your host system but generates code for your target system (and target
+processor). For example, if your host system uses x86 and your target
+system uses ARM, the regular compilation toolchain on your host runs on
+x86 and generates code for x86, while the cross-compilation toolchain
+runs on x86 and generates code for ARM.
+
+[[pros-buildroot]]
+
+Why choose Buildroot
+~~~~~~~~~~~~~~~~~~~~
+
+Even if your embedded system uses an x86 processor, you might be
+interested in Buildroot for two reasons:
+
+* The compilation toolchain on your host certainly uses the GNU Libc
+  which is a complete but huge C standard library. Instead of using
+  GNU Libc on your target system, you can use uClibc which is a tiny C
+  standard library. If you want to use this C library, then you need a
+  compilation toolchain to generate binaries linked with it. Buildroot
+  can do that for you.
+
+* Buildroot automates the building of a root filesystem with all
+  needed tools like busybox. That makes it much easier than doing it
+  by hand.
+
+You might wonder why such a tool is needed when you can compile +gcc+,
++binutils+, +uClibc+ and all the other tools by hand. Of course doing
+so is possible but, dealing with all of the configure options and
+problems of every +gcc+ or +binutils+ version is very time-consuming
+and uninteresting.  Buildroot automates this process through the use
+of Makefiles and has a collection of patches for each +gcc+ and
++binutils+ version to make them work on most architectures.
+
+Moreover, Buildroot provides an infrastructure for reproducing the
+build process of your kernel, cross-toolchain, and embedded root
+filesystem. Being able to reproduce the build process will be useful
+when a component needs to be patched or updated or when another person
+is supposed to take over the project.

82 lines not on this page · raw message

index f50672b..df1e6a8 100644
@@ -1,2 +1,69 @@
+[[requirement]]
 System requirements
 -------------------
+
+Buildroot is design to run on Linux system.
+
+Buildroot needs some software to be already installed on the host
+system; hereafter the lists of the mandatory and optional packages
+(packages' name may vary between distribution).
+
+Take care of _installing both runtime and development data_, especially
+for the libraries that may be packaged in 2 distinct packages.
+
+
+[[requirement-mandatory]]
+
+Mandatory packages
+~~~~~~~~~~~~~~~~~~
+
+* Build tools:
+** +build-essential+ (only for Debian based system)
+** +gcc+
+** +g+++
+** +autoconf+
+** +automake+
+** +libtool+
+** +bison+
+** +flex+
+** +gettext+
+** +patch+
+** +gawk+
+
+* Source fetching tools:
+** +curl+
+** +wget+
+** +cvs+
+** +git+
+** +mercurial+
+** +subversion+
+
+* Development libraries:
+** +ncurses5+
+** +lzo2+
+** +lzma+
+** +zlib1+
+** +acl1+
+** +uuid+
+
+* Documentation generation tools:
+** +asciidoc+
+** +texinfo+
+
+[[requirement-optional]]
+
+Optional packages
+~~~~~~~~~~~~~~~~~
+
+* Interface dependencies (requires development libraries):
+** +ncurses5+ to use the 'menuconfig' interface
+** +qt4+ to use the 'xconfig' interface
+** +glib2+, +gtk2+ and +glade2+ to use the 'gconfig' interface
+
+* Development libraries:
+** +glib2+
+** +netpbm10+ (for +fbtest+)
+** +python-xcbgen+ (for +Matchbox+ on Debian based system)
+** +jdk+ and and depending on the host system +gcj-compat+ for Java
+development (for +java+, +jamvm+ and +gnu-classpath+)
+

index ff8543f..dde1ab0 100644
@@ -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
+--------------------

128 lines not on this page · raw message

index 646efdf..a512689 100644
@@ -1,2 +1,48 @@
+[[make-tips]]
 'make' tips
 -----------
+
+Because Buildroot is a set of Makefiles and patches, there are few
+things useful to know, such as:
+
+Display all command executed by make:
+
+--------------------
+ $ make V=0|1 <target>
+--------------------
+
+Display all available targets:
+
+--------------------
+ $ make help
+--------------------
+
+Note that, some settings in the +.config+ file may hide some targets
+like:
+
+* +busybox-menuconfig+ depends whether +busybox+ is enabled or not in
+  the +Package selection+ menu
+* +linux-menuconfig+ and +linux-savedefconfig+ depends on whether
+  +linux+ is enabled or not
+* +uclibc-menuconfig+ depends on whether the toolchain uses the
+  Buildroot internal toolchain backend or not
+* +ctng-menuconfig+ depends on whether the toolchain uses the
+  crosstool-NG backend or not
+* +barebox-menuconfig+ and +barebox-savedefconfig+ depends on whether
+  +barebox+ bootloader is enabled or not
+
+Delete all build products (including build directories, host, staging
+and target trees, the images and the toolchain):
+
+--------------------
+ $ make clean
+--------------------
+
+Delete all build products as well as the configuration:
+
+--------------------
+ $ make distclean
+--------------------
+
+Note that if +ccache+ is enabled, running +make clean|distclean+ does
+not empty the Buildroot's cache. To delete it, refer to xref:ccache[].

index 6e4ee2f..b0f53f6 100644
@@ -25,8 +25,8 @@ by the different packages, so some understanding of the particular
 package is needed.
 
 For packages relying on Buildroot packages infrastructures (see
-xref:add-packages[this section] for details), the following stamp
-files are relevant:
+xref:adding-packages[] for details), the following stamp files are
+relevant:
 
 * +output/build/packagename-version/.stamp_configured+. If removed,
   Buildroot will trigger the recompilation of the package from the

index 01f1041..b9d915c 100644
@@ -1,6 +1,9 @@
 Working with Buildroot
 ======================
-[[working-with-br]]
+
+This section aims to explain how Buildroot allows you to tune,
+customize almost everthing... making your configuration fitting your
+needs.
 
 include::make-tips.txt[]
 

@@ -10,3 +13,10 @@ include::common-usage.txt[]
 
 Tweaking Buildroot
 ------------------
+
+Because Buildroot does not yet fit all your requirements, you may be
+intrested in tweaking it to add:
+
+* new packages: refer to the xref:adding-packages[Developer guide]
+
+* new board support: refer to the xref:board-support[Developer guide]

index 4eddddd..db9277d 100644
@@ -1,2 +1,46 @@
 Troubleshooting
 ===============
+
+LZO package configuration failure due to incorrect host architecture detection
+------------------------------------------------------------------------------
+
+Typical error output
+~~~~~~~~~~~~~~~~~~~~
+
+------------------------
+configure: Configuring LZO 2.03
+checking build system type... Invalid configuration `x86_64-unknown-linux-': machine `x86_64-unknown-linux' not recognized
+configure: error: /bin/sh autoconf/config.sub x86_64-unknown-linux- failed
+------------------------
+
+Actually this is a known ccache/zlib issue (see
+https://bugs.busybox.net/show_bug.cgi?id=4808) that occurs when the
+zlib version of the host system is more recent that the one provided
+by Buildroot. This misleads the Buildroot host binary +ccache+.
+
+This bug has been spotted, then fixed shortly after the Buildroot
+2012.02 release.
+
+If you are using the release 2012.02 or elder and got this issue, then
+applying this patch
+http://git.buildroot.net/buildroot/patch/package/ccache/ccache.mk?id=7ea11dafff37c5403432f691cf3c46d1d5566e46
+should fix it.
+
+Solution
+~~~~~~~~
+
+* Get the upstream patch:
++
+-----------------------
+ $ wget -O /tmp/ccache-Force-ccache-to-use-its-internal-zlib.patch \
+    "http://git.buildroot.net/buildroot/patch/package/ccache/ccache.mk?id=7ea11dafff37c5403432f691cf3c46d1d5566e46"
+------------------------
+
+* Apply this patch and rebuild ccache:
++
+------------------------
+ $ cd buildroot
+ $ patch -p1 < /tmp/ccache-Force-ccache-to-use-its-internal-zlib.patch
+ $ make host-ccache-dirclean
+ $ make
+------------------------

index 123c97f..d067e31 100644
@@ -2,7 +2,9 @@
 Customizing the generated target filesystem
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-There are a few ways to customize the resulting target filesystem:
+Apart changing one or another configuration through +make
+*-menuconfig+, there are a few ways to customize the resulting target
+filesystem:
 
 * Customize the target filesystem directly and rebuild the image.  The
   target filesystem is available under +output/target/+.  You can

index 1428f37..e36eafc 100644
@@ -145,6 +145,9 @@ is also enabled, but not necessarily built before your package. To do
 so, the dependency also needs to be expressed in the +.mk+ file of the
 package.
 
+Further formating details: see xref:writing-rules-config-in[the
+writing rules].
+
 The +.mk+ file
 ^^^^^^^^^^^^^^
 

@@ -185,3 +188,5 @@ different way, using different infrastructures:
   many of them in the tree, we keep them documented in a
   xref:handwritten-tutorial[tutorial].
 
+Further formating details: see xref:writing-rules-mk[the writing
+rules].

119 lines not on this page · raw message

index df3b055..9b6e843 100644
@@ -1,2 +1,67 @@
 Getting involved
 ================
+
+Like any open source projects, Buildroot has different ways to share
+information in its community and outside.
+
+One piece of it is the document you are currently reading ;-).
+
+Each of those ways may interest you if you are look for some help,
+want to understand Buildroot or contribute to the project.
+
+Mailing List
+------------
+
+Buildroot has a mailing list
+http://lists.busybox.net/pipermail/buildroot[] for discussion and
+development.
+
+[[mailing-list-subscribe]]
+
+Subscribing to the mailing list
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can subscribe by visiting
+http://lists.busybox.net/mailman/listinfo/buildroot[].
+Only subscribers to the Buildroot mailing list are allowed to post to
+this list.
+
+The list is also available through _Gmane_ http://gmane.org[], at
++gmane.comp.lib.uclibc.buildroot+
+http://dir.gmane.org/gmane.comp.lib.uclibc.buildroot[].
+
+Searching the List Archives
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Please search the mailing list archives before asking questions on the
+mailing list, since there is a good chance someone else has asked the
+same question before. Checking the archives is a great way to avoid
+annoying everyone on the list with frequently asked questions...
+
+IRC
+---
+
+The Buildroot IRC is irc://freenode.net/#buildroot[].
+The channel +#buildroot+ is hosted on Freenode
+http://webchat.freenode.net[].
+
+When asking for help on the IRC, share relevant logs or piece of code
+using a code sharing website (see
+http://en.wikipedia.org/wiki/Comparison_of_pastebins[], and pick up
+one).
+
+Bugtracker
+----------
+
+The Buildroot bugtracker is at https://bugs.uclibc.org[].
+
+Buildroot wikipage
+------------------
+
+Consecutively to the Buildroot developer day February 3, 2012,
+a page dedicated to Buildroot has been created on
+http://elinux.org[elinux.org].
+
+This page is reachable at http://elinux.org/Buildroot[].
+
+Currently, this page is mainly used as a _todo-list_.

index 30ae800..d80e79a 100644
@@ -1,2 +1,63 @@
 Contibuting to Buildroot
 ========================
+
+If you want to contribute to Buildroot, you will need a git view of
+the project. Refer to xref:getting-buildroot[] to get it.
+
+Currently, the mailing list is the central place for contribution.
+If you have not already subscribe to it, then refer to
+xref:mailing-list-subscribe[].
+
+Submiting patches
+-----------------
+
+When your changes are done, and commited in your local git view,
+_rebase_ your development branch on top of the upstream tree before
+generating the patch set. To do so, run:
+
+---------------------
+ $ git fetch --all --tags
+ $ git rebase origin/master
+---------------------
+
+Here, your are ready to generate then submit your patch set.
+
+To generate it, run:
+
+---------------------
+ $ git format-patch -M -n -s -o outgoing origin/master
+---------------------
+
+This will generate patch files in the +outgoing+ subdirectory,
+automatically adding the +signed-of-by+ line.
+
+If you want to present the whole patch set in a separate mail, add
++--cover-letter --summary+ to the previous command line (+man
+git-format-patch+ for further information).
+
+Once patch files are generated, you can review/edit the commit message
+before submitting them using your favourite text editor.
+
+Lastly, send/submit your patch set to the Buildroot mailing list:
+
+---------------------
+ $ git send-email --to buildroot at busybox.net outgoing/*
+---------------------
+
+Note that +git+ should be configured to use your mail account.
+To configure +git+, see +man git-send-email+ or google it.
+
+Reviewing/Testing patches
+-------------------------
+
+In the review process, do not hesitate to respond to patch submissions
+for remarks, suggestions or anything that will help everyone to
+understand the patches and make them better.
+
+Some tags are used to help following the state of any patch posted on
+the mailing-list:
+
+Acked-by:: Indicates that the patch can be committed.
+
+Tested-by:: Indicates that the patch has been tested. It is useful
+  but not necessary to add a comment about what has been tested.

index 6cfdefb..8ad544a 100644
@@ -1,6 +1,7 @@
 [[getting-buildroot]]
 Getting Buildroot
 -----------------
+[[getting-buildroot]]
 
 Buildroot releases are made approximately every 3 months. Direct Git
 access and daily snapshots are also available, if you want more

index 428a182..dcc7a24 100644
@@ -1,10 +1,10 @@
 Infrastructure for autotools-based packages
--------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 [[autotargets-tutorial]]
 
 +AUTOTARGETS+ tutorial
-~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^
 
 First, let's see how to write a +.mk+ file for an autotools-based
 package, with an example :

@@ -64,7 +64,7 @@ package to be built.
 [[autotargets-reference]]
 
 +AUTOTARGETS+ reference
-~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^
 
 The main macro of the autotools package infrastructure is
 +AUTOTARGETS+. It has the same number of arguments and the

index 3e400ec..a6b2273 100644
@@ -1,10 +1,10 @@
 Infrastructure for CMake-based packages
----------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 [[cmaketargets-tutorial]]
 
 +CMAKETARGETS+ tutorial
-~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^
 
 First, let's see how to write a +.mk+ file for a CMake-based package,
 with an example :

@@ -63,7 +63,7 @@ package to be built.
 [[cmaketargets-reference]]
 
 +CMAKETARGETS+ reference
-~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 The main macro of the CMake package infrastructure is
 +CMAKETARGETS+. It has the same number of arguments and the same

index 3475827..d03dc4e 100644
@@ -1,5 +1,5 @@
 Conclusion
-----------
+~~~~~~~~~~
 
 As you can see, adding a software package to Buildroot is simply a
 matter of writing a Makefile using an  existing example and modifying it

index 2670f2f..1428f37 100644
@@ -1,5 +1,5 @@
 Package directory
------------------
+~~~~~~~~~~~~~~~~~
 
 First of all, create a directory under the +package+ directory for
 your software, for example +libfoo+.

@@ -10,7 +10,7 @@ one of these categories, then create your package directory in these.
 
 
 +Config.in+ file
-~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^
 
 Then, create a file named +Config.in+. This file will contain the
 option descriptions related to our +libfoo+ software that will be used

@@ -146,7 +146,7 @@ so, the dependency also needs to be expressed in the +.mk+ file of the
 package.
 
 The +.mk+ file
-~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^
 
 Finally, here's the hardest part. Create a file named +libfoo.mk+. It
 describes how the package should be downloaded, configured, built,

index cfcee8c..c0ad89d 100644
@@ -1,5 +1,5 @@
 Infrastructure for packages with specific build systems
--------------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 By 'packages with specific build systems' we mean all the packages
 whose build system is not one of the standard ones, such as

@@ -9,7 +9,7 @@ system is based on hand-written Makefiles or shell scripts.
 [[gentargets-tutorial]]
 
 +GENTARGETS+ Tutorial
-~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^
 
 ------------------------------
 01: #############################################################

@@ -90,7 +90,7 @@ Makefile code necessary to make your package working.
 [[gentargets-reference]]
 
 +GENTARGETS+ Reference
-~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^
 
 The +GENTARGETS+ macro takes one optional argument. This argument can
 be used to tell if the package is a target package (cross-compiled for

index 1ed834e..7eced86 100644
@@ -1,5 +1,5 @@
 Gettext integration and interaction with packages
--------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Many packages that support internationalization use the gettext
 library. Dependencies for this library are fairly complicated and

index beb25f6..25fa93c 100644
@@ -1,7 +1,5 @@
-[[handwritten-tutorial]]
-
 Manual Makefile
----------------
+~~~~~~~~~~~~~~~
 
 *NOTE: new manual makefiles should not be created, and existing manual
 makefiles should be converted either to the generic, autotools or

index 0217e9f..91649d4 100644
@@ -1,5 +1,6 @@
+[[adding-packages]]
 Adding new packages to Buildroot
-================================
+--------------------------------
 
 This section covers how new packages (userspace libraries or
 applications) can be integrated into Buildroot. It also shows how

new file mode 100644
index 0000000..f433c13
@@ -0,0 +1,10 @@
+Advanced usage
+--------------
+
+include::using-buildroot-toolchain.txt[]
+
+include::external-toolchain.txt[]
+
+include::ccache-support.txt[]
+
+include::download-location.txt[]

index d1d9d63..e8142ab 100644
@@ -1,5 +1,6 @@
+[[board-support]]
 Creating your own board support
-===============================
+-------------------------------
 
 Creating your own board support in Buildroot allows users of a
 particular hardware platform to easily build a system that is known to

index ab8cbad..37a9f92 100644
@@ -1,5 +1,6 @@
+[[ccache]]
 Using +ccache+ in Buildroot
-===========================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 http://ccache.samba.org[ccache] is a compiler cache. It stores the
 object files resulting from each compilation process, and is able to

new file mode 100644
index 0000000..ff8543f
@@ -0,0 +1,4 @@
+Daily use
+---------
+
+include::rebuilding-packages.txt[]

index 60e6a55..880fe3a 100644
@@ -1,6 +1,6 @@
-Customizing the Busybox configuration
--------------------------------------
 [[busybox-custom]]
+Customizing the Busybox configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 http://www.busybox.net/[Busybox] is very configurable, and you may
 want to customize it. You can follow these simple steps to do so. This

@@ -20,5 +20,5 @@ Otherwise, you can simply change the
 options you want to change, without using the configuration tool.
 
 If you want to use an existing config file for busybox, then see
-section xref:env-vars[].
+xref:env-vars[].
 

index 6bafe46..93470be 100644
@@ -1,5 +1,6 @@
+[[kernel-custom]]
 Customizing the Linux kernel configuration
-------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The Linux kernel configuration can be customized just like
 xref:busybox-custom[BusyBox] and xref:uclibc-custom[uClibc] using

index 8c3ea82..123c97f 100644
@@ -1,5 +1,6 @@
+[[rootfs-custom]]
 Customizing the generated target filesystem
--------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 There are a few ways to customize the resulting target filesystem:
 

index 08b60a2..b4ac4a4 100644
@@ -1,12 +1,12 @@
-Customizing the toolchain
--------------------------
 [[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.

@@ -15,7 +15,7 @@ It also requires to set the Buildroot settings according to the toolchain ones
 (see xref:external-toolchain[]).
 
 Using the internal Buildroot toolchain backend
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The internal Buildroot toolchain backend *only* allows to generate
 *http://www.uclibc.org/[uClibc]-based toolchains*.

@@ -32,7 +32,7 @@ This is directly available after selecting the +Buildroot toolchain+ type in
 the menu +Toolchain+.
 
 Using the Crosstool-NG backend
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The http://crosstool-ng.org[crosstool-NG] toolchain backend enables a rather
 limited set of settings under the Buildroot +Toolchain+ menu (ie. when invoking

index e2e6799..6db4e41 100644
@@ -1,6 +1,6 @@
-Customizing the uClibc configuration
-------------------------------------
 [[uclibc-custom]]
+Customizing the uClibc configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Just like xref:busybox-custom[BusyBox], http://www.uclibc.org/[uClibc]
 offers a lot of configuration options. They allow you to select

index e8235de..8778fdd 100644
@@ -1,5 +1,5 @@
 Customization
-=============
+-------------
 
 include::customize-rootfs.txt[]
 

new file mode 100644
index 0000000..69f3632
@@ -0,0 +1,6 @@
+Developer Guidelines
+====================
+
+include::adding-packages.txt[]
+
+include::board-support.txt[]

index cb6147f..7ac98c0 100644
@@ -1,5 +1,5 @@
 Location of downloaded packages
-===============================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 It might be useful to know that the various tarballs that are
 downloaded by the Makefiles are all stored in the +DL_DIR+ which by

index 62eb0a3..30efe42 100644
@@ -1,6 +1,6 @@
-Using an external toolchain
-===========================
 [[external-toolchain]]
+Using an external toolchain
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Using an already existing toolchain is useful for different
 reasons:

index 42ca009..6cfdefb 100644
@@ -1,5 +1,6 @@
+[[getting-buildroot]]
 Getting Buildroot
-=================
+-----------------
 
 Buildroot releases are made approximately every 3 months. Direct Git
 access and daily snapshots are also available, if you want more

new file mode 100644
index 0000000..6f3cd6e
@@ -0,0 +1,6 @@
+Going further in Buildroot's innards
+====================================
+
+include::how-buildroot-works.txt[]
+
+include::advanced.txt[]

index 481e5a4..1e86ca3 100644
@@ -1,5 +1,5 @@
 How Buildroot works
-===================
+-------------------
 
 As mentioned above, Buildroot is basically a set of Makefiles that
 download, configure, and compile software with the correct options. It

new file mode 100644
index 0000000..3d741a9
@@ -0,0 +1,4 @@
+Legal notice
+============
+
+TODO

index 732b50c..b35b5f6 100644
@@ -11,24 +11,20 @@ image::logo.png[]
 
 include::introduction.txt[]
 
-include::getting.txt[]
+include::starting-up.txt[]
 
-include::using.txt[]
 
-include::customize.txt[]
 
-include::rebuilding-packages.txt[]
+include::working-with.txt[]
 
-include::how-buildroot-works.txt[]
 
-include::using-buildroot-toolchain.txt[]
 
-include::external-toolchain.txt[]
 
-include::ccache-support.txt[]
+include::going-further.txt[]
 
-include::download-location.txt[]
+include::developer-guide.txt[]
+
+include::legal-notice.txt[]
 
-include::adding-packages.txt[]
 
 include::appendix.txt[]

index f247dd0..717121a 100644
@@ -1,5 +1,5 @@
 Understanding how to rebuild packages
-=====================================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 One of the most common questions asked by Buildroot users is how to
 rebuild a given package or how to remove a package without rebuilding

new file mode 100644
index 0000000..4f567f0
@@ -0,0 +1,7 @@
+Starting up
+===========
+
+include::getting.txt[]
+
+include::using.txt[]
+

index 712e9a8..24e797f 100644
@@ -1,5 +1,5 @@
 Using the generated toolchain outside Buildroot
-===============================================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You may want to compile, for your target, your own programs or other
 software that are not packaged in Buildroot. In order to do this you

index a5dc9e1..88dc58c 100644
@@ -1,8 +1,5 @@
 Using Buildroot
-===============
-
-Configuration and general usage
--------------------------------
+---------------
 
 Buildroot has a nice configuration tool similar to the one you can
 find in the http://www.kernel.org/[Linux kernel] or in

new file mode 100644
index 0000000..e444204
@@ -0,0 +1,10 @@
+Working with Buildroot
+======================
+[[working-with-br]]
+
+include::customize.txt[]
+
+include::common-usage.txt[]
+
+Tweaking Buildroot
+------------------

new file mode 100644
index 0000000..bf14d7c
@@ -0,0 +1,67 @@
+Embedded system basics & Reasons to use Buildroot
+-------------------------------------------------
+
+Cross-compilation & cross-toolchain
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A compilation toolchain is the set of tools that allows you to compile
+code for your system. It consists of a compiler (in our case, +gcc+),
+binary utils like assembler and linker (in our case, +binutils+) and a
+C standard library (for example
+http://www.gnu.org/software/libc/libc.html[GNU Libc],
+http://www.uclibc.org/[uClibc] or
+http://www.fefe.de/dietlibc/[dietlibc]). The system installed on your
+development station certainly already has a compilation toolchain that
+you can use to compile an application that runs on your system. If
+you're using a PC, your compilation toolchain runs on an x86 processor
+and generates code for an x86 processor. Under most Linux systems, the
+compilation toolchain uses the GNU libc (glibc) as the C standard
+library.  This compilation toolchain is called the "host compilation
+toolchain". The machine on which it is running, and on which you're
+working, is called the "host system". The compilation toolchain is
+provided by your distribution, and Buildroot has nothing to do with it
+(other than using it to build a cross-compilation toolchain and other
+tools that are run on the development host).
+
+As said above, the compilation toolchain that comes with your system
+runs on and generates code for the processor in your host system. As
+your embedded system has a different processor, you need a
+cross-compilation toolchain - a compilation toolchain that runs on
+your host system but generates code for your target system (and target
+processor). For example, if your host system uses x86 and your target
+system uses ARM, the regular compilation toolchain on your host runs on
+x86 and generates code for x86, while the cross-compilation toolchain
+runs on x86 and generates code for ARM.
+
+[[pros-buildroot]]
+
+Why choose Buildroot
+~~~~~~~~~~~~~~~~~~~~
+
+Even if your embedded system uses an x86 processor, you might be
+interested in Buildroot for two reasons:
+
+* The compilation toolchain on your host certainly uses the GNU Libc
+  which is a complete but huge C standard library. Instead of using
+  GNU Libc on your target system, you can use uClibc which is a tiny C
+  standard library. If you want to use this C library, then you need a
+  compilation toolchain to generate binaries linked with it. Buildroot
+  can do that for you.
+
+* Buildroot automates the building of a root filesystem with all
+  needed tools like busybox. That makes it much easier than doing it
+  by hand.
+
+You might wonder why such a tool is needed when you can compile +gcc+,
++binutils+, +uClibc+ and all the other tools by hand. Of course doing
+so is possible but, dealing with all of the configure options and
+problems of every +gcc+ or +binutils+ version is very time-consuming
+and uninteresting.  Buildroot automates this process through the use
+of Makefiles and has a collection of patches for each +gcc+ and
++binutils+ version to make them work on most architectures.
+
+Moreover, Buildroot provides an infrastructure for reproducing the
+build process of your kernel, cross-toolchain, and embedded root
+filesystem. Being able to reproduce the build process will be useful
+when a component needs to be patched or updated or when another person
+is supposed to take over the project.

index 6f3cd6e..67162a6 100644
@@ -1,6 +1,8 @@
 Going further in Buildroot's innards
 ====================================
 
+include::embedded-basics.txt[]
+
 include::how-buildroot-works.txt[]
 
 include::advanced.txt[]

82 lines not on this page · raw message

new file mode 100644
index 0000000..6ed3072
@@ -0,0 +1,62 @@
+[[requirement]]
+System requirements
+-------------------
+
+Buildroot is design to run on Linux system.
+
+Buildroot needs some software to be already installed on the host
+system; hereafter the lists of the mandatory and optional packages
+(packages' name may vary between distribution).
+
+Take care of _installing both runtime and development data_, especially
+for the libraries that may be packaged in 2 distinct packages.
+
+
+[[requirement-mandatory]]
+
+Mandatory packages
+~~~~~~~~~~~~~~~~~~
+
+* Build tools:
+** +build-essential+ (only for Debian based system)
+** +gcc+
+** +g+++
+** +bison+
+** +flex+
+** +gettext+
+** +patch+
+
+* Source fetching tools:
+** +wget+
+
+* Development libraries:
+** +ncurses5+
+
+[[requirement-optional]]
+
+Optional packages
+~~~~~~~~~~~~~~~~~
+
+* Build tools:
+** +gawk+
+
+* Source fetching tools:
+** +cvs+
+** +git+
+** +mercurial+
+** +subversion+
+
+* Configuration interface dependencies (requires development libraries):
+** +qt4+ to use the 'xconfig' interface
+** +glib2+, +gtk2+ and +glade2+ to use the 'gconfig' interface
+
+* Development libraries:
+** +zlib1+
+** +netpbm10+ (for +fbtest+)
+** +python-xcbgen+ (for +Matchbox+ on Debian based system)
+// ** +jdk+ and and depending on the host system +gcj-compat+ for Java
+// development (for +java+, +jamvm+ and +gnu-classpath+)
+
+* Documentation generation tools:
+** +asciidoc+
+** +texinfo+

index 4f567f0..3a74ea6 100644
@@ -1,6 +1,8 @@
 Starting up
 ===========
 
+include::prerequisite.txt[]
+
 include::getting.txt[]
 
 include::using.txt[]

index ff8543f..dde1ab0 100644
@@ -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
+--------------------

122 lines not on this page · raw message

new file mode 100644
index 0000000..a512689
@@ -0,0 +1,48 @@
+[[make-tips]]
+'make' tips
+-----------
+
+Because Buildroot is a set of Makefiles and patches, there are few
+things useful to know, such as:
+
+Display all command executed by make:
+
+--------------------
+ $ make V=0|1 <target>
+--------------------
+
+Display all available targets:
+
+--------------------
+ $ make help
+--------------------
+
+Note that, some settings in the +.config+ file may hide some targets
+like:
+
+* +busybox-menuconfig+ depends whether +busybox+ is enabled or not in
+  the +Package selection+ menu
+* +linux-menuconfig+ and +linux-savedefconfig+ depends on whether
+  +linux+ is enabled or not
+* +uclibc-menuconfig+ depends on whether the toolchain uses the
+  Buildroot internal toolchain backend or not
+* +ctng-menuconfig+ depends on whether the toolchain uses the
+  crosstool-NG backend or not
+* +barebox-menuconfig+ and +barebox-savedefconfig+ depends on whether
+  +barebox+ bootloader is enabled or not
+
+Delete all build products (including build directories, host, staging
+and target trees, the images and the toolchain):
+
+--------------------
+ $ make clean
+--------------------
+
+Delete all build products as well as the configuration:
+
+--------------------
+ $ make distclean
+--------------------
+
+Note that if +ccache+ is enabled, running +make clean|distclean+ does
+not empty the Buildroot's cache. To delete it, refer to xref:ccache[].

index e444204..01f1041 100644
@@ -2,6 +2,8 @@ Working with Buildroot
 ======================
 [[working-with-br]]
 
+include::make-tips.txt[]
+
 include::customize.txt[]
 
 include::common-usage.txt[]

index 717121a..6b486cf 100644
@@ -29,8 +29,8 @@ by the different packages, so some understanding of the particular
 package is needed.
 
 For packages relying on Buildroot packages infrastructures (see
-xref:add-packages[this section] for details), the following stamp
-files are relevant:
+xref:adding-packages[] for details), the following stamp files are
+relevant:
 
 * +output/build/packagename-version/.stamp_configured+. If removed,
   Buildroot will trigger the recompilation of the package from the

index 01f1041..b9d915c 100644
@@ -1,6 +1,9 @@
 Working with Buildroot
 ======================
-[[working-with-br]]
+
+This section aims to explain how Buildroot allows you to tune,
+customize almost everthing... making your configuration fitting your
+needs.
 
 include::make-tips.txt[]
 

@@ -10,3 +13,10 @@ include::common-usage.txt[]
 
 Tweaking Buildroot
 ------------------
+
+Because Buildroot does not yet fit all your requirements, you may be
+intrested in tweaking it to add:
+
+* new packages: refer to the xref:adding-packages[Developer guide]
+
+* new board support: refer to the xref:board-support[Developer guide]

index 123c97f..d067e31 100644
@@ -2,7 +2,9 @@
 Customizing the generated target filesystem
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-There are a few ways to customize the resulting target filesystem:
+Apart changing one or another configuration through +make
+*-menuconfig+, there are a few ways to customize the resulting target
+filesystem:
 
 * Customize the target filesystem directly and rebuild the image.  The
   target filesystem is available under +output/target/+.  You can

index b35b5f6..aa0952e 100644
@@ -17,6 +17,7 @@ include::starting-up.txt[]
 
 include::working-with.txt[]
 
+include::troubleshooting.txt[]
 
 
 

46 lines not on this page · raw message

index 1428f37..e36eafc 100644
@@ -145,6 +145,9 @@ is also enabled, but not necessarily built before your package. To do
 so, the dependency also needs to be expressed in the +.mk+ file of the
 package.
 
+Further formating details: see xref:writing-rules-config-in[the
+writing rules].
+
 The +.mk+ file
 ^^^^^^^^^^^^^^
 

@@ -185,3 +188,5 @@ different way, using different infrastructures:
   many of them in the tree, we keep them documented in a
   xref:handwritten-tutorial[tutorial].
 
+Further formating details: see xref:writing-rules-mk[the writing
+rules].

index 69f3632..14589c2 100644
@@ -1,6 +1,8 @@
 Developer Guidelines
 ====================
 
+include::writing-rules.txt[]
+
 include::adding-packages.txt[]
 
 include::board-support.txt[]

119 lines not on this page · raw message

new file mode 100644
index 0000000..9b6e843
@@ -0,0 +1,67 @@
+Getting involved
+================
+
+Like any open source projects, Buildroot has different ways to share
+information in its community and outside.
+
+One piece of it is the document you are currently reading ;-).
+
+Each of those ways may interest you if you are look for some help,
+want to understand Buildroot or contribute to the project.
+
+Mailing List
+------------
+
+Buildroot has a mailing list
+http://lists.busybox.net/pipermail/buildroot[] for discussion and
+development.
+
+[[mailing-list-subscribe]]
+
+Subscribing to the mailing list
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can subscribe by visiting
+http://lists.busybox.net/mailman/listinfo/buildroot[].
+Only subscribers to the Buildroot mailing list are allowed to post to
+this list.
+
+The list is also available through _Gmane_ http://gmane.org[], at
++gmane.comp.lib.uclibc.buildroot+
+http://dir.gmane.org/gmane.comp.lib.uclibc.buildroot[].
+
+Searching the List Archives
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Please search the mailing list archives before asking questions on the
+mailing list, since there is a good chance someone else has asked the
+same question before. Checking the archives is a great way to avoid
+annoying everyone on the list with frequently asked questions...
+
+IRC
+---
+
+The Buildroot IRC is irc://freenode.net/#buildroot[].
+The channel +#buildroot+ is hosted on Freenode
+http://webchat.freenode.net[].
+
+When asking for help on the IRC, share relevant logs or piece of code
+using a code sharing website (see
+http://en.wikipedia.org/wiki/Comparison_of_pastebins[], and pick up
+one).
+
+Bugtracker
+----------
+
+The Buildroot bugtracker is at https://bugs.uclibc.org[].
+
+Buildroot wikipage
+------------------
+
+Consecutively to the Buildroot developer day February 3, 2012,
+a page dedicated to Buildroot has been created on
+http://elinux.org[elinux.org].
+
+This page is reachable at http://elinux.org/Buildroot[].
+
+Currently, this page is mainly used as a _todo-list_.

index aa0952e..b23e9c1 100644
@@ -25,6 +25,8 @@ include::going-further.txt[]
 
 include::developer-guide.txt[]
 
+include::get-involved.txt[]
+
 include::legal-notice.txt[]
 
 

new file mode 100644
index 0000000..d80e79a
@@ -0,0 +1,63 @@
+Contibuting to Buildroot
+========================
+
+If you want to contribute to Buildroot, you will need a git view of
+the project. Refer to xref:getting-buildroot[] to get it.
+
+Currently, the mailing list is the central place for contribution.
+If you have not already subscribe to it, then refer to
+xref:mailing-list-subscribe[].
+
+Submiting patches
+-----------------
+
+When your changes are done, and commited in your local git view,
+_rebase_ your development branch on top of the upstream tree before
+generating the patch set. To do so, run:
+
+---------------------
+ $ git fetch --all --tags
+ $ git rebase origin/master
+---------------------
+
+Here, your are ready to generate then submit your patch set.
+
+To generate it, run:
+
+---------------------
+ $ git format-patch -M -n -s -o outgoing origin/master
+---------------------
+
+This will generate patch files in the +outgoing+ subdirectory,
+automatically adding the +signed-of-by+ line.
+
+If you want to present the whole patch set in a separate mail, add
++--cover-letter --summary+ to the previous command line (+man
+git-format-patch+ for further information).
+
+Once patch files are generated, you can review/edit the commit message
+before submitting them using your favourite text editor.
+
+Lastly, send/submit your patch set to the Buildroot mailing list:
+
+---------------------
+ $ git send-email --to buildroot at busybox.net outgoing/*
+---------------------
+
+Note that +git+ should be configured to use your mail account.
+To configure +git+, see +man git-send-email+ or google it.
+
+Reviewing/Testing patches
+-------------------------
+
+In the review process, do not hesitate to respond to patch submissions
+for remarks, suggestions or anything that will help everyone to
+understand the patches and make them better.
+
+Some tags are used to help following the state of any patch posted on
+the mailing-list:
+
+Acked-by:: Indicates that the patch can be committed.
+
+Tested-by:: Indicates that the patch has been tested. It is useful
+  but not necessary to add a comment about what has been tested.

index b23e9c1..3e7a7ef 100644
@@ -27,6 +27,8 @@ include::developer-guide.txt[]
 
 include::get-involved.txt[]
 
+include::contribute.txt[]
+
 include::legal-notice.txt[]