Simple Autotools Patching Example

Conditional source files based upon USE flags are allowed using the usual flag? ( ) syntax. This is often useful for arch-specific code or for binary -packages -- downloading sparc binaries on ppc would be a waste of bandwidth. +packages downloading sparc binaries on ppc would be a waste of bandwidth.

diff --git a/general-concepts/autotools/text.xml b/general-concepts/autotools/text.xml index 3541d70..6224ebd 100644 --- a/general-concepts/autotools/text.xml +++ b/general-concepts/autotools/text.xml @@ -16,17 +16,17 @@ when working with ebuilds:

- Finding and correcting build issues is often easier if the build system is - not seen simply as a scary black box. + Finding and correcting build issues is often easier if the build system is + not seen simply as a scary black box.
- The autotools input files can help when determining a package's build-time - dependencies. + The autotools input files can help when determining a package's build-time + dependencies.
- The risk of accidentally breaking something by patching the wrong file at the - wrong time is greatly reduced if the relationship between the build system - files is understood. + The risk of accidentally breaking something by patching the wrong file at the + wrong time is greatly reduced if the relationship between the build system + files is understood.

@@ -46,6 +46,626 @@ create the build system for a package. A basic overview of how the main autotools components fit together. +

+In a simple setup: +

+ +

+ The autoconf program produces a configure script from either + configure.in or configure.ac (see note below). +
+ The automake program produces a Makefile.in from a Makefile.am. +
+ The configure script is run to produce one or more Makefile files from + Makefile.in files. +
+ The make program uses the Makefile to compile the program. +

+ + + +The configure.in name used to be standard. However, the GNU +documentation now recommends configure.ac as it is more obvious which +program should be used when processing it. The files perform the same purpose +and have the same format the only difference is the name. + + +

+You will see autotools being used variously in both src_unpack and +src_compile. The QA people prefer it in src_unpack the rationale is +that src_unpack handles "getting the package ready to be compiled" but +there is no official policy which mandates this. +

+ +

+The autoreconf tool supposedly runs autoconf (and automake, +autoheader, aclocal, autopoint and libtoolize) as necessary. +Sometimes it works. Some packages ship a shell script named autogen.sh which +does the same thing (this is not related to autogen). +

+ + +You must not attempt to modify any of the generated files in +between running configure and make. This can lead to autotools +trying to be clever and recreate the files, in turn leading to your changes +being removed. In some situations this will also result in ./configure +arguments being silently dropped, which can give broken dependencies. +The best way to proceed is usually to work with the .ac / .in files +instead. + + + + + +

+Simple Autotools Patching Example + + +

+The following snippet illustrates the correct way to proceed after patching +either Makefile.am or configure.ac: +

