docs/manual/adding-packages-autotools.txt

   1 // -*- mode:doc; -*-
   2 // vim: set syntax=asciidoc:
   3
   4 === Infrastructure for autotools-based packages
   5
   6 [[autotools-package-tutorial]]
   7
   8 ==== +autotools-package+ tutorial
   9
  10 First, let's see how to write a +.mk+ file for an autotools-based
  11 package, with an example :
  12
  13 ------------------------
  14 01: ################################################################################
  15 02: #
  16 03: # libfoo
  17 04: #
  18 05: ################################################################################
  19 06:
  20 07: LIBFOO_VERSION = 1.0
  21 08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
  22 09: LIBFOO_SITE = http://www.foosoftware.org/download
  23 10: LIBFOO_INSTALL_STAGING = YES
  24 11: LIBFOO_INSTALL_TARGET = NO
  25 12: LIBFOO_CONF_OPTS = --disable-shared
  26 13: LIBFOO_DEPENDENCIES = libglib2 host-pkgconf
  27 14:
  28 15: $(eval $(autotools-package))
  29 ------------------------
  30
  31 On line 7, we declare the version of the package.
  32
  33 On line 8 and 9, we declare the name of the tarball (xz-ed tarball recommended)
  34 and the location of the tarball on the Web. Buildroot will automatically
  35 download the tarball from this location.
  36
  37 On line 10, we tell Buildroot to install the package to the staging
  38 directory. The staging directory, located in +output/staging/+
  39 is the directory where all the packages are installed, including their
  40 development files, etc. By default, packages are not installed to the
  41 staging directory, since usually, only libraries need to be installed in
  42 the staging directory: their development files are needed to compile
  43 other libraries or applications depending on them. Also by default, when
  44 staging installation is enabled, packages are installed in this location
  45 using the +make install+ command.
  46
  47 On line 11, we tell Buildroot to not install the package to the
  48 target directory. This directory contains what will become the root
  49 filesystem running on the target. For purely static libraries, it is
  50 not necessary to install them in the target directory because they will
  51 not be used at runtime. By default, target installation is enabled; setting
  52 this variable to NO is almost never needed. Also by default, packages are
  53 installed in this location using the +make install+ command.
  54
  55 On line 12, we tell Buildroot to pass a custom configure option, that
  56 will be passed to the +./configure+ script before configuring
  57 and building the package.
  58
  59 On line 13, we declare our dependencies, so that they are built
  60 before the build process of our package starts.
  61
  62 Finally, on line line 15, we invoke the +autotools-package+
  63 macro that generates all the Makefile rules that actually allows the
  64 package to be built.
  65
  66 [[autotools-package-reference]]
  67
  68 ==== +autotools-package+ reference
  69
  70 The main macro of the autotools package infrastructure is
  71 +autotools-package+. It is similar to the +generic-package+ macro. The ability to
  72 have target and host packages is also available, with the
  73 +host-autotools-package+ macro.
  74
  75 Just like the generic infrastructure, the autotools infrastructure
  76 works by defining a number of variables before calling the
  77 +autotools-package+ macro.
  78
  79 First, all the package metadata information variables that exist in the
  80 generic infrastructure also exist in the autotools infrastructure:
  81 +LIBFOO_VERSION+, +LIBFOO_SOURCE+,
  82 +LIBFOO_PATCH+, +LIBFOO_SITE+,
  83 +LIBFOO_SUBDIR+, +LIBFOO_DEPENDENCIES+,
  84 +LIBFOO_INSTALL_STAGING+, +LIBFOO_INSTALL_TARGET+.
  85
  86 A few additional variables, specific to the autotools infrastructure,
  87 can also be defined. Many of them are only useful in very specific
  88 cases, typical packages will therefore only use a few of them.
  89
  90 * +LIBFOO_SUBDIR+ may contain the name of a subdirectory
  91   inside the package that contains the configure script. This is useful,
  92   if for example, the main configure script is not at the root of the
  93   tree extracted by the tarball. If +HOST_LIBFOO_SUBDIR+ is
  94   not specified, it defaults to +LIBFOO_SUBDIR+.
  95
  96 * +LIBFOO_CONF_ENV+, to specify additional environment
  97   variables to pass to the configure script. By default, empty.
  98
  99 * +LIBFOO_CONF_OPTS+, to specify additional configure
 100   options to pass to the configure script. By default, empty.
 101
 102 * +LIBFOO_MAKE+, to specify an alternate +make+
 103   command. This is typically useful when parallel make is enabled in
 104   the configuration (using +BR2_JLEVEL+) but that this
 105   feature should be disabled for the given package, for one reason or
 106   another. By default, set to +$(MAKE)+. If parallel building
 107   is not supported by the package, then it should be set to
 108   +LIBFOO_MAKE=$(MAKE1)+.
 109
 110 * +LIBFOO_MAKE_ENV+, to specify additional environment
 111   variables to pass to make in the build step. These are passed before
 112   the +make+ command. By default, empty.
 113
 114 * +LIBFOO_MAKE_OPTS+, to specify additional variables to
 115   pass to make in the build step. These are passed after the
 116   +make+ command. By default, empty.
 117
 118 * +LIBFOO_AUTORECONF+, tells whether the package should
 119   be autoreconfigured or not (i.e. if the configure script and
 120   Makefile.in files should be re-generated by re-running autoconf,
 121   automake, libtool, etc.). Valid values are +YES+ and
 122   +NO+. By default, the value is +NO+
 123
 124 * +LIBFOO_AUTORECONF_ENV+, to specify additional environment
 125   variables to pass to the 'autoreconf' program if
 126   +LIBFOO_AUTORECONF=YES+. These are passed in the environment of
 127   the 'autoreconf' command. By default, empty.
 128
 129 * +LIBFOO_AUTORECONF_OPTS+ to specify additional options
 130   passed to the 'autoreconf' program if
 131   +LIBFOO_AUTORECONF=YES+. By default, empty.
 132
 133 * +LIBFOO_GETTEXTIZE+, tells whether the package should be
 134   gettextized or not (i.e. if the package uses a different gettext
 135   version than Buildroot provides, and it is needed to run
 136   'gettextize'.) Only valid when +LIBFOO_AUTORECONF=YES+. Valid
 137   values are +YES+ and +NO+. The default is +NO+.
 138
 139 * +LIBFOO_GETTEXTIZE_OPTS+, to specify additional options passed to
 140   the 'gettextize' program, if +LIBFOO_GETTEXTIZE=YES+. You may
 141   use that if, for example, the +.po+ files are not located in the
 142   standard place (i.e. in +po/+ at the root of the package.) By
 143   default, '-f'.
 144
 145 * +LIBFOO_LIBTOOL_PATCH+ tells whether the Buildroot
 146   patch to fix libtool cross-compilation issues should be applied or
 147   not. Valid values are +YES+ and +NO+. By
 148   default, the value is +YES+
 149
 150 * +LIBFOO_INSTALL_STAGING_OPTS+ contains the make options
 151   used to install the package to the staging directory. By default, the
 152   value is +DESTDIR=$(STAGING_DIR) install+, which is
 153   correct for most autotools packages. It is still possible to override
 154   it.
 155
 156 * +LIBFOO_INSTALL_TARGET_OPTS+ contains the make options
 157   used to install the package to the target directory. By default, the
 158   value is +DESTDIR=$(TARGET_DIR) install+. The default
 159   value is correct for most autotools packages, but it is still possible
 160   to override it if needed.
 161
 162 With the autotools infrastructure, all the steps required to build
 163 and install the packages are already defined, and they generally work
 164 well for most autotools-based packages. However, when required, it is
 165 still possible to customize what is done in any particular step:
 166
 167 * By adding a post-operation hook (after extract, patch, configure,
 168   build or install). See xref:hooks[] for details.
 169
 170 * By overriding one of the steps. For example, even if the autotools
 171   infrastructure is used, if the package +.mk+ file defines its
 172   own +LIBFOO_CONFIGURE_CMDS+ variable, it will be used
 173   instead of the default autotools one. However, using this method
 174   should be restricted to very specific cases. Do not use it in the
 175   general case.