Pull request for branch for-2012/doc

index 9f0f6a9..403ad75 100755
@@ -131,12 +131,10 @@ if ! $SHELL --version 2>&1 | grep -q '^GNU bash'; then
 fi;
 
 # Check that a few mandatory programs are installed
-for prog in awk bison flex msgfmt makeinfo patch gzip bzip2 perl tar wget cpio python unzip rsync ${DL_TOOLS} ; do
+for prog in awk bison flex msgfmt patch gzip bzip2 perl tar wget cpio python unzip rsync ${DL_TOOLS} ; do
     if ! which $prog > /dev/null ; then
 	/bin/echo -e "\nYou must install '$prog' on your build machine";
-	if test $prog = "makeinfo" ; then
-	    /bin/echo -e "makeinfo is usually part of the texinfo package in your distribution\n"
-	elif test $prog = "msgfmt" ; then
+	if test $prog = "msgfmt" ; then
 	    /bin/echo -e "msgfmt is usually part of the gettext package in your distribution\n"
 	elif test $prog = "svn" ; then
 	    /bin/echo -e "svn is usually part of the subversion package in your distribution\n"

index 1eaf73a..83d2fcb 100644
@@ -38,10 +38,10 @@ $(call GENDOC_INNER,$(1),chunked,split-html,chunked,Split HTML)
 $(call GENDOC_INNER,$(1),pdf,pdf,pdf,PDF,--dblatex-opts "-P latex.output.revhistory=0")
 $(call GENDOC_INNER,$(1),text,txt,text,Text)
 $(call GENDOC_INNER,$(1),epub,epub,epub,EPUB)
-clean: clean-$(1)
-clean-$(1):
+clean clean-$(1): $(1)-clean
+$(1)-clean:
 	$(Q)$(RM) -rf $(O)/docs/$(1)