+ + +src_unpack() { + unpack ${A} + cd "${S}" + + # Remove problematic LDFLAGS declaration + sed -i -e '/^LDFLAGS/d' src/Makefile.am + + # Rerun autotools + einfo "Regenerating autotools files..." + WANT_AUTOCONF=2.5 autoconf || die "autoconf failed" + WANT_AUTOMAKE=1.9 automake || die "automake failed" +} + +src_compile() { + econf $(use_enable nls) || die "econf failed" + emake || die "emake failed" +} + + +

+The einfo message before running autotools is not mandatory. However, these +steps can sometimes take a while and may produce no output, so it may make sense +to let the user know that something is still happening. See `Messages`_. +

+ + +

+ +

+The <c>configure.ac</c> File + + +

+The configure.ac file is used to create the ./configure script. It +consists of a series of macros which are processed and expanded by autoconf. +These macros can check for packages and libraries, handle --enable and +--with switches, and generate various files. +

+ + + + +Basic Format of <c>configure.ac</c> + + +

+The configure.ac file is a basic text file. Indenting and whitespace are +largely irrelevant. Comments are indicated by the string dnl (dnl is +actually a macro which discards the remainder of the input it stands for +"discard new line"). +

+ +

+If the previous sentence made you uneasy, you should probably stop reading this +page. It gets far worse. +

+ +

+A typical file might start with something like the following: +

+ + +dnl Process this file with autoconf +AC_INIT(appname, 0.1) +AC_PREREQ(2.5) +AC_CONFIG_SRCDIR(src/main.c) +AC_CONFIG_AUX_DIR(config) +AM_INIT_AUTOMAKE(1.8) + + +

+The AC_PREREQ line, if present, tells you which autoconf version you +need. This is useful, because autoconf is not compatible between versions. +In the above example, we need =autoconf-2.5*. and we should +export WANT_AUTOCONF="2.5" (or use the autoconf-2.59 script) when calling +autoconf. +

+ +

+The AM_INIT_AUTOMAKE line tells us which automake version we need. +Again, there is little chance that an automake-1.7 script will work properly +with automake-1.8. Setting WANT_AUTOMAKE="1.8" in the environment can be +used to make an unversioned automake call run the correct version. +

+ + +The WANT_ variables are a Gentoo feature that originally came from +Mandrake. Other distributions may handle things differently. + + +

+Usually, some standard checks will follow: +

+ + +dnl Check for toolchain and install components +AC_PROG_CC +AC_PROG_INSTALL +AC_PROG_LN_S +AC_PROG_RANLIB + + +

+For non-standard applications, you may also see manual checks: +

+ + +dnl Check for sed +AC_CHECK_PROGS(regex_cmd, sed) +if test x$regex_cmd = "x" ; then + AC_MSG_ERROR([sed is required to build the data files.]) +fi + + +

+You may also see checks for compiler features: +

+ + +dnl Check that our compiler can do const and inline +AC_C_CONST +AC_C_INLINE + + +

+Library and header checks: +

+ + +dnl Check for standard headers: +AC_HEADER_STDC +AC_HEADER_DIRENT +AC_CHECK_HEADERS([stdlib.h stdio.h libintl.h locale.h]) + +dnl Check for libraries: +AC_CHECK_LIB(ssl, SSL_free) + + +

+And function checks: +

+ + +dnl Check for functions: +AC_CHECK_FUNCS([setlocale strtol]) + + +

+Often these will be all jumbled together without any useful comments. In some +cases, many of the checks done won't even be necessary for the application in +question most autotools code is copy/pasted rather than written from scratch, +and autoscan (a tool which helps write configure.ac) is sometimes +over-eager to add in checks. +

+ +

+The file will finish with some output functions: +

+ + +AM_CONFIG_HEADER(config.h) +AC_OUTPUT(Makefile src/Makefile nls/Makefile man/Makefile tests/Makefile) + + +

+These are used to make the ./configure script generate the relevant files. +

+ + + + + +Enable and Disable Checks + + +

+So far we've only seen 'hard' dependencies. Many packages have optional +support for various extras (graphics toolkits, libraries which add +functionality, interpreters, features, ...). This is (if we're lucky) handled +via --enable-foo and --disable-foo switches to ./configure. which +are generated from autoconf rules. +

+ +

+A simple --enable / --disable function might look something like the +following: +

+ + +AC_MSG_CHECKING(--enable-cscope argument) +AC_ARG_ENABLE(cscope, + [ --enable-cscope Include cscope interface.], + [enable_cscope=$enableval], + [enable_cscope="no"]) +AC_MSG_RESULT($enable_cscope) +if test "$enable_cscope" = "yes"; then + AC_DEFINE(FEAT_CSCOPE) +fi + + +

+Sometimes more complicated checks are included based upon whether or not an +option is enabled. There are also some predefined macros which include +AC_ARG_ENABLE. so grepping configure.ac for AC_ARG_ENABLE may not +give a complete list. A better way is to use ./configure --help and check +the output. +

+ + +The third argument is used when a --enable or --disable +switch to ./configure is provided, and the fourth is used when such a +switch is not passed. A common misconception is that the third is enable +and the fourth is disable this is not the case. You may encounter +packages that get this wrong. + + +

+A simple way to check that a package is using this macro properly is to +install the optional dependency, and then try all of ./configure. +./configure --enable-foo and ./configure --disable-foo. If the second +and third runs give the same results, something is wrong. If the first run gives +a different result to the second and third, there is a good chance that a +misunderstanding of the AC_ARG_ENABLE arguments is to blame. +

