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 10First, let's see how to write a +.mk+ file for an autotools-based 11package, with an example : 12 13------------------------ 1401: ################################################################################ 1502: # 1603: # libfoo 1704: # 1805: ################################################################################ 1906: 2007: LIBFOO_VERSION = 1.0 2108: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz 2209: LIBFOO_SITE = http://www.foosoftware.org/download 2310: LIBFOO_INSTALL_STAGING = YES 2411: LIBFOO_INSTALL_TARGET = NO 2512: LIBFOO_CONF_OPTS = --disable-shared 2613: LIBFOO_DEPENDENCIES = libglib2 host-pkgconf 2714: 2815: $(eval $(autotools-package)) 29------------------------ 30 31On line 7, we declare the version of the package. 32 33On line 8 and 9, we declare the name of the tarball (xz-ed tarball recommended) 34and the location of the tarball on the Web. Buildroot will automatically 35download the tarball from this location. 36 37On line 10, we tell Buildroot to install the package to the staging 38directory. The staging directory, located in +output/staging/+ 39is the directory where all the packages are installed, including their 40development files, etc. By default, packages are not installed to the 41staging directory, since usually, only libraries need to be installed in 42the staging directory: their development files are needed to compile 43other libraries or applications depending on them. Also by default, when 44staging installation is enabled, packages are installed in this location 45using the +make install+ command. 46 47On line 11, we tell Buildroot to not install the package to the 48target directory. This directory contains what will become the root 49filesystem running on the target. For purely static libraries, it is 50not necessary to install them in the target directory because they will 51not be used at runtime. By default, target installation is enabled; setting 52this variable to NO is almost never needed. Also by default, packages are 53installed in this location using the +make install+ command. 54 55On line 12, we tell Buildroot to pass a custom configure option, that 56will be passed to the +./configure+ script before configuring 57and building the package. 58 59On line 13, we declare our dependencies, so that they are built 60before the build process of our package starts. 61 62Finally, on line line 15, we invoke the +autotools-package+ 63macro that generates all the Makefile rules that actually allows the 64package to be built. 65 66[[autotools-package-reference]] 67 68==== +autotools-package+ reference 69 70The main macro of the autotools package infrastructure is 71+autotools-package+. It is similar to the +generic-package+ macro. The ability to 72have target and host packages is also available, with the 73+host-autotools-package+ macro. 74 75Just like the generic infrastructure, the autotools infrastructure 76works by defining a number of variables before calling the 77+autotools-package+ macro. 78 79First, all the package metadata information variables that exist in the 80generic 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 86A few additional variables, specific to the autotools infrastructure, 87can also be defined. Many of them are only useful in very specific 88cases, 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 162With the autotools infrastructure, all the steps required to build 163and install the packages are already defined, and they generally work 164well for most autotools-based packages. However, when required, it is 165still 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. 176