diff --git a/docs/buildroot.html b/docs/buildroot.html deleted file mode 100644 index d178df1f56..0000000000 --- a/docs/buildroot.html +++ /dev/null @@ -1,1834 +0,0 @@ - - - - - Buildroot - Usage and documentation - - - - - -
-
-

Buildroot

-
- -

Buildroot usage and documentation - by Thomas Petazzoni. Contributions from Karsten Kruse, Ned Ludd, Martin - Herren and others.

- - - -

WARNING: Since the 2011.11 release, this page is on its way to be - deprecated. Information may be incomplete and out-dated.

- -

To get an up-to-date documentation for - Buildroot-2011.11 or a git view, just - run:

-
-  $ make manual
-
-

This requires asciidoc installed on the host system.

- -

For releases since Buildroot-2012.02, - manuals (html, pdf and text) are available in the docs/manual - directory.

- -

About Buildroot

- -

Buildroot is a set of Makefiles and patches that allows you to easily - generate a cross-compilation toolchain, a root filesystem and a Linux - kernel image for your target. Buildroot can be used for one, two or all - of these options, independently.

- -

Buildroot is useful mainly for people working with embedded systems. - Embedded systems often use processors that are not the regular x86 - processors everyone is used to having in his PC. They can be PowerPC - processors, MIPS processors, ARM processors, etc.

- -

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 - GNU Libc, - uClibc or - 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:

- - - -

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.

- -

Obtaining Buildroot

- -

Buildroot releases are made approximately every 3 - months. Direct Git access and daily snapshots are also - available, if you want more bleeding edge.

- -

Releases are available at - http://buildroot.net/downloads/.

- -

The latest snapshot is always available at - http://buildroot.net/downloads/snapshots/buildroot-snapshot.tar.bz2, - and previous snapshots are also available at - http://buildroot.net/downloads/snapshots/.

- -