+ + + + + +With and Without Checks + + +

+A simple --with / --without check might look like: +

+ + +AC_MSG_CHECKING([whether to enable foo]) +AC_ARG_WITH(foo, + [ --with-foo enable foo support], + with_foo=$withval, + with_foo=yes) +AC_MSG_RESULT($with_foo) + + +

+Again, the third argument is for 'specified' and the fourth for 'not specified', +and there are standard macros which include with options. +

+ + + + + +Automatic Checks + + +

+It's possible to write autoconf rules which bypass the manual enable / disable +convention (or which just ignore what the user asks for). If your package does +this, it must be fixed to avoid dependency problems. +

+ +

+The most common form is packages which simply use AC_CHECK_LIB to decide +whether or not to enable a feature. If you find a package which does this, you +must change the behaviour. +

+ + + + + +Quoting Rules for <c>configure.ac</c> + + +

+Behind the scenes, autoconf makes heavy use of the m4 macro processor to +do the work. The m4 quote characters are set by autoconf to be [ and +] for opening and closing quotes respectively. Using " or ' may +produce unexpected results. +

+ +

+To include a literal left square bracket, the easiest thing to do is to use the +special string @<:@. For a right bracket, use @:>@. +

+ +

+For example: +

+ + +AC_MSG_RESULT(the first) +AC_MSG_RESULT([the second]) +AC_MSG_RESULT("the third") +AC_MSG_RESULT(@<:@the fourth@:>@) +AC_MSG_RESULT([@<:@the fifth@:>@]) + + +

+gives: +

+ +

+    the first
+    the second
+    "the third"
+    [the fourth]
+    [the fifth]
+

+ +

+When in doubt, it is generally safest to quote macro arguments using [ ] +rather than leaving things unquoted. +

+ + + +

+ +

+The <c>Makefile.am</c> Files + + +

+The Makefile.am file is processed by automake to create Makefile.in. +which is in turn processed by configure to create Makefile. which is in +turn used by make to build the software. +

+ +

+The basic format is like that of a Makefile. However, you will see various +'special' variables being set, rather than every rule being written manually. +

+ +

+A very simple example: +

+ + +bin_PROGRAMS = myapp +myapp_SOURCES = myapp_commandline.c myapp.c + + +

+All the standard GNU rules will be generated, so make. make clean. +make distclean. make dist and so on will all work here. +

+ +

+You may also see some standard Makefile constructs showing up whenever there +isn't a standard automake way of handling a certain task. For example: +

+ + +CLEANFILES = glep31check.1 +man_MANS = glep31check.1 +EXTRA_DIST = glep31check.in + +%.1 : %.in + @regex_cmd@ -e "s,\@VERSION\@,$(VERSION),g" $? > $@ + + +

+Here, the @regex_cmd@ variable will be substituted with whatever +configure detects (sed in this case) when creating the Makefile. +This is handled via the macro AC_SUBST(VARNAME) in configure.ac. +

+ + + + +Makefile Variables + + +

+Sometimes, badly behaved Makefile.am files will override user variables such +as CFLAGS. This must not be allowed see `Not Filtering Variables`_. There +are separate special variables which should be used in these situations for +setting CFLAGS. for example, a Makefile.am should use AM_CFLAGS so +that user preferences are not ignored. +

+ +

+So, if a Makefile.am contains, say: +

+ +

+CFLAGS="-Wall"
+

+ +

+You should sed or patch it to use: +

+ +

+AM_CFLAGS="-Wall"
+

+ +

+Remember to manually run autoconf then automake if you do this. +

+ + + +

+ +

+The <c>config.h.in</c> File + + +

+The config.h.in file is generated by autoheader. You shouldn't have to +worry about this usually, but occasionally you may need to run autoheader +manually as part of the build process if upstream do not ship a pre-generated +version. +

+ + +

+ +

+<c>aclocal</c> and <c>m4</c> Files + + +

+In the configure.ac or configure.in files you can call not only the +default macros defined by autoconf and automake. but also other +functions which can be defined by specific packages like libraries and programs +to check for their features in the correct manner. +

+ +