-.PHONY: $(1) clean-$(1)
+.PHONY: $(1) $(1)-clean
 endef
 
 MANUAL_SOURCES = $(wildcard docs/manual/*.txt) $(wildcard docs/images/*)

index 1eaf73a..fd9091e 100644
@@ -38,10 +38,10 @@ $(call GENDOC_INNER,$(1),chunked,split-html,chunked,Split HTML)
 $(call GENDOC_INNER,$(1),pdf,pdf,pdf,PDF,--dblatex-opts "-P latex.output.revhistory=0")
 $(call GENDOC_INNER,$(1),text,txt,text,Text)
 $(call GENDOC_INNER,$(1),epub,epub,epub,EPUB)
-clean: clean-$(1)
-clean-$(1):
+clean: $(1)-clean
+$(1)-clean:
 	$(Q)$(RM) -rf $(O)/docs/$(1)
-.PHONY: $(1) clean-$(1)
+.PHONY: $(1) $(1)-clean
 endef
 
 MANUAL_SOURCES = $(wildcard docs/manual/*.txt) $(wildcard docs/images/*)

index 83d2fcb..0043ebf 100644
@@ -33,8 +33,8 @@ endef
 # The variable <DOCUMENT_NAME>_SOURCES defines the dependencies.
 ################################################################################
 define GENDOC
-$(call GENDOC_INNER,$(1),xhtml,html,html,HTML)
-$(call GENDOC_INNER,$(1),chunked,split-html,chunked,Split HTML)
+$(call GENDOC_INNER,$(1),xhtml,html,html,HTML,--xsltproc-opts "--stringparam toc.section.depth 4")
+$(call GENDOC_INNER,$(1),chunked,split-html,chunked,Split HTML,--xsltproc-opts "--stringparam toc.section.depth 4")
 $(call GENDOC_INNER,$(1),pdf,pdf,pdf,PDF,--dblatex-opts "-P latex.output.revhistory=0")
 $(call GENDOC_INNER,$(1),text,txt,text,Text)
 $(call GENDOC_INNER,$(1),epub,epub,epub,EPUB)

index b85b7af..1184b69 100644
@@ -1,10 +1,12 @@
+// -*- mode:doc; -*-
+
 Infrastructure for autotools-based packages
--------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 [[autotools-package-tutorial]]
 
 +autotools-package+ tutorial
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 First, let's see how to write a +.mk+ file for an autotools-based
 package, with an example :

@@ -64,7 +66,7 @@ package to be built.
 [[autotools-package-reference]]
 
 +autotools-package+ reference
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The main macro of the autotools package infrastructure is
 +autotools-package+. It is similar to the +generic-package+ macro. The ability to

index da4984a..81ac0a7 100644
@@ -1,10 +1,12 @@
+// -*- mode:doc; -*-
+
 Infrastructure for CMake-based packages
----------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 [[cmake-package-tutorial]]
 
 +cmake-package+ tutorial
-~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 First, let's see how to write a +.mk+ file for a CMake-based package,
 with an example :

@@ -63,7 +65,7 @@ package to be built.
 [[cmake-package-reference]]
 
 +cmake-package+ reference
-~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The main macro of the CMake package infrastructure is
 +cmake-package+. It is similar to the +generic-package+ macro. The ability to

index 3475827..ac20875 100644
@@ -1,5 +1,7 @@
+// -*- mode:doc; -*-
+
 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 4a96415..6030e08 100644
@@ -1,5 +1,7 @@
+// -*- mode:doc; -*-
+
 Package directory
------------------
+~~~~~~~~~~~~~~~~~
 
 First of all, create a directory under the +package+ directory for
 your software, for example +libfoo+.

@@ -10,7 +12,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 +148,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 7ecdb91..e3f16c2 100644
@@ -1,5 +1,7 @@
+// -*- mode:doc; -*-
+
 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 +11,7 @@ system is based on hand-written Makefiles or shell scripts.
 [[generic-package-tutorial]]
 
 +generic-package+ Tutorial
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ------------------------------
 01: #############################################################

@@ -90,7 +92,7 @@ Makefile code necessary to make your package working.
 [[generic-package-reference]]
 
 +generic-package+ Reference
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 There are two variants of the generic target. The +generic-package+ macro is
 used for packages to be cross-compiled for the target.  The

index e0df1a4..89461a7 100644
@@ -1,5 +1,7 @@
+// -*- mode:doc; -*-
+
 Gettext integration and interaction with packages
--------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Many packages that support internationalization use the gettext
 library. Dependencies for this library are fairly complicated and

index f672ec6..8221c85 100644
@@ -1,6 +1,8 @@
-Adding new packages to Buildroot
-================================
+// -*- mode:doc -*- ;
+
 [[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..cd53182
@@ -0,0 +1,12 @@
+// -*- mode:doc; -*-
+
+Advanced usage
+--------------
+
+include::using-buildroot-toolchain.txt[]
+
+include::external-toolchain.txt[]
+
+include::ccache-support.txt[]
+
+include::download-location.txt[]

index f41c82c..a6642b5 100644
@@ -1,3 +1,5 @@
+// -*- mode:doc; -*-
+
 Appendix
 ========
 

index d1d9d63..e20e721 100644
@@ -1,5 +1,8 @@
+// -*- mode:doc -*- ;
+
+[[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..95cd662 100644
@@ -1,5 +1,8 @@
+// -*- mode:doc -*- ;
+
+[[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..b343606
@@ -0,0 +1,6 @@
+// -*- mode:doc; -*-
+
+Daily use
+---------
+
+include::rebuilding-packages.txt[]

index 60e6a55..fe9cdda 100644
@@ -1,6 +1,8 @@
-Customizing the Busybox configuration
--------------------------------------
+// -*- mode:doc -*- ;
+
 [[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 +22,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..1072270 100644
@@ -1,5 +1,8 @@
+// -*- mode:doc -*- ;
+
+[[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 44007c7..7ac5195 100644
@@ -1,5 +1,8 @@
+// -*- mode:doc -*- ;
+
+[[rootfs-custom]]
 Customizing the generated target filesystem
--------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 There are a few ways to customize the resulting target filesystem:
 

index 08b60a2..91657cf 100644
@@ -1,12 +1,14 @@
-Customizing the toolchain
--------------------------
+// -*- mode:doc -*- ;
+
 [[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 +17,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 +34,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..88121ea 100644
@@ -1,6 +1,8 @@
-Customizing the uClibc configuration
-------------------------------------
+// -*- mode:doc -*- ;
+
 [[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..1e6f4e8 100644
@@ -1,5 +1,7 @@
+// -*- mode:doc; -*-
+
 Customization
-=============
+-------------
 
 include::customize-rootfs.txt[]
 

new file mode 100644
index 0000000..37f703d
@@ -0,0 +1,8 @@
+// -*- mode:doc; -*-
+
+Developer Guidelines
+====================
+
+include::adding-packages.txt[]
+
+include::board-support.txt[]

index cb6147f..8c66a76 100644
@@ -1,5 +1,7 @@
+// -*- mode:doc; -*-
+
 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..b337376 100644
@@ -1,6 +1,8 @@
-Using an external toolchain
-===========================
+// -*- mode:doc -*- ;
+
 [[external-toolchain]]
+Using an external toolchain
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Using an already existing toolchain is useful for different
 reasons:

index 42ca009..a51caa0 100644
@@ -1,5 +1,8 @@
+// -*- mode:doc -*- ;
+
+[[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..879cff3 100644
@@ -1,5 +1,7 @@
+// -*- mode:doc; -*-
+
 How Buildroot works
-===================
+-------------------
 
 As mentioned above, Buildroot is basically a set of Makefiles that
 download, configure, and compile software with the correct options. It

index 4728c4b..4703b2f 100644
@@ -1,3 +1,5 @@
+// -*- mode:doc -*- ;
+
 [[makedev-syntax]]
 Makedev syntax documentation
 ----------------------------

index de4b594..00bd037 100644
@@ -1,3 +1,5 @@
+// -*- mode:doc; -*-
+
 The Buildroot user manual
 =========================
 :toc:

@@ -11,25 +13,13 @@ image::logo.png[]
 
 include::introduction.txt[]
 
-include::getting.txt[]
-
-include::using.txt[]
-
-include::customize.txt[]
-
-include::rebuilding-packages.txt[]
-
-include::how-buildroot-works.txt[]
-
-include::using-buildroot-toolchain.txt[]
-
-include::external-toolchain.txt[]
+include::starting-up.txt[]
 
-include::ccache-support.txt[]
+include::working-with.txt[]
 
-include::download-location.txt[]
+include::going-further.txt[]
 
-include::adding-packages.txt[]
+include::developer-guide.txt[]
 
 include::faq.txt[]
 

index fb6d696..824b35c 100644
@@ -1,5 +1,7 @@
+// -*- mode:doc -*- ;
+
 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..8ba16c9
@@ -0,0 +1,9 @@
+// -*- mode:doc; -*-
+
+Starting up
+===========
+
+include::getting.txt[]
+
+include::using.txt[]
+

index 712e9a8..750fa99 100644
@@ -1,5 +1,7 @@
+// -*- mode:doc; -*-
+
 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 fcbd24b..5741473 100644
@@ -1,8 +1,7 @@
-Using Buildroot
-===============
+// -*- mode:doc; -*-
 
-Configuration and general usage
--------------------------------
+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

new file mode 100644
index 0000000..3c57504
@@ -0,0 +1,21 @@
+// -*- mode:doc; -*-
+
+Working with Buildroot
+======================
+
+This section explains how you can customize Buildroot to fit your
+needs.
+
+include::customize.txt[]
+
+include::common-usage.txt[]
+
+Hacking Buildroot
+-----------------
+
+If Buildroot does not yet fit all your requirements, you may be
+interested in hacking it to add:
+
+* new packages: refer to the xref:adding-packages[Developer guide]
+
+* new board support: refer to the xref:board-support[Developer guide]

new file mode 100644
index 0000000..27dda37
@@ -0,0 +1,110 @@
+// -*- mode:doc; -*-
+
+Embedded system basics
+----------------------
+
+When developing an embedded system, there are a number of choices to
+do:
+
+* the cross-toolchain: target architecture/C library/...
+* the bootloader
+* kernel options
+* the device management
+* the init system
+* the package selection (busybox vs. "real" programs, ...)
+* ...
+
+Some of them may be influenced by the target hardware.
+
+Some of them may also add some constraints when you will develop the
+final application for what your target is designed (e.g. some
+functions may be provided by soem C libraries and missing in some
+others, ...). So, these choices should be carefully done.
+
+Buildroot allows to set most of these options to fit your needs.
+
+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.
+
+[[cross-compilation-and-cross-toolchain]]
+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.
+
+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.
+
+Buildroot offers a number of options and settings that can be tuned
+when defining the cross-toolchain (refer to xref:toolchain-custom[]).
+
+[[bootloader]]
+Bootloader
+~~~~~~~~~~
+
+TODO
+
+[[device-management]]
+Device management
+~~~~~~~~~~~~~~~~~
+
+TODO
+
+[[init-system]]
+Init system
+~~~~~~~~~~~
+
+TODO

index 6f3cd6e..15324c4 100644
@@ -1,6 +1,10 @@
+// -*- mode:doc; -*-
+
 Going further in Buildroot's innards
 ====================================
 
+include::embedded-basics.txt[]
+
 include::how-buildroot-works.txt[]
 
 include::advanced.txt[]

81 lines not on this page · raw message

index b343606..c08c10e 100644
@@ -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
+--------------------

125 lines not on this page · raw message

index 7ac5195..d6224ff 100644
@@ -4,7 +4,8 @@
 Customizing the generated target filesystem
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-There are a few ways to customize the resulting target filesystem:
+Besides changing one or another configuration through +make *config+,
+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

@@ -12,28 +13,33 @@ There are a few ways to customize the resulting target filesystem:
   rebuild the target filesystem image. This method allows you to do
   anything to the target filesystem, but if you decide to completely
   rebuild your toolchain and tools, these changes will be lost.
+  _Changes are not resistent to the +make clean+ command_.
 
 * Create your own 'target skeleton'. You can start with the default
   skeleton available under +system/skeleton+ and then customize it to
   suit your needs. The +BR2_ROOTFS_SKELETON_CUSTOM+ and
   +BR2_ROOTFS_SKELETON_CUSTOM_PATH+ will allow you to specify the
-  location of your custom skeleton. At build time, the contents of the
+  location of your custom skeleton. These options can be found in the
+  +System configuration+ menu. At build time, the contents of the
   skeleton are copied to output/target before any package
   installation.
 
 * In the Buildroot configuration, you can specify the path to a
-  post-build script, that gets called 'after' Buildroot builds all the
+  *post-build script*, that gets called 'after' Buildroot builds all the
   selected software, but 'before' the rootfs packages are
-  assembled. The destination root filesystem folder is given as the
-  first argument to this script, and this script can then be used to
-  copy programs, static data or any other needed file to your target
-  filesystem. You should, however, use this feature with care.
-  Whenever you find that a certain package generates wrong or unneeded
-  files, you should fix that package rather than work around it with a
-  post-build cleanup script.
+  assembled. The +BR2_ROOTFS_POST_BUILD_SCRIPT+ will allow you to
+  specify the location of your post-build script. This option can be
+  found in the +System configuration+ menu. The destination root
+  filesystem folder *is given as the first argument to this script,
+  and this script can then be used to copy programs, static data or
+  any other needed file to your target filesystem. You should,
+  however, use this feature with care. Whenever you find that a
+  certain package generates wrong or unneeded files, you should fix
+  that package rather than work around it with a post-build cleanup
+  script. _Among these first 3 methods, this one should be prefere_d.
 
 * A special package, 'customize', stored in +package/customize+ can be
   used. You can put all the files that you want to see in the final
   target root filesystem in +package/customize/source+, and then
-  enable this special package in the configuration system.
-
+  enable this special package in the configuration system. _This
+  method is marked as deprecated_.

index 824b35c..2225200 100644
@@ -1,5 +1,39 @@
 // -*- mode:doc -*- ;
 
+[[full-rebuild]]
+Understanding when a full rebuild is necessary
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A full rebuild is achieved by running:
+
+---------------
+$ make clean all
+---------------
+
+In what cases, a full rebuild is mandatory:
+
+* each time the toolchain properties are changed, this includes:
+
+** after changing some toolchain option under the _Toolchain_ menu (if
+   the internal Buildroot backend is used);
+** after running +make ctng-menuconfig+ (if the crosstool-NG backend
+   is used);
+** after running +make uclibc-menuconfig+.
+
+* after removing some libraries from the package selection.
+
+In what cases, a full rebuild is recommended:
+
+* after adding some libraries to the package selection (otherwise,
+  some packages that can be optionally linked against those libraries
+  won't be rebuilt, so they won't support those new available
+  features).
+
+In other cases, it is up to you to decide if you should or not run a
+full rebuild, but you should know what is impacted and understand what
+you are doing anyway.
+
+[[rebuild-pkg]]
 Understanding how to rebuild packages
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

@@ -42,27 +76,10 @@ files are relevant:
   Buildroot will trigger the recompilation of the package from the
   compilation step (execution of +make+).
 
-For other packages, an analysis of the specific 'package.mk' file is
-needed. For example, the zlib Makefile used to look like this (before
-it was converted to the generic package infrastructure):
-
------------------
-$(ZLIB_DIR)/.configured: $(ZLIB_DIR)/.patched
-	(cd $(ZLIB_DIR); rm -rf config.cache; \
-		[...]
-	)
-	touch $@
-
-$(ZLIB_DIR)/libz.a: $(ZLIB_DIR)/.configured
-	$(MAKE) -C $(ZLIB_DIR) all libz.a
-	touch -c $@
------------------
-
-If you want to trigger the reconfiguration, you need to remove
-+output/build/zlib-version/.configured+. If you want to trigger only
-the recompilation, you need to remove
-+output/build/zlib-version/libz.a+.
-
-Note that most packages, if not all, will progressively be ported over
-to the generic or autotools infrastructure, making it much easier to
-rebuild individual packages.
+.Notes
+- Since the _Buildroot-2012.11_ release, all packages rely on the
+Buildroot infrastructures.
+- Only toolchain packages remain using custom makefiles (i.e. do not
+use any Buildroot infrastructure).
+- Most packages and toolchain packages, if not all, will progressively
+be ported over to the generic, autotools or CMake infrastructure,

index 6030e08..35d28b6 100644
@@ -49,6 +49,7 @@ supposed to contain anything but the 'bare' name of the package.
 source "package/libfoo/Config.in"
 --------------------------
 
+[[depends-on-vs-select]]
 The +Config.in+ file of your package must also ensure that
 dependencies are enabled. Typically, Buildroot uses the following
 rules:

@@ -59,15 +60,26 @@ rules:
   dependencies are selected. For example, the _libgtk2_ package uses
   +select BR2_PACKAGE_LIBGLIB2+ to make sure this library is also
   enabled.
+  The +select+ keyword express the dependency with a backward
+  semantic.
 
 * Use a +depends on+ type of dependency when the user really needs to
   be aware of the dependency. Typically, Buildroot uses this type of
-  dependency for dependencies on toolchain options (large file
-  support, RPC support, IPV6 support), or for dependencies on "big"
-  things, such as the X.org system. In some cases, especially
-  dependency on toolchain options, it is recommended to add a
-  +comment+ displayed when the option is not enabled, so that the user
-  knows why the package is not available.
+  dependency for dependencies on toolchain options (target
+  architecture, MMU support, C library, C++ support, large file
+  support, thread support, RPC support, IPV6 support, WCHAR support),
+  or for dependencies on "big" things, such as the X.org system. In
+  some cases, especially dependency on toolchain options, it is
+  recommended to add a +comment+ displayed when the option is not
+  enabled, so that the user knows why the package is not available.
+  The +depends on+ keyword express the dependency with a forward
+  semantic.
+
+.Note
+The current problem with the _kconfig_ language is that these two
+dependency semantics are not internally linked. Therefore, it may be
+possible to select a package, whom one of its dependencies/requirement
+is not met.
 
 An example illustrates both the usage of +select+ and +depends on+.
 

@@ -147,6 +159,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
 ^^^^^^^^^^^^^^
 

@@ -182,8 +197,5 @@ different way, using different infrastructures:
    CMake. We cover them through a xref:cmake-package-tutorial[tutorial]
    and xref:cmake-package-reference[reference].
 
-* *Hand-written Makefiles:* These are currently obsolete, and no new
-  manual Makefiles should be added. However, since there are still
-  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].

new file mode 100644
index 0000000..b24731f
@@ -0,0 +1,84 @@
+// -*- mode:doc -*- ;
+
+[[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
+(package names may vary between distributions).
+
+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:
+
+** +which+
+** +sed+
+** +make+ (version 3.82 or any later)
+** +binutils+
+** +build-essential+ (only for Debian based systems)
+** +gcc+ (version 2.95 or any later)
+** `g++` (version 2.95 or any later)
+** +bash+
+** +gawk+
+** +bison+
+** +flex+
+** +gettext+
+** +patch+
+** +gzip+
+** +bzip2+
+** +perl+
+** +tar+
+** +cpio+
+** +python+ (version 2.6 or 2.7)
+** +unzip+
+** +rsync+
+
+* Source fetching tools:
+** +wget+
+
+* Configuration interface dependencies (requires development libraries):
+** +ncurses5+
+
+[[requirement-optional]]
+
+Optional packages
+~~~~~~~~~~~~~~~~~
+
+* Source fetching tools:
++
+In the official tree, most of the package sources are retrieved
+using +wget+, few are only available through their +git+, +mercurial+,
+or +svn+ repository.
++
+All other source fetching methods are implemented and may be used in a
+development context.
++
+** +bazaar+
+** +cvs+
+** +git+
+** +mercurial+
+** +rsync+
+** +scp+
+** +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)
+
+* Documentation generation tools:
+** +asciidoc+

index 8ba16c9..2999fd4 100644
@@ -3,6 +3,8 @@
 Starting up
 ===========
 
+include::prerequisite.txt[]
+
 include::getting.txt[]
 
 include::using.txt[]

new file mode 100644
index 0000000..5b00536
@@ -0,0 +1,58 @@
+// -*- mode:doc -*- ;
+
+[[make-tips]]
+'make' tips
+-----------
+
+Because Buildroot is a set of Makefiles and patches, there are few
+things useful to know, such as:
+
++make *config+ commands offer a search tool. Read the help message in
+the different frontend menu to know how to use it:
+
+* in _menuconfig_, search tool is called by pressing +/+;
+* in _xconfig_, search tool is called by pressing +ctrl+ + +f+.
+
+The result of the search show the help message of the matching items.
+
+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:
+
+* +busybox-menuconfig+ depends on whether +busybox+ is enabled or not
+  in the +Package selection+ menu
+* +linux-menuconfig+ and +linux-savedefconfig+ depend 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+ depend 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 cache of compiler used by Buildroot. To delete it, refer
+to xref:ccache[].

index 3c57504..4ea9239 100644
@@ -6,6 +6,8 @@ Working with Buildroot
 This section explains how you can customize Buildroot to fit your
 needs.
 
+include::make-tips.txt[]
+
 include::customize.txt[]
 
 include::common-usage.txt[]

new file mode 100644
index 0000000..6911c55
@@ -0,0 +1,134 @@
+// -*- mode:doc; -*-
+
+Frequently Asked Questions & Troubleshooting
+============================================
+
+[[faq-boot-hang-after-starting]]
+The boot hangs after 'Starting network...'
+------------------------------------------
+
+If the boot process seems to hand after the following messages
+(messages not necessarily exactly similar, depending on the list of
+packages selected):
+
+------------------------
+Freeing init memory: 3972K
+Initializing random number generator... done.
+Starting network...
+Starting dropbear sshd: generating rsa key... generating dsa key... OK
+------------------------
+
+then it means that your system is running, but didn't start a shell on
+the serial console. In order to have the system start a shell on your
+serial console, you have to go in the Buildroot configuration, +System
+configuration+, and modify +Port to run a getty (login prompt) on+ and
++Baudrate to use+ as appropriate. This will automatically tune the
++/etc/inittab+ file of the generated system so that a shell starts on
+the correct serial port.
+
+[[faq-module-init-tool-build-failure]]
+module-init-tools fails to build with 'cannot find -lc'
+-------------------------------------------------------
+
+If the build of +module-init-tools+ for the host fails with:
+
+------------------------
+/usr/bin/ld: cannot find -lc
+------------------------
+
+then probably you are running a Fedora (or similar) distribution, and
+you should install the +glibc-static+ package. This is because the
++module-init-tools+ build process wants to link statically against the
+C library.
+
+[[faq-no-compiler-on-target]]
+Why there is no compiler on the target?
+---------------------------------------
+
+It has been decided that the support of the _native compiler for the
+target_ would be stopped since the Buildroot-2012.11 release because:
+
+* this feature was not maintained nor tested and often broken;
+* this feature was only available for Buildroot toolchains;
+* Buildroot mostly targets _small_ or _very small_ target hardware
+  with limited resource onboard (CPU, ram, mass-storage), on which
+  compiling does not make much sense.
+
+If you need a compiler on your target anyway, then Buildroot is not
+suitable for your purpose. In such case, you need a _real
+distribution_ and you should for something like:
+
+* http://www.openembedded.org[openembedded]
+* https://www.yoctoproject.org[yocto]
+* http://www.emdebian.org[emdebian]
+* https://fedoraproject.org/wiki/Architectures[Fedora]
+* http://en.opensuse.org/Portal:ARM[openSUSE ARM]
+* http://archlinuxarm.org[Arch Linux ARM]
+* ...
+
+[[faq-no-dev-files-on-target]]
+Why there is no development files on the target?
+------------------------------------------------
+
+Since there is no compiler available on the target (see
+xref:faq-no-compiler-on-target[]), it does not make sense to waste
+space with headers or static libraries.
+
+Therefore, those files are always removed from the target since the
+Buildroot-2012.11 release.
+
+[[faq-no-doc-on-target]]
+Why there is no documentation on the target?
+--------------------------------------------
+
+Because Buildroot mostly targets _small_ or _very small_ target
+hardware with limited resource onboard (CPU, ram, mass-storage), it
+does not make sense to waste space with the documentation data.
+
+If you need documentation data on your target anyway, then Buildroot
+is not suitable for your purpose, and you should look for a _real
+distribution_ (see: xref:faq-no-compiler-on-target[]).
+
+[[faq-depends-on-vs-select]]
++Config.in+: _depends on_ vs _select_
+-------------------------------------
+
+When adding a new package to Buildroot, you will most likely have to
+deal with expressing the dependencies of this package.
+
+In the +Config.in+ file, dependencies may be expressed following two
+semantics.
+See xref:depends-on-vs-select[].
+
+[[faq-why-not-visible-package]]
+Why some packages are not visible in the Buildroot config menu?
+---------------------------------------------------------------
+
+If a package exists in the Buildroot tree and does not appears in the
+config menu, this most likely means that some of the package's
+dependencies are not met.
+
+To know more about the dependencies of a package, search the package
+symbol using in teh config menu (see xref:make-tips[]).
+
+Then, you may have to recursively enable several options (which
+correspond to the unmeet dependencies) to finally be able to select
+the package.
+
+If the package is not visible due to some unmeet toolchain options,
+then you should certainly run a full rebuild (see xref:make-tips[] for
+more explanations).
+
+[[faq-why-not-use-target-as-chroot]]
+Why not use the target directory as a chroot directory?
+-------------------------------------------------------
+
+There are plenty of reason to *not* use the target directory a chroot
+one, among these:
+
+* files' owners, modes and permissions are not correctly set in the
+  target directory;
+* devices nodes are not created in the target directory.
+
+Because of that, commands run in through chroot, using the target
+directory as new root, will fail.

59 lines not on this page · raw message

index 00bd037..4df1657 100644
@@ -17,10 +17,10 @@ include::starting-up.txt[]
 
 include::working-with.txt[]
 
+include::faq-troubleshooting.txt[]
+
 include::going-further.txt[]
 
 include::developer-guide.txt[]
 
-include::faq.txt[]
-
 include::appendix.txt[]

index 37f703d..b254b0f 100644
@@ -3,6 +3,8 @@
 Developer Guidelines
 ====================
 
+include::writing-rules.txt[]
+
 include::adding-packages.txt[]
 
 include::board-support.txt[]

125 lines not on this page · raw message

new file mode 100644
index 0000000..566516b
@@ -0,0 +1,98 @@
+// -*- mode:doc; -*-
+
+Getting involved
+================
+
+Like any open source project, 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 looking 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 IRC, share relevant logs or pieces of code
+using a code sharing website (see
+http://en.wikipedia.org/wiki/Comparison_of_pastebins[], and pick one).
+
+[[patchwork]]
+Patchwork
+---------
+
+The Buildroot patch management interface is at
+http://patchwork.buildroot.org[].
+
+All patches and comments sent through the mailing list are
+automatically indexed in http://patchwork.buildroot.org[patchwork].
+
+Bugtracker
+----------
+
+The Buildroot bugtracker is at https://bugs.busybox.net[].
+
+Buildroot wikipage
+------------------
+
+After the Buildroot developer day on 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_.
+
+[[events]]
+Events
+------
+
+Buildroot Developer Days aside ELC-E 2012 (November 3-4, 2012 - Barcelona)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Event page: http://elinux.org/Buildroot:DeveloperDaysELCE2012[]
+
+Buildroot presentation at LSM 2012 (July 12-14, 2012 - Geneva)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Announcement: http://lists.busybox.net/pipermail/buildroot/2012-May/053845.html[]
+
+Buildroot Developer Days aside FOSDEM 2012 (February 3, 2012 - Brussels)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Announcement & agenda thread: http://lists.busybox.net/pipermail/buildroot/2012-January/049340.html[]
+* Report: http://lists.busybox.net/pipermail/buildroot/2012-February/050371.html[]

index 4df1657..3331cbf 100644
@@ -23,4 +23,6 @@ include::going-further.txt[]
 
 include::developer-guide.txt[]
 
+include::get-involved.txt[]
+
 include::appendix.txt[]

new file mode 100644
index 0000000..ddf790d
@@ -0,0 +1,126 @@
+// -*- mode:doc; -*-
+
+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 subscribed to it, then refer to
+xref:mailing-list-subscribe[].
+
+Recently, a web interface is also used to manage patches sent to the
+mailing list, see xref:patchwork[].
+
+[NOTE]
+_Please, do not attach patches to bugs, send them to the mailing list
+instead_ (see xref:submitting-patches[]).
+
+[[submitting-patches]]
+Submitting patches
+------------------
+
+When your changes are done, and committed 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, you 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-off-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 favorite 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.
+
+Make sure posted *patches are not line-wrapped*, otherwise it cannot
+easily be applied. In such a case, fix your e-mail client, or better,
+use +git send-email+ to send your patches.
+
+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.
+
+Autobuild
+---------
+
+The Buildroot community is currently setting up automatic build i
+order to test more and more configuration. All build results are
+available at http://autobuild.buildroot.org[]
+
+A way to contribute is fixing broken builds.
+
+In the commit message of a patch fixing an _autobuild_, add a
+reference to the _build result directory_ (the +dir+ link in the _data
+column_):
+
+---------------------
+Fixes http://autobuild.buildroot.org/results/51000a9d4656afe9e0ea6f07b9f8ed374c2e4069
+---------------------
+
+[[reporting-bugs]]
+Reporting issues/bugs, get help
+-------------------------------
+
+Before reporting some issues, please chek
+xref:mailing-list-subscribe[the mailing list archive] in case someone had
+already reported and fixed a similar problem.
+
+Whatever the way you choose to report some bugs or get help,
+xref:bugtracker[opening a bug] or
+xref:mailing-list-subscribe[send a mail to the mailing list], there is
+a number of detail to provide in order to help people reproduce and
+find a solution to the issue.
+
+Try to think as you would be the one who will help someone else; in
+that case, what would you need?
+
+Here is a short list of details to provide in such case:
+
+* host machine (OS/release)
+* version of Buildroot
+* target for which the build fails
+* package(s) which the build fails
+* the command that fails and its output
+* any information you think that may be relevant
+
+Additionnally, your can add the +.config+ file.
+
+If some of these details are too large, do not hesitate to use some
+pastebin service (see
+http://en.wikipedia.org/wiki/Comparison_of_pastebins[]).

index 566516b..3a00b1e 100644
@@ -61,11 +61,14 @@ http://patchwork.buildroot.org[].
 All patches and comments sent through the mailing list are
 automatically indexed in http://patchwork.buildroot.org[patchwork].
 
+[[bugtracker]]
 Bugtracker
 ----------
 
 The Buildroot bugtracker is at https://bugs.busybox.net[].
 
+To open a bug, see xref:reporting-bugs[].
+
 Buildroot wikipage
 ------------------
 

index 3331cbf..4032a6b 100644
@@ -25,4 +25,6 @@ include::developer-guide.txt[]
 
 include::get-involved.txt[]
 
+include::contribute.txt[]
+
 include::appendix.txt[]

index cd53182..ba6574c 100644
@@ -10,3 +10,5 @@ include::external-toolchain.txt[]
 include::ccache-support.txt[]
 
 include::download-location.txt[]
+
+include::package-make-target.txt[]

88 lines not on this page · raw message

index 2225200..a723d11 100644
@@ -83,3 +83,7 @@ Buildroot infrastructures.
 use any Buildroot infrastructure).
 - Most packages and toolchain packages, if not all, will progressively
 be ported over to the generic, autotools or CMake infrastructure,
+making it much easier to rebuild individual packages.
+
+Further details about package special make target at the
+xref:pkg-build-steps[].

index b254b0f..f3fc1dd 100644
@@ -7,4 +7,6 @@ include::writing-rules.txt[]
 
 include::adding-packages.txt[]
 
+include::download-infra.txt[]
+
 include::board-support.txt[]

new file mode 100644
index 0000000..63908ad
@@ -0,0 +1,8 @@
+// -*- mode:doc -*- ;
+
+[[download-infra]]
+
+Download infrastructure
+-----------------------
+
+TODO

index b24731f..693347b 100644
@@ -61,7 +61,7 @@ using +wget+, few are only available through their +git+, +mercurial+,
 or +svn+ repository.
 +
 All other source fetching methods are implemented and may be used in a
-development context.
+development context (further details: refer to xref:download-infra[]).
 +
 ** +bazaar+
 ** +cvs+

index f3fc1dd..5002897 100644
@@ -7,6 +7,8 @@ include::writing-rules.txt[]
 
 include::adding-packages.txt[]
 
+include::patch-policy.txt[]
+
 include::download-infra.txt[]
 
 include::board-support.txt[]

128 lines not on this page · raw message

new file mode 100644
index 0000000..acc73d3
@@ -0,0 +1,54 @@
+// -*- mode:doc; -*-
+
+Tips and tricks
+~~~~~~~~~~~~~~~
+
+[[package-name-variable-relation]]
+Package name, config entry name and makefile variable relationship
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In Buildroot, there are some relation between:
+
+* the _package name_, which is the package directory name (and the
+  name of the +*.mk+ file);
+
+* the config entry name that is declared in the +Config.in+ file;
+
+* the makefile variable prefix.
+
+Thus, it is mandatory to keep consistency between all this stuff,
+matching the following rules:
+
+* the _make_ target name will be the _package name_ itself (e.g.:
+  +foo-bar_boo+);
+
+* the config entry is the upper case _package name_ with `.` and `-`
+  characters substituted with `_`, prefixed with +BR2_PACKAGE_+ (e.g.:
+  +BR2_PACKAGE_FOO_BAR_BOO+);
+
+* the +*.mk+ file variable prefix is the upper case _package name_
+  `.` and `-` characters substituted with `_` (e.g.:
+  +FOO_BAR_BOO_VERSION+).
+
+
+[[github-download-url]]
+How to add package from github
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If the package has no release version, or its version cannot be
+identified using tag, then the sha1 of the particular commit should be
+used to identify the version (the first 7 characters of the sha1 are
+enough):
+
+------------------------
+FOO_VERSION = 1234567
+FOO_SITE = http://github.com/<user>/<package>/tarball/<branch>
+------------------------
+
+If the package version matches a tag, then this tag should be used to
+identify the version:
+
+------------------------
+FOO_VERSION = v1.0
+FOO_SITE = http://github.com/<user>/<package>/tarball/$(FOO_VERSION)
+------------------------

index 8221c85..b909d47 100644
@@ -19,4 +19,6 @@ include::adding-packages-cmake.txt[]
 
 include::adding-packages-gettext.txt[]
 
+include::adding-packages-tips.txt[]
+
 include::adding-packages-conclusion.txt[]

index e3f16c2..b05043a 100644
@@ -22,33 +22,35 @@ system is based on hand-written Makefiles or shell scripts.
 06: LIBFOO_VERSION = 1.0
 07: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
 08: LIBFOO_SITE = http://www.foosoftware.org/download
-09: LIBFOO_INSTALL_STAGING = YES
-10: LIBFOO_DEPENDENCIES = host-libaaa libbbb
-11:
-12: define LIBFOO_BUILD_CMDS
-13: 	$(MAKE) CC="$(TARGET_CC)" LD="$(TARGET_LD)" -C $(@D) all
-14: endef
-15:
-16: define LIBFOO_INSTALL_STAGING_CMDS
-17: 	$(INSTALL) -D -m 0755 $(@D)/libfoo.a $(STAGING_DIR)/usr/lib/libfoo.a
-18: 	$(INSTALL) -D -m 0644 $(@D)/foo.h $(STAGING_DIR)/usr/include/foo.h
-19: 	$(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(STAGING_DIR)/usr/lib
-20: endef
-21:
-22: define LIBFOO_INSTALL_TARGET_CMDS
-23: 	$(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(TARGET_DIR)/usr/lib
-24: 	$(INSTALL) -d -m 0755 $(TARGET_DIR)/etc/foo.d
-25: endef
-26:
-27: define LIBFOO_DEVICES
-28: 	/dev/foo  c  666  0  0  42  0  -  -  -
-29: endef
-30:
-31: define LIBFOO_PERMISSIONS
-32: 	/bin/foo  f  4755  0  0  -  -  -  -  -
-33: endef
-34:
-35: $(eval $(generic-package))
+09: LIBFOO_LICENSE = GPLv3+
+10: LIBFOO_LICENSE_FILES = COPYING
+11: LIBFOO_INSTALL_STAGING = YES
+12: LIBFOO_DEPENDENCIES = host-libaaa libbbb
+13:
+14: define LIBFOO_BUILD_CMDS
+15:	$(MAKE) CC="$(TARGET_CC)" LD="$(TARGET_LD)" -C $(@D) all
+16: endef
+17:
+18: define LIBFOO_INSTALL_STAGING_CMDS
+19:	$(INSTALL) -D -m 0755 $(@D)/libfoo.a $(STAGING_DIR)/usr/lib/libfoo.a
+20:	$(INSTALL) -D -m 0644 $(@D)/foo.h $(STAGING_DIR)/usr/include/foo.h
+21:	$(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(STAGING_DIR)/usr/lib
+22: endef
+23:
+24: define LIBFOO_INSTALL_TARGET_CMDS
+25:	$(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(TARGET_DIR)/usr/lib
+26:	$(INSTALL) -d -m 0755 $(TARGET_DIR)/etc/foo.d
+27: endef
+28:
+29: define LIBFOO_DEVICES
+30:	/dev/foo  c  666  0  0	42  0  -  -  -
+31: endef
+32:
+33: define LIBFOO_PERMISSIONS
+34:	/bin/foo  f  4755  0  0	 -  -  -  -  -
+35: endef
+36:
+37: $(eval $(generic-package))
 --------------------------------
 
 The Makefile begins on line 6 to 8 with metadata information: the

@@ -245,7 +247,7 @@ information is (assuming the package name is +libfoo+) :
 * +LIBFOO_LICENSE+ defines the license (or licenses) under which the package
   is released.
   This name will appear in the manifest file produced by +make legal-info+.
-  If the license is one of those listed in xref:legal-info[],
+  If the license appears in xref:legal-info-list-licenses[the following list],
   use the same string to make the manifest file uniform.
   Otherwise, describe the license in a precise and concise way, avoiding
   ambiguous names such as +BSD+ which actually name a family of licenses.

136 lines not on this page · raw message

index 4032a6b..a1ee68a 100644
@@ -23,6 +23,8 @@ include::going-further.txt[]
 
 include::developer-guide.txt[]
 
+include::legal-notice.txt[]
+
 include::get-involved.txt[]
 
 include::contribute.txt[]

133 lines not on this page · raw message

index a6642b5..6f1e9f3 100644
@@ -4,3 +4,16 @@ Appendix
 ========
 
 include::makedev-syntax.txt[]
+
+[[package-list]]
+Available packages
+------------------
+// docs/manaual/pkg-list.txt is generated using the following command:
+// $ git grep -E '\((autotools|cmake|generic)-package\)' package/ |  \
+//     cut -d':' -f1 | grep '\.mk$' | \
+//     sed -e 's;.*\?/\(.*\?\).mk;* \1;' | \
+//     sort > docs/manual/pkg-list.txt
+
+include::pkg-list.txt[]
+
+include::deprecated-list.txt[]

870 lines not on this page · raw message

new file mode 100644
index 0000000..6dc87a4
@@ -0,0 +1,46 @@
+// -*- mode:doc -*- ;
+
+[[deprecated]]
+Deprecated list
+---------------
+
+The following stuff are marked as _deprecated_ in Buildroot due to
+their status either too old or unmaintained.
+
+// list generated using the followings command:
+// $ git grep -EB4 'depends on BR2_DEPRECATED'
+// and
+// $ git grep -EB4 'depends on BR2_DEPRECATED' | \
+//     grep -Eo '(:|-).*?(config|comment) BR2_.*'
+//
+// Need manual checks and sorting.
+
+* Packages:
+
+** +busybox+ 1.18.x
+** +customize+
+** +lzma+
+** +microperl+
+** +netkitbase+
+** +netkittelnet+
+** +pkg-config+
+** +squashfs3+
+** +ttcp+
+
+* Toolchain:
+
+** +gdb+ 6.8
+** +gdb+ 7.0.1
+** +gdb+ 7.1
+** +kernel headers+ 2.6.37
+** +kernel headers+ 2.6.38
+** +kernel headers+ 2.6.39
+
+* Bootloaders:
+
+** +u-boot+ 2011-06
+** +u-boot+ 2011-09
+
+* Output images:
+
+** squashfs3 image

new file mode 100644
index 0000000..12ce78c
@@ -0,0 +1,38 @@
+// -*- mode:doc; -*-
+
+Beyond Buildroot
+================
+
+Boot the generated images
+-------------------------
+
+NFS boot
+~~~~~~~~
+
+To achieve NFS-boot, enable _tar root filesystem_ in the _Filesystem
+images_ menu.
+
+After complete build, just run the following commands to setup the
+NFS-root directory:
+
+-------------------
+sudo tar -xavf /path/to/output_dir/rootfs.tar -C /path/to/nfs_root_dir
+-------------------
+
+Then, you can execute a NFS-boot from your target.
+
+Chroot
+------
+
+If you want to chroot in a generated image, then there are few thing
+you should be aware of:
+
+* you should setup the new root from the _tar root filesystem_ image;
+
+* either the selected target architecture is compatible with your host
+  machine, or you should use some +qemu-*+ binary and correctly set it
+  within the +binfmt+ properties to be able to run the binaries built
+  for the target on your host machine;
+
+* Buildroot does not currently provide +host-qemu+ and +binfmt+
+  correctly built and set for that kind of use.

index a1ee68a..c34e0ca 100644
@@ -25,6 +25,8 @@ include::developer-guide.txt[]
 
 include::legal-notice.txt[]
 
+include::beyond-buildroot.txt[]
+
 include::get-involved.txt[]
 
 include::contribute.txt[]