+// -*- 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 :
[[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
+// -*- 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 :
[[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
+// -*- 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
+// -*- mode:doc; -*-
+
Package directory
------------------
+~~~~~~~~~~~~~~~~~
First of all, create a directory under the +package+ directory for
your software, for example +libfoo+.
+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
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,
+// -*- 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
[[generic-package-tutorial]]
+generic-package+ Tutorial
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------
01: #############################################################
[[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
+// -*- 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
-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
--- /dev/null
+// -*- mode:doc; -*-
+
+Advanced usage
+--------------
+
+include::using-buildroot-toolchain.txt[]
+
+include::external-toolchain.txt[]
+
+include::ccache-support.txt[]
+
+include::download-location.txt[]
+// -*- mode:doc; -*-
+
Appendix
========
+// -*- 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
+// -*- 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
--- /dev/null
+// -*- mode:doc; -*-
+
+Daily use
+---------
+
+include::rebuilding-packages.txt[]
-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
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[].
+// -*- 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
+// -*- mode:doc -*- ;
+
+[[rootfs-custom]]
Customizing the generated target filesystem
--------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are a few ways to customize the resulting target filesystem:
-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.
(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*.
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
-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
+// -*- mode:doc; -*-
+
Customization
-=============
+-------------
include::customize-rootfs.txt[]
--- /dev/null
+// -*- mode:doc; -*-
+
+Developer Guidelines
+====================
+
+include::adding-packages.txt[]
+
+include::board-support.txt[]
+// -*- 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
-Using an external toolchain
-===========================
+// -*- mode:doc -*- ;
+
[[external-toolchain]]
+Using an external toolchain
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
Using an already existing toolchain is useful for different
reasons:
+// -*- 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
--- /dev/null
+Going further in Buildroot's innards
+====================================
+
+include::how-buildroot-works.txt[]
+
+include::advanced.txt[]
+// -*- 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
+// -*- mode:doc -*- ;
+
[[makedev-syntax]]
Makedev syntax documentation
----------------------------
+// -*- mode:doc; -*-
+
The Buildroot user manual
=========================
:toc:
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[]
+// -*- 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
--- /dev/null
+// -*- mode:doc; -*-
+
+Starting up
+===========
+
+include::getting.txt[]
+
+include::using.txt[]
+
+// -*- 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
-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
--- /dev/null
+// -*- 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]
projects / buildroot.git / commitdiff