+Those functions are (usually) defined in m4 files placed in +the /usr/share/aclocal directory by packages. Problems can arise when you +need to regenerate the autotools files, because the functions used by the +configure.ac file can be defined in an m4 macro file which isn't +installed on the user's system. This is the case for example for some optional +features which require libraries and are disabled by USE flags. If the +m4 files aren't installed in the user's system, the autoconf step will +fail. +

+ +

+To resolve this, most packages just ship the m4 macro files needed for their +configure.ac in an m4 subdirectory in the source package. Unfortunately, +not all m4 directories are complete, even if they are present. +

+ +

+In those cases you need to find out the m4 file, usually installed by the +dependency in /usr/share/aclocal. and make sure that the src_unpack +stage both makes available those files to the autotools and calls aclocal to +recreate the aclocal.m4 file which is used by autoconf when creating the +configure script. +

+ +

+Usually it's more than one m4 file which is missing, so you probably want to +package them in a tarball, and add it to SRC_URI. After making sure that the +tarball is extracted somewhere in ${WORKDIR} (say, in a gentoo-m4 +directory), you usually have two general ways to handle those macro files, one +for packages which ships with an incomplete m4 directory and one for +packages which ships without the m4 directory. +

+ +

+In the first case you usually want to do something like: +

+ + +einfo "Regenerating autotools files..." +cp ${WORKDIR}/gentoo-m4 ${S}/m4 || die "m4 copy failed" +WANT_AUTOCONF="2.5" aclocal -I ${S}/m4 || die "aclocal failed" +WANT_AUTOCONF="2.5" autoconf || die "autoconf failed" + + +

+and so on. In the second case you can simplify it in this way: +

+ + +einfo "Regenerating autotools files..." +WANT_AUTOCONF="2.5" aclocal -I ${WORKDIR}/gentoo-m4 || die "aclocal failed" +WANT_AUTOCONF="2.5" autoconf || die "autoconf failed" + + +

+without need to copy the files. +

+ +

+It's always better inform upstream when the needed m4 files are missing in +the distribution, asking them to add all the needed files in the source tarball +to avoid version conflicts if the macro changes. +

+ + +

+ +

+Libtool + + + +Stuff about libtool, libtoolize, elibtoolize, libtool.eclass. Which I +know almost nothing about... Yay! + + + +

+ +

+Further Autotools Reading + + +

+For more details on autotools: +

+ +

+ The book "GNU Autoconf, Automake and Libtool" by Gary V. Vaughan, Ben + Elliston, Tom Tromey and Ian Lance Taylor (often called "The Autobook") + provides a good but somewhat outdated description of autotools. It is + `freely available online <http://sources.redhat.com/autobook/>`_. +
+ The GNU documentation for the various autotools components is of varying + quality and completeness: +

+ `GNU automake Manual + <http://www.gnu.org/software/automake/manual/automake.html>`_ +
+ `GNU autoconf Manual <http://www.gnu.org/software/autoconf/manual/>`_ +
+ `GNU libtool Manual <http://www.gnu.org/software/libtool/manual.html>`_ +
+ `GNU m4 Manual <http://www.gnu.org/software/m4/manual/m4.html>`_ +

+ There are some good overview lectures available online. `These slides + <http://vipe.technion.ac.il/~shlomif/lecture/Autotools/slides/>`_ are one + example. +

diff --git a/general-concepts/dependencies/text.xml b/general-concepts/dependencies/text.xml index da5153d..3d5d074 100644 --- a/general-concepts/dependencies/text.xml +++ b/general-concepts/dependencies/text.xml @@ -99,7 +99,7 @@ DEPEND="dev-lang/ruby

Each atom is the full category and name of a package. Atoms are separated by -arbitrary whitespace -- convention is to specify one atom per line for +arbitrary whitespace convention is to specify one atom per line for readability purposes. When specifying names, the category part should be treated as mandatory.

diff --git a/general-concepts/digest-and-manifest/text.xml b/general-concepts/digest-and-manifest/text.xml index 541d622..952824d 100644 --- a/general-concepts/digest-and-manifest/text.xml +++ b/general-concepts/digest-and-manifest/text.xml @@ -31,7 +31,7 @@ will do this automatically if cvs is included in FEATURES.

