| Infrastructure for autotools-based packages |
| ------------------------------------------- |
| |
| [[autotargets-tutorial]] |
| |
| +AUTOTARGETS+ tutorial |
| ~~~~~~~~~~~~~~~~~~~~~~ |
| |
| First, let's see how to write a +.mk+ file for an autotools-based |
| package, with an example : |
| |
| ------------------------ |
| 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)) |
| ------------------------ |
| |
| 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. |
| |
| [[autotargets-reference]] |
| |
| +AUTOTARGETS+ 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. |
| |
| * +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 is 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 be set to |
| +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 +NO+ |
| |
| * +LIBFOO_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 +YES+ |
| |
| * +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+. The default |
| value is correct for most autotools packages, but it is still possible |
| to override it 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 any particular step: |
| |
| * By adding a post-operation hook (after extract, patch, configure, |
| build or install). See the reference documentation of the generic |
| infrastructure for details. |
| |
| * By overriding one of the steps. For example, even if the autotools |
| infrastructure is used, if the package +.mk+ file 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. |
