target/ which contains almost the root
filesystem for the target: everything needed is present except
@@ -474,9 +474,9 @@ $ export BUILDROOT_COPYTO=/tftpboot
uniformely named and handled by the different packages, so some
understanding of the particular package is needed.
- For packages relying on the autotools Buildroot - infrastructure (see this section for - details), the following stamp files are relevent:
+For packages relying on Buildroot packages infrastructures (see + this section for details), the + following stamp files are relevent:
For other packages, an analysis of the specific package.mk file is needed. For example, the zlib Makefile - looks like:
+ used to look like this (before it was converted to the generic + package infrastructure):
$(ZLIB_DIR)/.configured: $(ZLIB_DIR)/.patched
@@ -512,6 +513,10 @@ $(ZLIB_DIR)/libz.a: $(ZLIB_DIR)/.configured
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 the generic or the autotools infrastructure, making it
+ much easier to rebuild individual packages.
+
How Buildroot
works
@@ -522,7 +527,7 @@ $(ZLIB_DIR)/libz.a: $(ZLIB_DIR)/.configured
uClibc).
There is basically one Makefile per software package, and they are named with
- the .mk extension. Makefiles are split into four
+ the .mk extension. Makefiles are split into three main
sections:
This section will only consider the case in which you want to - add user-space software.
+This section covers how new packages (userspace libraries or + applications) can be integrated into Buildroot. It also allows to + understand how existing packages are integrated, which is needed + to fix issues or tune their configuration.
-Config.in file.mk file
+
+ First of all, create a directory under the package
directory for your software, for example foo.
Config.in fileSome packages have been grouped by topic in a sub-directory:
+ multimedia, java,
+ databases, editors, x11r7,
+ games. If your package fits in one of these
+ categories, then create your package directory in these.
Config.in fileThen, create a file named Config.in. This file
will contain the option descriptions related to our
- foo software that will be used and displayed in the
- configuration tool. It should basically contain:
libfoo software that will be used and displayed in the
+ configuration tool. It should basically contain :
-config BR2_PACKAGE_FOO
- bool "foo"
+config BR2_PACKAGE_LIBFOO
+ bool "libfoo"
help
- This is a comment that explains what foo is.
+ This is a comment that explains what libfoo is.
- http://foosoftware.org/foo/
+ http://foosoftware.org/libfoo/
Of course, you can add other options to configure particular - things in your software.
-Finally you have to add your new foo/Config.in to
- package/Config.in. The files included there are
- sorted alphabetically per category and are NOT
- supposed to contain anything but the bare name of the package.
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/procps/Config.in" +source "package/libfoo/Config.in"-
Note:
- Generally all packages should live directly in the
- package directory to make it easier to find them.
-
.mk fileFinally, here's the hardest part. Create a file named
- foo.mk. It will contain the Makefile rules that
- are in charge of downloading, configuring, compiling and installing
- the software.
foo.mk. It describes how the package should be
+ downloaded, configured, built, installed, etc.
- Two types of Makefiles can be written :
+Depending on the package type, the .mk file must be
+ written in a different way, using different infrastructures:
package/Makefile.autotools.in.First, let's see how to write a Makefile 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_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 $(@D)/libfoo.a $(STAGING_DIR)/usr/lib/libfoo.a +18: $(INSTALL) -D $(@D)/foo.h $(STAGING_DIR)/usr/include/foo.h +19: cp -dpf $(@D)/libfoo.so* $(STAGING_DIR)/usr/lib +20: endef +21: +22: define LIBFOO_INSTALL_TARGET_CMDS +23: cp -dpf $(@D)/libfoo.so* $(TARGET_DIR)/usr/lib +24: -$(STRIPCMP) $(STRIP_STRIP_UNNEEDED) $(TARGET_DIR)/isr/lib/libfoo.so* +25: endef +26: +27: $(eval $(call GENTARGETS,package,libfoo))+ +
The Makefile begins on line 6 to 8 by metadata informations: 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.
The GENTARGETS macro takes three arguments:
package/libfoo, then the directory
+ prefix is package. If your package is in
+ package/editors/foo, then the directory prefix must
+ be package/editors..mk file
+ and must match the configuration option name in the
+ Config.in file. For example, if the package name is
+ libfoo, so the variables in the .mk
+ must start with LIBFOO_ and the configuration option
+ in the Config.in file must be
+ BR2_PACKAGE_LIBFOO.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:
- 1 ############################################################# - 2 # - 3 # foo - 4 # - 5 ############################################################# - 6 FOO_VERSION:=1.0 - 7 FOO_SOURCE:=foo-$(FOO_VERSION).tar.gz - 8 FOO_SITE:=http://www.foosoftware.org/downloads - 9 FOO_INSTALL_STAGING = YES - 10 FOO_INSTALL_TARGET = YES - 11 FOO_CONF_OPT = --enable-shared - 12 FOO_DEPENDENCIES = libglib2 host-pkgconfig - 13 $(eval $(call AUTOTARGETS,package,foo)) +$(eval $(call GENTARGETS,package,libfoo)) +$(eval $(call GENTARGETS,package,libfoo,host))-
On line 6, we declare the version of - the package. On lines 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.
+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.
On line 9, we tell Buildroot to install
- the application to the staging directory. The staging directory,
- located in output/staging/ is the directory
- where all the packages are installed, including their
- documentation, etc. By default, packages are installed in this
+
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 target 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 informations is (assuming the package name is
+ libfoo) :
LIBFOO_VERSION, mandatory, must contain the
+ version of the package. Note that if
+ HOST_LIBFOO_VERSION doesn't exist, it is assumed to
+ be the same as LIBFOO_VERSION.LIBFOO_VERSION=0.1.2LIBFOO_SOURCE may contain the name of the
+ tarball of the package. If HOST_LIBFOO_SOURCE is not
+ specified, it defaults to LIBFOO_VERSION. If none
+ are specified, then the value is assumed to be
+ packagename-$(LIBFOO_VERSION).tar.gz.LIBFOO_SOURCE =
+ foobar-$(LIBFOO_VERSION).tar.bz2LIBFOO_PATCH may contain the name of a patch,
+ that will be downloaded from the same location as the tarball
+ indicated in LIBFOO_SOURCE. If
+ HOST_LIBFOO_PATCH is not specified, it defaults to
+ LIBFOO_PATCH. Also note that another mechanism is
+ available to patch a package: all files of the form
+ packagename-packageversion-description.patch present
+ in the package directory inside Buildroot will be applied to the
+ package after extraction.LIBFOO_SITE may contain the Internet location of
+ the tarball of the package. If HOST_LIBFOO_SITE is
+ not specified, it defaults to LIBFOO_SITE. If none
+ are specified, then the location is assumed to be
+ http://$$(BR2_SOURCEFORGE_MIRROR).dl.sourceforge.net/sourceforge/packagename.LIBFOO_SITE=http://www.foosoftware.org/libfoo.LIBFOO_DEPENDENCIES lists the dependencies (in
+ terms of package name) that are required for the current target
+ package to compile. These dependencies are guaranteed to be
+ compiled and installed before the configuration of the current
+ package starts. In a similar way,
+ HOST_LIBFOO_DEPENDENCIES lists the dependency for
+ the current host package.LIBFOO_INSTALL_STAGING can be set to
+ YES or NO (default). If set to
+ YES, then the commands in the
+ LIBFOO_INSTALL_STAGING_CMDS variables are executed
+ to install the package into the staging directory.
+
+ LIBFOO_INSTALL_TARGET can be set to
+ YES (default) or NO. If set to
+ YES, then the commands in the
+ LIBFOO_INSTALL_TARGET_CMDS variables are executed
+ to install the package into the target directory.
+
+ 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.
+ +LIBFOO_CONFIGURE_CMDS, used to list the
+ actions to be performed to configure the package before its
+ compilationLIBFOO_BUILD_CMDS, used to list the actions to
+ be performed to compile the packageHOST_LIBFOO_INSTALL_CMDS, used to list the
+ actions to be performed to install the package, when the
+ package is a host package. The package must install its files
+ to the directory given by $(HOST_DIR). All files,
+ including development files such as headers should be
+ installed, since other packages might be compiled on top of
+ this package.LIBFOO_INSTALL_TARGET_CMDS, used to list the
+ actions to be performed to install the package to the target
+ directory, when the package is a target package. The package
+ must install its files to the directory given by
+ $(TARGET_DIR). Only the files required for
+ execution of the package should be installed. Header
+ files and documentation should not be installed.LIBFOO_INSTALL_STAGING_CMDS, used to list the
+ actions to be performed to install the package to the staging
+ directory, when the package is a target package. The package
+ must install its files to the directory given by
+ $(STAGING_DIR). All development files should be
+ installed, since they might be needed to compile other
+ packages.LIBFOO_CLEAN_CMDS, used to list the actions to
+ perform to clean up the build directory of the package.LIBFOO_UNINSTALL_TARGET_CMDS, used to list the
+ actions to uninstall the package from the target directory
+ $(TARGET_DIR)LIBFOO_UNINSTALL_STAGING_CMDS$(STAGING_DIR).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:
+ +$(@D), which contains the directory in which
+ the package source code has been uncompressed.$(TARGET_CC), $(TARGET_LD),
+ etc. to get the target cross-compilation utilities$(TARGET_CROSS) to get the cross-compilation
+ toolchain prefix$(HOST_DIR),
+ $(STAGING_DIR) and $(TARGET_DIR)
+ variables to install the packages properly.The last feature of the generic infrastructure is the ability
+ to add hook more actions after existing steps. These 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. But
+ since they are provided by the generic infrastructure, they are
+ documented here.
The following hook points are available:
+ +LIBFOO_POST_PATCH_HOOKSLIBFOO_POST_CONFIGURE_HOOKSLIBFOO_POST_BUILD_HOOKSLIBFOO_POST_INSTALL_HOOKS (for host packages only)LIBFOO_POST_INSTALL_STAGING_HOOKS (for target packages only)LIBFOO_POST_INSTALL_TARGET_HOOKS (for target packages only)This 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 ++ +
First, let's see how to write a .mk file for an
+ autotools-based package, with an example :
01: ############################################################# +02: # +03: # foo +04: # +05: ############################################################# +06: +07: FOO_VERSION:=1.0 +08: FOO_SOURCE:=foo-$(FOO_VERSION).tar.gz +09: FOO_SITE:=http://www.foosoftware.org/downloads +10: FOO_INSTALL_STAGING = YES +11: FOO_INSTALL_TARGET = YES +12: FOO_CONF_OPT = --enable-shared +13: FOO_DEPENDENCIES = libglib2 host-pkg-config +14: +15: $(eval $(call AUTOTARGETS,package,foo))+ +
On line 7, we declare the version of the package. On line 8 and + 9, 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 10, 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 application to the target directory. This directory - contains what will become the root filesystem running on the - target. Usually, we try to install stripped binaries and - to not install the documentation. By default, packages are +
On line 11, 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 the documentation 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-strip command.
On line 11, we tell Buildroot to pass
- a custom configure option to the
- ./configure script when configuring the
- the package.
On line 12, 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.
+On line 13, we declare our dependencies, so that they are built + before the build process of our package starts.
-Finally, on line line 13, we invoke
- the package/Makefile.autotools.in magic to get things
- working.
Finally, on line line 14, we invoke the
+ AUTOTARGETS macro that generates all the Makefile
+ rules that actually allows the package to be built.
For more details about the available variables and options, see
- the comment at the top of
- package/Makefile.autotools.in and the examples in all
- the available packages.
The second solution, suitable for every type of package, looks - like this :
+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 meta-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.
+ +LIBFOO_SUBDIR may contain the name of a
+ subdirectory inside the package that contains the configure
+ script. This is useful, if for example, the main configure
+ script is not at the root of the tree extracted by the
+ tarball. If HOST_LIBFOO_SUBDIR is not specified, it
+ defaults to LIBFOO_SUBDIR.LIBFOO_CONF_ENV, to specify additional
+ environment variables to pass to the configure script. By
+ default, empty.LIBFOO_CONF_OPT, to specify additional
+ configure options to pass to the configure script. By default,
+ empty.LIBFOO_MAKE, to specify an
+ alternate make command. This is typically useful
+ when parallel make it enabled in the configuration
+ (using BR2_JLEVEL) but that this feature should be
+ disabled for the given package, for one reason or another. By
+ default, set to $(MAKE). If parallel building is
+ not supported by the package, then it should
+ do LIBFOO_MAKE=$(MAKE1).LIBFOO_MAKE_ENV, to specify additional
+ environment variables to pass to make in the build step. These
+ are passed before the make command. By default,
+ empty.LIBFOO_MAKE_OPT, to specify additional
+ variables to pass to make in the build step. These are passed
+ after the make command. By default, empty.LIBFOO_AUTORECONF, tells whether the package
+ should be autoreconfigured or not (i.e, if the configure script
+ and Makefile.in files should be re-generated by re-running
+ autoconf, automake, libtool, etc.). Valid values
+ are YES and NO. By default, the value
+ is NOLIBFOO_AUTORECONF_OPT to specify additional
+ options passed to the autoreconf program
+ if LIBFOO_AUTORECONF=YES. By default, empty.LIBFOO_LIBTOOL_PATCH tells whether the
+ Buildroot patch to fix libtool cross-compilation issues should
+ be applied or not. Valid values are YES
+ and NO. By default, the value
+ is YESLIBFOO_USE_CONFIG_CACHE tells whether the
+ configure script should really on a cache file that caches test
+ results from previous configure script. Usually, this variable
+ should be left to its default value. Only for specific packages
+ having issues with the configure cache can set this variable to
+ the NO value (but this is more a work-around than a
+ really fix)LIBFOO_INSTALL_STAGING_OPT contains the make
+ options used to install the package to the staging directory. By
+ default, the value is DESTDIR=$$(STAGING_DIR)
+ install, which is correct for most autotools packages. It
+ is still possible to override it.LIBFOO_INSTALL_TARGET_OPT contains the make
+ options used to install the package to the target directory. By
+ default, the value is DESTDIR=$$(TARGET_DIR)
+ install-strip if BR2_ENABLE_DEBUG is not
+ set, and DESTDIR=$$(TARGET_DIR) install-exec
+ if BR2_ENABLE_DEBUG is set. These default values
+ are correct for most autotools packages, but it is still
+ possible to override them if needed.LIBFOO_CLEAN_OPT contains the make options used
+ to clean the package. By default, the value
+ is clean.LIBFOO_UNINSTALL_STAGING_OPT, contains the make
+ options used to uninstall the package from the staging
+ directory. By default, the value is
+ DESTDIR=$$(STAGING_DIR) uninstall.LIBFOO_UNINSTALL_TARGET_OPT, contains the make
+ options used to uninstall the package from the target
+ directory. By default, the value is
+ DESTDIR=$$(TARGET_DIR) uninstall.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 + particular step:
+ +.mk defines its own
+ LIBFOO_CONFIGURE_CMDS variable, it will be used
+ instead of the default autotools one. However, using this method
+ should be restricted to very specific cases. Do not use it in
+ the general case.NOTE: new manual makefiles should not be created, and + existing manual makefiles should be converted either to the + generic infrastructure or the autotools infrastructure. This + section is only kept to document the existing manual makefiles and + help understanding how they work.
1 #############################################################