To generate digests and Manifest, use ebuild foo.ebuild digest. When committing, the Manifest file must be regenerated to handle any CVS keyword -expansion changes -- repoman will do this automatically. +expansion changes repoman will do this automatically.

diff --git a/general-concepts/ebuild-revisions/text.xml b/general-concepts/ebuild-revisions/text.xml index 51c109f..33b7de1 100644 --- a/general-concepts/ebuild-revisions/text.xml +++ b/general-concepts/ebuild-revisions/text.xml @@ -6,14 +6,14 @@

Ebuilds may have a Gentoo revision number associated with them. This is a --rX suffix, where X is an integer -- see `File Naming Rules`_. This +-rX suffix, where X is an integer see `File Naming Rules`_. This component must only be used for Gentoo changes, not upstream releases. By default, -r0 is implied and should not be specified manually.

Ebuilds should have their -rX incremented whenever a change is made which -will make a substantial difference to what gets installed by the package -- by +will make a substantial difference to what gets installed by the package by substantial, we generally mean "something for which many users would want to upgrade". This is usually for bugfixes.

diff --git a/general-concepts/filesystem/text.xml b/general-concepts/filesystem/text.xml index e2eac96..64f9ac4 100644 --- a/general-concepts/filesystem/text.xml +++ b/general-concepts/filesystem/text.xml @@ -58,7 +58,7 @@ which is not modified at runtime.

-Try to avoid installing unnecessary things into /etc -- every file in there +Try to avoid installing unnecessary things into /etc every file in there is additional work for the system administrator. In particular, non-text files and files that are not intended for system administrator usage should be moved to /usr/share. diff --git a/general-concepts/herds-and-projects/text.xml b/general-concepts/herds-and-projects/text.xml index c6f9811..c4ff6d5 100644 --- a/general-concepts/herds-and-projects/text.xml +++ b/general-concepts/herds-and-projects/text.xml @@ -8,7 +8,7 @@

A herd is a collection of developers who maintain a collection of related packages. A herd has an associated email address which can be used for bugzilla -assignments. This email address is not always herdname@gentoo.org -- for +assignments. This email address is not always herdname@gentoo.org for example, because of the way Gentoo's email aliases are set up, the cron herd use cron-bugs@gentoo.org (aliases cannot match system usernames).

@@ -19,7 +19,7 @@ may have herds associated with it.

-Sometimes herd and project names overlap -- for example, the sparc project +Sometimes herd and project names overlap for example, the sparc project has an associated sparc herd which maintains sparc-specific packages (such as the silo bootloader). This is not always the case.

diff --git a/general-concepts/install-destinations/text.xml b/general-concepts/install-destinations/text.xml index ff51cdf..9e9fe43 100644 --- a/general-concepts/install-destinations/text.xml +++ b/general-concepts/install-destinations/text.xml @@ -8,13 +8,13 @@

When an ebuild runs the src_install phase, it installs an image of the package in question from ${S} into ${D}. Ebuilds must not attempt to -perform any operation upon the live filesystem at this stage -- this will break +perform any operation upon the live filesystem at this stage this will break binaries, and will (often) cause a sandbox violation notice.

When installing, portage will install the image in ${D} into ${ROOT}. By -default, ${ROOT} points to /, although the user can alter this -- for +default, ${ROOT} points to /, although the user can alter this for example, the user may be building a minimal image for another system in a different location. If your package must operate on the live filesystem (for example, to create some cache files during pkg_postinst), you must ensure diff --git a/general-concepts/mirrors/text.xml b/general-concepts/mirrors/text.xml index 47051db..dbbd855 100644 --- a/general-concepts/mirrors/text.xml +++ b/general-concepts/mirrors/text.xml @@ -14,7 +14,7 @@ trying the original upstream location.

-This is generally desired behaviour -- upstream mirrors are prone to being +This is generally desired behaviour upstream mirrors are prone to being rearranged, tidied out or having files modified.

@@ -33,7 +33,7 @@ certain files.