To download Buildroot using Git, you can simply follow - the rules described on the "Accessing Git" page - (http://buildroot.net/git.html) - of the Buildroot website - (http://buildroot.net). - For the impatient, here's a quick recipe:

- -
- $ git clone git://git.buildroot.net/buildroot
-
- -

Using Buildroot

- -

Buildroot has a nice configuration tool similar to the one you can find - in the Linux kernel - (http://www.kernel.org/) or in Busybox - (http://www.busybox.net/). Note that - you can (and should) build everything as a normal user. There is no need to - be root to configure and use Buildroot. The first step is to run the - configuration assistant:

- -
- $ make menuconfig
-
- -

to run the curses-based configurator, or

- -
- $ make xconfig
-
- -

or

- -
- $ make gconfig
-
- -

to run the Qt or GTK-based configurators.

- -

All of these "make" commands will need to build a configuration - utility, so you may need to install "development" packages for relevant - libraries used by the configuration utilities. On Debian-like systems, - the libncurses5-dev package is required to use the - menuconfig interface, libqt4-dev is required to use - the xconfig interface, and libglib2.0-dev, libgtk2.0-dev - and libglade2-dev are needed to use the gconfig interface.

- -

For each menu entry in the configuration tool, you can find associated - help that describes the purpose of the entry.

- -

Once everything is configured, the configuration tool generates a - .config file that contains the description of your - configuration. It will be used by the Makefiles to do what's needed.

- - -

Let's go:

- -
- $ make
-
- -

You should never use make -jN with - Buildroot: it does not support top-level parallel - make. Instead, use the BR2_JLEVEL option to tell - Buildroot to run each package compilation with make - -jN.

- -

This command will generally perform the following steps:

- - -

Buildroot output is stored in a single directory, output/. - This directory contains several subdirectories:

- - - -

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>
-
- -

Environment variables

- -

Buildroot also honors some environment variables, when they are passed - to make or set in the environment:

- - -

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
-
- -

Customizing the generated target filesystem

- -

There are a few ways to customize the resulting target filesystem:

- - - -

Customizing the Busybox configuration

- -

Busybox is very configurable, - and you may want to customize it. You can follow these simple steps to - do so. This method isn't optimal, but it's simple, and it works:

- -
    -
  1. Do an initial compilation of Buildroot, with busybox, without - trying to customize it.
    2. - -
  2. Invoke make busybox-menuconfig. - The nice configuration tool appears, and you can - customize everything.
    3. - -
  3. Run the compilation of Buildroot again.
    4. -
- -

Otherwise, you can simply change the - package/busybox/busybox-<version>.config file, if you - know 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 environment variables.

- -

Customizing the uClibc configuration

- -

Just like BusyBox, - uClibc offers a lot of - configuration options. They allow you to select various - functionalities depending on your needs and limitations.

- -

The easiest way to modify the configuration of uClibc is to - follow these steps:

- -
    -
  1. Do an initial compilation of Buildroot without trying to - customize uClibc.
    2. - -
  2. Invoke make uclibc-menuconfig. - The nice configuration assistant, similar to - the one used in the Linux kernel or Buildroot, appears. Make - your configuration changes as appropriate.
    3. - -
  3. Copy the $(O)/toolchain/uclibc-VERSION/.config - file to a different place - (like toolchain/uClibc/uClibc-myconfig.config, - or board/mymanufacturer/myboard/uClibc.config) and - adjust the uClibc configuration (configuration - option BR2_UCLIBC_CONFIG) to use this configuration - instead of the default one.
    4. - -
  4. Run the compilation of Buildroot again.
    5. -
- -

Otherwise, you can simply change - toolchain/uClibc/uClibc.config, without running the - configuration assistant.

- -

If you want to use an existing config file for uclibc, then see - section environment variables.

- -

Customizing the Linux kernel configuration

- -

The Linux kernel configuration can be customized just like - BusyBox and - uClibc using make linux-menuconfig - . Make sure you have enabled the kernel build in make - menuconfig first. Once done, run make to (re)build - everything.

- -

If you want to use an existing config file for Linux, then see - section environment variables.

- -

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 everything from scratch.

- -

Removing a package is currently unsupported by Buildroot - without rebuilding from scratch. This is because Buildroot doesn't - keep track of which package installs what files in the - output/staging and output/target - directories. However, implementing clean package removal is on the - TODO-list of Buildroot developers.

- -

The easiest way to rebuild a single package from scratch is to - remove its build directory in output/build. Buildroot - will then re-extract, re-configure, re-compile and re-install this - package from scratch.

- -

However, if you don't want to rebuild the package completely - from scratch, a better understanding of the Buildroot internals is - needed. Internally, to keep track of which steps have been done - and which steps remain to be done, Buildroot maintains stamp - files (empty files that just tell whether this or that action - has been done). The problem is that these stamp files are not - uniformly named and handled by the different packages, so some - understanding of the particular package is needed.

- -

For packages relying on Buildroot packages infrastructures (see - this section for details), the - following stamp files are relevant:

- - - -

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.

- -

How Buildroot works

- -

As mentioned above, Buildroot is basically a set of Makefiles that - download, configure, and compile software with the correct options. It - also includes patches for various software packages — mainly the - ones involved in the cross-compilation tool chain (gcc, - binutils and uClibc).

- -

There is basically one Makefile per software package, and they are - named with the .mk extension. Makefiles are split into - three main sections:

- - - -

Each directory contains at least 2 files:

- - - -

The main Makefile performs the following steps (once the - configuration is done):

- -
    -
  1. Create all the output directories: staging, - target, build, stamps, - etc. in the output directory (output/ by default, - another value can be specified using O=)
    2. - -
  2. Generate all the targets listed in the - BASE_TARGETS variable. When an internal toolchain - is used, this means generating the cross-compilation - toolchain. When an external toolchain is used, this means checking - the features of the external toolchain and importing it into the - Buildroot environment.
    3. - -
  3. Generate all the targets listed in the TARGETS - variable. This variable is filled by all the individual - components' Makefiles. Generating these targets will - trigger the compilation of the userspace packages (libraries, - programs), the kernel, the bootloader and the generation of the - root filesystem images, depending on the configuration.
    4. -
- -

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 work.

- -

To do so, you need to create a normal Buildroot configuration - that builds a basic system for the hardware: toolchain, kernel, - bootloader, filesystem and a simple Busybox-only userspace. No - specific package should be selected: the configuration should be - as minimal as possible, and should only build a working basic - Busybox system for the target platform. You can of course use more - complicated configurations for your internal projects, but the - Buildroot project will only integrate basic board - configurations. This is because package selections are highly - application-specific.

- -

Once you have a known working configuration, run make - savedefconfig. This will generate a - minimal defconfig file at the root of the Buildroot - source tree. Move this file into the configs/ - directory, and rename it MYBOARD_defconfig.

- -

It is recommended to use as much as possible upstream versions - of the Linux kernel and bootloaders, and to use as much as - possible default kernel and bootloader configurations. If they are - incorrect for your platform, we encourage you to send fixes to the - corresponding upstream projects.

- -

However, in the mean time, you may want to store kernel or - bootloader configuration or patches specific to your target - platform. To do so, create a - directory board/MANUFACTURER and a - subdirectory board/MANUFACTURER/BOARDNAME (after - replacing, of course, MANUFACTURER and BOARDNAME with the - appropriate values, in lower case letters). You can then store - your patches and configurations in these directories, and - reference them from the main Buildroot configuration.

- -

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 can - use the toolchain that was generated by Buildroot.

- -

The toolchain generated by Buildroot is located by default in - output/host/. The simplest way to use it is to add - output/host/usr/bin/ to your PATH environment variable and - then to use ARCH-linux-gcc, ARCH-linux-objdump, - ARCH-linux-ld, etc.

- -

It is possible to relocate the toolchain — but - then --sysroot must be passed every time the compiler - is called to tell where the libraries and header files are.

- -

It is also possible to generate the Buildroot toolchain in a - directory other than output/host by using the - Build options -> Host dir option. - This could be useful if the toolchain must be shared with other users.

- -

Using ccache in Buildroot

- -

ccache is a compiler - cache. It stores the object files resulting from each compilation - process, and is able to skip future compilation of the same source - file (with same compiler and same arguments) by using the - pre-existing object files. When doing almost identical builds from - scratch a number of times, it can nicely speed up the build - process.

- -

ccache support is integrated in Buildroot. You - just have to enable Enable compiler cache - in Build options. This will automatically build - ccache and use it for every host and target - compilation.

- -

The cache is located - in $HOME/.buildroot-ccache. It is stored outside of - Buildroot output directory so that it can be shared by separate - Buildroot builds. If you want to get rid of the cache, simply - remove this directory.

- -

You can get statistics on the cache (its size, number of hits, - misses, etc.) by running make ccache-stats.

- -

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 default is the dl directory. It's useful, for - example, if you want to keep a complete version of Buildroot which is - known to be working with the associated tarballs. This will allow you to - regenerate the toolchain and the target filesystem with exactly the same - versions.

- -

If you maintain several Buildroot trees, it might be better to have a - shared download location. This can be accessed by creating a symbolic - link from the dl directory to the shared download location:

- -
- $ ln -s <shared download location> dl
-
- -

Another way of accessing a shared download location is to - create the BUILDROOT_DL_DIR environment variable. - If this is set, then the value of DL_DIR in the project is - overridden. The following line should be added to - "~/.bashrc".

- -
- $ export BUILDROOT_DL_DIR <shared download location>
-
- -

Using an external toolchain

- -

Using an already existing toolchain is useful for different - reasons:

- - - -

Buildroot supports using existing toolchains through a - mechanism called external toolchain. The external toolchain - mechanism is enabled in the Toolchain menu, by - selecting External toolchain in Toolchain - type.

- -

Then, you have three solutions to use an external - toolchain:

- - - -

Our external toolchain support has been tested with toolchains - from CodeSourcery, toolchains generated - by Crosstool-NG, - and toolchains generated by Buildroot itself. In general, all - toolchains that support the sysroot feature should - work. If not, do not hesitate to contact the developers.

- -

We do not support toolchains from - the ELDK of Denx, - for two reasons:

- - - -

We also do not support using the distribution toolchain (i.e - the gcc/binutils/C library installed by your distribution) as the - toolchain to build software for the target. This is because your - distribution toolchain is not a "pure" toolchain (i.e only with - the C/C++ library), so we cannot import it properly into the - Buildroot build environment. So even if you are building a system - for a x86 or x86_64 target, you have to generate a - cross-compilation toolchain with Buildroot or Crosstool-NG.

- -

Adding new packages to Buildroot

- -

This section covers how new packages (userspace libraries or - applications) can be integrated into Buildroot. It also shows how existing - packages are integrated, which is needed for fixing issues or tuning their - configuration.

- - - -

Package directory

- -

First of all, create a directory under the package - directory for your software, for example libfoo.

- -

Some packages have been grouped by topic in a sub-directory: - multimedia, x11r7, and - games. If your package fits in 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 and displayed in the - configuration tool. It should basically contain :

- -
-config BR2_PACKAGE_LIBFOO
-	bool "libfoo"
-	help
-	  This is a comment that explains what libfoo is.
-
-	  http://foosoftware.org/libfoo/
-
- -

Of course, you can add other options to configure particular - things in your software. You can look at examples in other - packages. The syntax of the Config.in file is the same as the one - for the kernel Kconfig file. The documentation for this syntax is - available at - http://lxr.free-electrons.com/source/Documentation/kbuild/kconfig-language.txt -

- -

Finally you have to add your new libfoo/Config.in to - package/Config.in (or in a category subdirectory if - you decided to put your package in one of the existing - categories). The files included there are sorted - alphabetically per category and are NOT supposed to - contain anything but the bare name of the package.

- -
-source "package/libfoo/Config.in"
-
- -

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, installed, etc.

- -

Depending on the package type, the .mk file must be - written in a different way, using different infrastructures:

- - - -

Makefile for generic packages : tutorial

- -
-01: #############################################################
-02: #
-03: # libfoo
-04: #
-05: #############################################################
-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: $(eval $(call GENTARGETS,package,libfoo))
-
- -

The Makefile begins on line 6 to 8 with metadata information: the - version of the package (LIBFOO_VERSION), the name of the - tarball containing the package (LIBFOO_SOURCE) and the - Internet location at which the tarball can be downloaded - (LIBFOO_SITE). All variables must start with the same prefix, - LIBFOO_ in this case. This prefix is always the uppercased - version of the package name (see below to understand where the package - name is defined).

- -

On line 9, we specify that this package wants to install something to - the staging space. This is often needed for libraries, since they must - install header files and other development files in the staging space. - This will ensure that the commands listed in the - LIBFOO_INSTALL_STAGING_CMDS variable will be executed.

- -

On line 10, we specify the list of dependencies this package relies - on. These dependencies are listed in terms of lower-case package names, - which can be packages for the target (without the host- - prefix) or packages for the host (with the host-) prefix). - Buildroot will ensure that all these packages are built and installed - before the current package starts its configuration.

- -

The rest of the Makefile defines what should be done at the different - steps of the package configuration, compilation and installation. - LIBFOO_BUILD_CMDS tells what steps should be performed to - build the package. LIBFOO_INSTALL_STAGING_CMDS tells what - steps should be performed to install the package in the staging space. - LIBFOO_INSTALL_TARGET_CMDS tells what steps should be - performed to install the package in the target space.

- -

All these steps rely on the $(@D) variable, which - contains the directory where the source code of the package has been - extracted.

- -

Finally, on line 27, we call the GENTARGETS which - generates, according to the variables defined previously, all the - Makefile code necessary to make your package working.

- -

Makefile for generic packages : reference

- -

The GENTARGETS macro takes three arguments:

- - - -

For a given package, in a single .mk file, it is - possible to call GENTARGETS twice, once to create the rules to generate - a target package and once to create the rules to generate a host package: -

- -
-$(eval $(call GENTARGETS,package,libfoo))
-$(eval $(call GENTARGETS,package,libfoo,host))
-
- -

This might be useful if the compilation of the target package - requires some tools to be installed on the host. If the package name is - libfoo, then the name of the package for the target is also - libfoo, while the name of the package for the host is - host-libfoo. These names should be used in the DEPENDENCIES - variables of other packages, if they depend on libfoo or - host-libfoo.

- -

The call to the GENTARGETS macro must be at the - end of the .mk file, after all variable definitions.

- -

For the target package, the GENTARGETS uses the - variables defined by the .mk file and prefixed by the uppercased package - name: LIBFOO_*. For the host package, it uses the - HOST_LIBFOO_*. For some variables, if the - HOST_LIBFOO_ prefixed variable doesn't exist, the package - infrastructure uses the corresponding variable prefixed by - LIBFOO_. This is done for variables that are likely to have - the same value for both the target and host packages. See below for - details.

- -

The list of variables that can be set in a .mk file to - give metadata information is (assuming the package name is - libfoo) :

- - - -

The recommended way to define these variables is to use the following - syntax:

- -
-LIBFOO_VERSION = 2.32
-
- -

Now, the variables that define what should be performed at the - different steps of the build process.

- - - -

The preferred way to define these variables is:

- -
-define LIBFOO_CONFIGURE_CMDS
-	action 1
-	action 2
-	action 3
-endef
-
- -

In the action definitions, you can use the following variables:

- - - -

The last feature of the generic infrastructure is the ability to add - hooks. These define further actions to perform after existing steps. - Most hooks aren't really useful for generic packages, since the - .mk file already has full control over the actions - performed in each step of the package construction. The hooks are more - useful for packages using the autotools infrastructure described below. - However, since they are provided by the generic infrastructure, they are - documented here. The exception is LIBFOO_POST_PATCH_HOOKS. - Patching the package is not user definable, so - LIBFOO_POST_PATCH_HOOKS will be userful for generic packages. -

- -

The following hook points are available:

- - - -

These variables are lists of variable names containing actions - to be performed at this hook point. This allows several hooks to be - registered at a given hook point. Here is an example:

- -
-define LIBFOO_POST_PATCH_FIXUP
-	action1
-	action2
-endef
-
-LIBFOO_POST_PATCH_HOOKS += LIBFOO_POST_PATCH_FIXUP
-
- -

Makefile for autotools-based packages : tutorial

- -

First, let's see how to write a .mk file for an - autotools-based package, with an example :

- -
-01: #############################################################
-02: #
-03: # libfoo
-04: #
-05: #############################################################
-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_INSTALL_TARGET = YES
-11: LIBFOO_CONF_OPT = --enable-shared
-12: LIBFOO_DEPENDENCIES = libglib2 host-pkg-config
-13:
-14: $(eval $(call AUTOTARGETS,package,libfoo))
-
- -

On line 6, we declare the version of the package.

- -

On line 7 and 8, we declare the name of the tarball and the location - of the tarball on the Web. Buildroot will automatically download the - tarball from this location.

- -

On line 9, we tell Buildroot to install the package to the staging - directory. The staging directory, located in output/staging/ - is the directory where all the packages are installed, including their - development files, etc. By default, packages are not installed to the - staging directory, since usually, only libraries need to be installed in - the staging directory: their development files are needed to compile - other libraries or applications depending on them. Also by default, when - staging installation is enabled, packages are installed in this location - using the make install command.

- -

On line 10, we tell Buildroot to also install the package to the - target directory. This directory contains what will become the root - filesystem running on the target. Usually, we try not to install header - files and to install stripped versions of the binary. By default, target - installation is enabled, so in fact, this line is not strictly - necessary. Also by default, packages are installed in this location - using the make install command.

- -

On line 11, we tell Buildroot to pass a custom configure option, that - will be passed to the ./configure script before configuring - and building the package.

- -

On line 12, we declare our dependencies, so that they are built - before the build process of our package starts.

- -

Finally, on line line 14, we invoke the AUTOTARGETS - macro that generates all the Makefile rules that actually allows the - package to be built.

- -

Makefile for autotools packages : reference

- -

The main macro of the autotools package infrastructure is - AUTOTARGETS. It has the same number of arguments and the - same semantic as the GENTARGETS macro, which is the main - macro of the generic package infrastructure. For autotools packages, the - ability to have target and host packages is also available (and is - actually widely used).

- -

Just like the generic infrastructure, the autotools infrastructure - works by defining a number of variables before calling the - AUTOTARGETS macro.

- -

First, all the package metadata information variables that exist in the - generic infrastructure also exist in the autotools infrastructure: - LIBFOO_VERSION, LIBFOO_SOURCE, - LIBFOO_PATCH, LIBFOO_SITE, - LIBFOO_SUBDIR, LIBFOO_DEPENDENCIES, - LIBFOO_INSTALL_STAGING, LIBFOO_INSTALL_TARGET.

- -

A few additional variables, specific to the autotools infrastructure, - can also be defined. Many of them are only useful in very specific - cases, typical packages will therefore only use a few of them.

- - - -

With the autotools infrastructure, all the steps required to build - and install the packages are already defined, and they generally work - well for most autotools-based packages. However, when required, it is - still possible to customize what is done in any particular step:

- - - -

Makefile for CMake-based packages : tutorial

- -

First, let's see how to write a .mk file for a CMake-based - package, with an example :

- -
-01: #############################################################
-02: #
-03: # libfoo
-04: #
-05: #############################################################
-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_INSTALL_TARGET = YES
-11: LIBFOO_CONF_OPT = -DBUILD_DEMOS=ON
-12: LIBFOO_DEPENDENCIES = libglib2 host-pkg-config
-13:
-14: $(eval $(call CMAKETARGETS,package,libfoo))
-
- -

On line 6, we declare the version of the package.

- -

On line 7 and 8, we declare the name of the tarball and the location - of the tarball on the Web. Buildroot will automatically download the - tarball from this location.

- -

On line 9, we tell Buildroot to install the package to the staging - directory. The staging directory, located in output/staging/ - is the directory where all the packages are installed, including their - development files, etc. By default, packages are not installed to the - staging directory, since usually, only libraries need to be installed in - the staging directory: their development files are needed to compile - other libraries or applications depending on them. Also by default, when - staging installation is enabled, packages are installed in this location - using the make install command.

- -

On line 10, we tell Buildroot to also install the package to the - target directory. This directory contains what will become the root - filesystem running on the target. Usually, we try not to install header - files and to install stripped versions of the binary. By default, target - installation is enabled, so in fact, this line is not strictly - necessary. Also by default, packages are installed in this location - using the make install command.

- -

On line 11, we tell Buildroot to pass custom options to CMake when it is - configuring the package.

- -

On line 12, we declare our dependencies, so that they are built - before the build process of our package starts.

- -

Finally, on line line 14, we invoke the CMAKETARGETS - macro that generates all the Makefile rules that actually allows the - package to be built.

- -

Makefile for CMake packages : reference

- -

The main macro of the CMake package infrastructure is - CMAKETARGETS. It has the same number of arguments and the - same semantic as the GENTARGETS macro, which is the main - macro of the generic package infrastructure. For CMake packages, the - ability to have target and host packages is also available.

- -

Just like the generic infrastructure, the CMake infrastructure - works by defining a number of variables before calling the - CMAKETARGETS macro.

- -

First, all the package metadata information variables that exist in the - generic infrastructure also exist in the CMake infrastructure: - LIBFOO_VERSION, LIBFOO_SOURCE, - LIBFOO_PATCH, LIBFOO_SITE, - LIBFOO_SUBDIR, LIBFOO_DEPENDENCIES, - LIBFOO_INSTALL_STAGING, LIBFOO_INSTALL_TARGET.

- -

A few additional variables, specific to the CMake infrastructure, - can also be defined. Many of them are only useful in very specific - cases, typical packages will therefore only use a few of them.

- - - -

With the CMake infrastructure, all the steps required to build - and install the packages are already defined, and they generally work - well for most CMake-based packages. However, when required, it is - still possible to customize what is done in any particular step:

- - - -

Manual Makefile : tutorial

- -

NOTE: new manual makefiles should not be created, and existing - manual makefiles should be converted either to the generic, autotools - or cmake infrastructure. This section is only kept to document the existing - manual makefiles and to help understand how they work.

- -
-01: #############################################################
-02: #
-03: # libfoo
-04: #
-05: #############################################################
-06: LIBFOO_VERSION:=1.0
-07: LIBFOO_SOURCE:=libfoo-$(LIBFOO_VERSION).tar.gz
-08: LIBFOO_SITE:=http://www.foosoftware.org/downloads
-09: LIBFOO_DIR:=$(BUILD_DIR)/foo-$(FOO_VERSION)
-10: LIBFOO_BINARY:=foo
-11: LIBFOO_TARGET_BINARY:=usr/bin/foo
-12:
-13: $(DL_DIR)/$(LIBFOO_SOURCE):
-14: 	$(call DOWNLOAD,$(LIBFOO_SITE),$(LIBFOO_SOURCE))
-15:
-16: $(LIBFOO_DIR)/.source: $(DL_DIR)/$(LIBFOO_SOURCE)
-17: 	$(ZCAT) $(DL_DIR)/$(LIBFOO_SOURCE) | tar -C $(BUILD_DIR) $(TAR_OPTIONS) -
-18: 	touch $@
-19:
-20: $(LIBFOO_DIR)/.configured: $(LIBFOO_DIR)/.source
-21: 	(cd $(LIBFOO_DIR); rm -rf config.cache; \
-22: 		$(TARGET_CONFIGURE_OPTS) \
-23: 		$(TARGET_CONFIGURE_ARGS) \
-24: 		./configure \
-25: 		--target=$(GNU_TARGET_NAME) \
-26: 		--host=$(GNU_TARGET_NAME) \
-27: 		--build=$(GNU_HOST_NAME) \
-28: 		--prefix=/usr \
-29: 		--sysconfdir=/etc \
-30: 	)
-31: 	touch $@
-32:
-33: $(LIBFOO_DIR)/$(LIBFOO_BINARY): $(LIBFOO_DIR)/.configured
-34: 	$(MAKE) CC=$(TARGET_CC) -C $(LIBFOO_DIR)
-35:
-36: $(TARGET_DIR)/$(LIBFOO_TARGET_BINARY): $(LIBFOO_DIR)/$(LIBFOO_BINARY)
-37: 	$(MAKE) DESTDIR=$(TARGET_DIR) -C $(LIBFOO_DIR) install-strip
-38: 	rm -Rf $(TARGET_DIR)/usr/man
-39:
-40: libfoo: uclibc ncurses $(TARGET_DIR)/$(LIBFOO_TARGET_BINARY)
-41:
-42: libfoo-source: $(DL_DIR)/$(LIBFOO_SOURCE)
-43:
-44: libfoo-clean:
-45: 	$(MAKE) prefix=$(TARGET_DIR)/usr -C $(LIBFOO_DIR) uninstall
-46: 	-$(MAKE) -C $(LIBFOO_DIR) clean
-47:
-48: libfoo-dirclean:
-49: 	rm -rf $(LIBFOO_DIR)
-50:
-51: #############################################################
-52: #
-53: # Toplevel Makefile options
-54: #
-55: #############################################################
-56: ifeq ($(BR2_PACKAGE_LIBFOO),y)
-57: TARGETS+=libfoo
-58: endif
-
- -

First of all, this Makefile example works for a package which - comprises a single binary executable. For other software, such as - libraries or more complex stuff with multiple binaries, it must be - adapted. For examples look at the other *.mk files in the - package directory.

- -

At lines 6-11, a couple of useful variables are - defined:

- - - -

Lines 13-14 define a target that downloads - the tarball from the remote site to the download directory - (DL_DIR).

- -

Lines 16-18 define a target and associated - rules that uncompress the downloaded tarball. As you can see, this - target depends on the tarball file so that the previous target (lines - 13-14) is called before executing the rules of - the current target. Uncompressing is followed by touching a - hidden file to mark the software as having been uncompressed. This trick - is used everywhere in a Buildroot Makefile to split steps (download, - uncompress, configure, compile, install) while still having correct - dependencies.

- -

Lines 20-31 define a target and associated - rules that configure the software. It depends on the previous target - (the hidden .source file) so that we are sure the software - has been uncompressed. In order to configure the package, it basically - runs the well-known ./configure script. As we may be doing - cross-compilation, target, host and - build arguments are given. The prefix is also set to - /usr, not because the software will be installed in - /usr on your host system, but because the software will be - installed in /usr on the target filesystem. Finally it - creates a .configured file to mark the software as - configured.

- -

Lines 33-34 define a target and a rule that - compile the software. This target will create the binary file in the - compilation directory and depends on the software being already - configured (hence the reference to the .configured file). - It basically runs make inside the source directory.

- -

Lines 36-38 define a target and associated - rules that install the software inside the target filesystem. They - depend on the binary file in the source directory to make sure the - software has been compiled. They use the install-strip - target of the software Makefile by passing a - DESTDIR argument so that the Makefile doesn't - try to install the software in the host /usr but rather in - the target /usr. After the installation, the - /usr/man directory inside the target filesystem is removed - to save space.

- -

Line 40 defines the main target of the - software — the one that will eventually be used by the top level - Makefile to download, compile, and then install this - package. This target should first of all depend on all needed - dependencies of the software (in our example, uclibc and - ncurses) and also depend on the final binary. This last dependency - will call all previous dependencies in the correct order.

- -

Line 42 defines a simple target that only - downloads the code source. This is not used during normal operation of - Buildroot, but is needed if you intend to download all required sources - at once for later offline build. Note that if you add a new package, - providing a libfoo-source target is mandatory to - support users that wish to do offline-builds. Furthermore, it eases - checking if all package-sources are downloadable.

- -

Lines 44-46 define a simple target to clean - the software build by calling the Makefile with the appropriate options. - The -clean target should run make clean on - $(BUILD_DIR)/package-version and MUST uninstall all files of the package - from $(STAGING_DIR) and from $(TARGET_DIR).

- -

Lines 48-49 define a simple target to - completely remove the directory in which the software was uncompressed, - configured and compiled. The -dirclean target MUST - completely rm $(BUILD_DIR)/ package-version.

- -

Lines 51-58 add the target libfoo - to the list of targets to be compiled by Buildroot, by first checking if - the configuration option for this package has been enabled using the - configuration tool. If so, it then "subscribes" this package - to be compiled by adding the package to the TARGETS global variable. - The name added to the TARGETS global variable is the name of this - package's target, as defined on line 40, which - is used by Buildroot to download, compile, and then install this package. -

- -

Gettext integration and interaction with packages

- -

Many packages that support internationalization use the gettext - library. Dependencies for this library are fairly complicated and therefore, - deserves some explanation.

- -

The uClibc C library doesn't implement gettext functionality, - therefore with this C library, a separate gettext must be compiled. On - the other hand, the glibc C library does integrate its own - gettext, and in this case, the separate gettext library should not be - compiled, because it creates various kinds of build failures.

- -

Additionally, some packages (such as libglib2) do require gettext - unconditionally, while other packages (those who support - --disable-nls in general) only require gettext when locale - support is enabled.

- -

Therefore, Buildroot defines two configuration options:

- - - -

Therefore, packages that unconditionally need gettext should:

- -
    -
  1. Use select BR2_PACKAGE_GETTEXT if BR2_NEEDS_GETTEXT - and possibly select BR2_PACKAGE_LIBINTL if BR2_NEEDS_GETTEXT, - if libintl is also needed
    2. - -
  2. Use $(if $(BR2_NEEDS_GETTEXT),gettext) in the package - DEPENDENCIES variable
    3. -
- -

Packages that need gettext only when locale support is enabled should: -

- -
    -
  1. Use - select BR2_PACKAGE_GETTEXT if BR2_NEEDS_GETTEXT_IF_LOCALE - and possibly - select BR2_PACKAGE_LIBINTL if BR2_NEEDS_GETTEXT_IF_LOCALE, - if libintl is also needed
    2. - -
  2. Use $(if $(BR2_NEEDS_GETTEXT_IF_LOCALE),gettext) in - the package DEPENDENCIES variable
    3. -
- -

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 - according to the compilation process required by the package.

- -

If you package software that might be useful for other people, don't - forget to send a patch to Buildroot developers!

- -

Frequently asked questions

- - - -

The boot hangs after Starting - network...

- -

If the boot process seems to hang after the following messages - (messages not necessarly 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.

- -

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.

- - - -

To learn more about Buildroot you can visit these websites:

- - -
- -