The RESTRICT="primaryuri" setting causes portage to try -original locations first, and then fall back to mirrors if necessary -- this +original locations first, and then fall back to mirrors if necessary this is sometimes useful if approximate download counts are needed, or if upstream have a reliable mirror setup.

diff --git a/general-concepts/overlay/text.xml b/general-concepts/overlay/text.xml index d3ae6a1..dcf79ad 100644 --- a/general-concepts/overlay/text.xml +++ b/general-concepts/overlay/text.xml @@ -42,7 +42,7 @@ Be very careful when using eclasses in an overlay. Portage will not do cache updates when an overlay eclass is changed, nor will it do cache updates when a main portage tree eclass which is used by an overlay ebuild changes. You may also encounter bogus 'illegal inherit' notices when working with eclasses in -overlay (see `QA Notice -- ECLASS foo inherited illegally`_). To be safe, +overlay (see `QA Notice ECLASS foo inherited illegally`_). To be safe, manually touch all relevant overlay files after updating overlay eclasses.

diff --git a/general-concepts/sandbox/text.xml b/general-concepts/sandbox/text.xml index d474f26..216be0d 100644 --- a/general-concepts/sandbox/text.xml +++ b/general-concepts/sandbox/text.xml @@ -13,7 +13,7 @@ badly written build systems) accidentally writing outside of permitted locations

All packages must build correctly when sandbox is active. Packages must not -achieve this by using sneaky tricks to make sandbox warnings not show up -- the +achieve this by using sneaky tricks to make sandbox warnings not show up the sandbox is there to ensure that binary packages will work correctly, and that a badly written Makefile won't cause problems. Using addwrite is generally not the correct solution. diff --git a/general-concepts/slotting/text.xml b/general-concepts/slotting/text.xml index 928f3fd..9625a1a 100644 --- a/general-concepts/slotting/text.xml +++ b/general-concepts/slotting/text.xml @@ -6,14 +6,14 @@

Packages can support having multiple versions installed simultaneously. This is -useful for libraries which may have changed interfaces between versions -- for +useful for libraries which may have changed interfaces between versions for example, the gtk+ package can install both versions 1.2 and 2.6 in parallel. This feature is called slotting.

Most packages have no need for slotting. These packages specify SLOT="0" in -the ebuilds. This is not the same as specifying an empty slot -- an empty +the ebuilds. This is not the same as specifying an empty slot an empty slot means "disable slotting entirely", and should not be used.

@@ -43,7 +43,7 @@ It is not possible to DEPEND upon a package in a specific slot. Currently portage will accept an arbitrary string for the value of SLOT. For future compatibility, it is recommended that slots contain only characters which are allowed in an ebuild name or version (alphanumerics, hypens, full stops, -underscores, the plus character) -- other characters may cause problems with +underscores, the plus character) other characters may cause problems with future portage enhancements.

diff --git a/general-concepts/use-flags/text.xml b/general-concepts/use-flags/text.xml index 34ec457..3904a4c 100644 --- a/general-concepts/use-flags/text.xml +++ b/general-concepts/use-flags/text.xml @@ -7,7 +7,7 @@

USE flags are to control optional dependencies and settings which the user may reasonably want to select. For example, vim can optionally build with support for -the ruby interpreter, and it needs ruby installed to do this -- we use the ruby USE +the ruby interpreter, and it needs ruby installed to do this we use the ruby USE flag to provide this option. On the other hand, glark requires ruby no matter what, so no USE flag is used here.

@@ -47,7 +47,7 @@ RDEPEND="x86? ( fakemedia? ( >=media-libs/fakemedia-1.1 ) )"

-Except this is pretty nasty -- what happens when an AMD64 binary is made as +Except this is pretty nasty what happens when an AMD64 binary is made as well? Also, users on other archs will see fakemedia listed in emerge -pv output, even though it is not actually available.

User environment variables and make.conf settings get passed on to ebuilds. -This can be useful -- it's how CFLAGS and friends work, for example -- but +This can be useful it's how CFLAGS and friends work, for example but it can also result in nasty build-breaking variables like LANG and LC_ALL getting through. Currently no sanitisation is performed upon the environment. @@ -52,7 +52,7 @@ respected (selective filtering is fine, but outright ignoring is not). Ignoring