Using GNU Autotools

42 Pages·2010·1.72 MB·English

Foreword ToolVersions
Foreword (1/2) Foreword (2/2)
This document was updated for the following releases of the Autotools:
This presentation targets developers familiar with Unix development tools
GNU Autoconf 2.65 (November 2009)
(shell, make, compiler) that want to learn Autotools.
GNU Automake 1.11.1 (December 2009)
GNU Libtool 2.2.6b (November 2009)
The latest version of this document can be retrieved from
GNU Gettext 0.17 (November 2007)
http://www.lrde.epita.fr/~adl/autotools.html
These were the last releases at the time of writing.
Please mail me corrections and suggestions about this document at
[email protected]. The usage of these tools has improved a lot over the last years.
Do not send me any general question about the Autotools. Use the Some syntaxes used here will not work with older tools.
appropriate mailing list instead ([email protected], or This a deliberate choice:
[email protected]). New users should learn today’s recommended usages.
Make sure you have up-to-date tools and do not bother with old
releases.
A.Duret-Lutz UsingGNUAutotools May16,2010 1/162 A.Duret-Lutz UsingGNUAutotools May16,2010 2/162
TitlePage
Part I
Using GNU Autotools
The GNU Build System
Alexandre Duret-Lutz 1 Goals
[email protected] Portable Packages
Uniform Builds
2 Package Use Cases
May 16, 2010 The User Point of View
The Power User Point of View
Copyright (cid:13)c 2010 Alexandre Duret-Lutz The Packager Point of View
http://creativecommons.org/licenses/by-sa/2.0/ The Maintainer Point of View
3 The configure Process
Trivial source code examples displayed in this tutorial (such as
the C files, Makefile.ams, and configure.acs of all the ‘amhello’ 4 Why We Need Tools
projects) can be reused as if they were in the public domain.
A.Duret-Lutz UsingGNUAutotools May16,2010 3/162 A.Duret-Lutz UsingGNUAutotools May16,2010 4/162
Goals PortablePackages Goals PortablePackages
Portable Packages Sources of Non-Portability in C
1 Goals Consider C functions...
Portable Packages that do not exist everywhere (e.g., strtod())
Uniform Builds
that have different names (e.g., strchr() vs. index())
that have varying prototypes
2 Package Use Cases
(e.g., int setpgrp(void); vs. int setpgrp(int, int);)
The User Point of View
The Power User Point of View that can behave differently (e.g., malloc(0);)
The Packager Point of View that might require other libraries
The Maintainer Point of View (is pow() in libm.so or in libc.so?)
that can be defined in different headers
3 The configure Process
(string.h vs. strings.h vs. memory.h)
4 Why We Need Tools How should a package deal with those?
A.Duret-Lutz UsingGNUAutotools May16,2010 5/162 A.Duret-Lutz UsingGNUAutotools May16,2010 6/162
Goals PortablePackages Goals PortablePackages
Possible Solutions Code Cluttered with #if/#else
Excerpt of ffcall-1.10’s alloc trampoline()
#if !defined(CODEEXECUTABLE)
static long pagesize = 0;
#if defined(EXECUTABLEVIAMMAPDEVZERO)
static int zero fd;
Slice the code with lots of #if/#else #endif
if (!pagesize) {
Create substitution macros
#if defined(HAVEMACHVM)
pagesize = vm page size;
Create substitution functions
#else
pagesize = getpagesize();
The latter two are to be preferred.
#endif
#if defined(EXECUTABLEVIAMMAPDEVZERO)
zero fd = open(”/dev/zero”, ORDONLY,0644);
if (zero fd < 0) {
fprintf(stderr , ”trampoline: Cannot open /dev/zero!\n”);
abort();
}
#endif
}
#endif
A.Duret-Lutz UsingGNUAutotools May16,2010 7/162 A.Duret-Lutz UsingGNUAutotools May16,2010 8/162
Goals PortablePackages Goals PortablePackages
Substitution macros Substitution functions
If strdup() does not exist, link your program with a replacement
definition such as
Excerpt of coreutils-5.2.1’s system.h strdup.c (from the GNU C library)
#if ! HAVE FSEEKO && ! defined fseeko char ∗
# define fseeko (s , o, w) ((o) == (long) (o) \ strdup (const char ∗s)
? fseek (s , o, w) \ {
: (errno = EOVERFLOW, −1)) size t len = strlen (s) + 1;
#endif void ∗new = malloc (len );
if (new == NULL)
Then use fseeko() whether it exists or not. return NULL;
return (char ∗) memcpy (new, s , len );
}
A.Duret-Lutz UsingGNUAutotools May16,2010 9/162 A.Duret-Lutz UsingGNUAutotools May16,2010 10/162
Goals UniformBuilds Goals UniformBuilds
Uniform Builds Need for Automatic Configuration
1 Goals
Maintaining a collection of #define for each system by hand is
Portable Packages
cumbersome.
Uniform Builds
Requiring users to add the necessary -D, -I, and -l compilation
2 Package Use Cases options to Makefile is burdensome.
The User Point of View Complicated builds hinder the acceptance of free software.
The Power User Point of View
The Packager Point of View
The Maintainer Point of View In 1991 people started to write shell scripts to guess these settings
for some GNU packages.
3 The configure Process Since then the configure script is mandatory in any package of the
GNU project.
4 Why We Need Tools
A.Duret-Lutz UsingGNUAutotools May16,2010 11/162 A.Duret-Lutz UsingGNUAutotools May16,2010 12/162
Goals UniformBuilds Goals UniformBuilds
configure’s Purpose GNU Coding Standards
configure http://www.gnu.org/prep/standards/
Practices that packages of the GNU project should follow:
program behavior
Makefile src/Makefile config.h how to report errors,
standard command line options,
etc.
configure probes the systems for required functions, libraries, and coding style
tools configuration
then it generates a config.h file with all #defines Makefile conventions
as well as Makefiles to build the package etc.
A.Duret-Lutz UsingGNUAutotools May16,2010 13/162 A.Duret-Lutz UsingGNUAutotools May16,2010 14/162
PackageUseCases TheUserPointofView PackageUseCases TheUserPointofView
The User Point of View Standard Installation Procedure
~ % tar zxf amhello-1.0.tar.gz
1 Goals ~ % cd amhello-1.0
Portable Packages
~/amhello-1.0 % ./configure
Uniform Builds
...
~/amhello-1.0 % make
2 Package Use Cases
...
The User Point of View
~/amhello-1.0 % make check
The Power User Point of View
...
The Packager Point of View
~/amhello-1.0 % su
The Maintainer Point of View
Password:
/home/adl/amhello-1.0 # make install
3 The configure Process
...
/home/adl/amhello-1.0 # exit
4 Why We Need Tools
~/amhello-1.0 % make installcheck
...
A.Duret-Lutz UsingGNUAutotools May16,2010 15/162 A.Duret-Lutz UsingGNUAutotools May16,2010 16/162
PackageUseCases TheUserPointofView PackageUseCases TheUserPointofView
Standard Makefile Targets Standard File System Hierarchy
‘make all’ Build programs, libraries, documentation, etc. Directory variable Default value
(Same as ‘make’.) prefix /usr/local
exec-prefix prefix
‘make install’ Install what needs to be installed.
bindir exec-prefix/bin
‘make install-strip’ Same as ‘make install’, then strip debugging
libdir exec-prefix/lib
symbols.
...
‘make uninstall’ The opposite of ‘make install’.
includedir prefix/include
‘make clean’ Erase what has been built (the opposite of ‘make datarootdir prefix/share
all’). datadir datarootdir
‘make distclean’ Additionally erase anything ‘./configure’ mandir datarootdir/man
created. infodir datarootdir/info
‘make check’ Run the test suite, if any. ...
‘make installcheck’ Check the installed programs or libraries, if
~/amhello-1.0 % ./configure --prefix ~/usr
supported.
~/amhello-1.0 % make
‘make dist’ Create PACKAGE-VERSION.tar.gz.
~/amhello-1.0 % make install
A.Duret-Lutz UsingGNUAutotools May16,2010 17/162 A.Duret-Lutz UsingGNUAutotools May16,2010 18/162
PackageUseCases TheUserPointofView PackageUseCases ThePowerUserPointofView
Standard Configuration Variables The Power User Point of View
‘./configure’ automatically detects many settings.
1 Goals
You can force some of them using configuration variables.
Portable Packages
CC C compiler command Uniform Builds
CFLAGS C compiler flags
2 Package Use Cases
CXX C++ compiler command
The User Point of View
CXXFLAGS C++ compiler flags
The Power User Point of View
LDFLAGS linker flags The Packager Point of View
CPPFLAGS C/C++ preprocessor flags The Maintainer Point of View
... See ‘./configure --help’ for a full list.
3 The configure Process
~/amhello-1.0 % ./configure --prefix ~/usr CC=gcc-3 \
4 Why We Need Tools
CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib
A.Duret-Lutz UsingGNUAutotools May16,2010 19/162 A.Duret-Lutz UsingGNUAutotools May16,2010 20/162
PackageUseCases ThePowerUserPointofView PackageUseCases ThePowerUserPointofView
Overriding Default Configuration Settings with config.site Parallel Build Trees (a.k.a. VPATH Builds)
Recall that old command
~/amhello-1.0 % ./configure --prefix ~/usr CC=gcc-3 \
Objects files, programs, and libraries are built where configure was run.
CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib
~ % tar zxf ~/amhello-1.0.tar.gz
Common configuration settings can be put in prefix/share/config.site ~ % cd amhello-1.0
~/amhello-1.0 % cat ~/usr/share/config.site ~/amhello-1.0 % mkdir build && cd build
test -z "$CC" && CC=gcc-3 ~/amhello-1.0/build % ../configure
test -z "$CPPFLAGS" && CPPFLAGS=-I$HOME/usr/include ~/amhello-1.0/build % make
test -z "$LDFLAGS" && LDFLAGS=-L$HOME/usr/lib ...
Sources files are in ∼/amhello-1.0/,
Reducing the command to...
built files are all in ∼/amhello-1.0/build/.
~/amhello-1.0 % ./configure --prefix ~/usr
configure: loading site script /home/adl/usr/share/config.site
...
A.Duret-Lutz UsingGNUAutotools May16,2010 21/162 A.Duret-Lutz UsingGNUAutotools May16,2010 22/162
PackageUseCases ThePowerUserPointofView PackageUseCases ThePowerUserPointofView
Parallel Build Trees for Multiple Architectures Two Part Installation
Builds for multiple architectures can share the same source tree.
Have the source on a (possibly read-only) shared directory
~ % cd /nfs/src
/nfs/src % tar zxf ~/amhello-1.0.tar.gz ‘make install’
=
Compilation on first host ‘make install-exec’ install platform-dependent files
+
~ % mkdir /tmp/amh && cd /tmp/amh
‘make install-data’ install platform-independent files
/tmp/amh % /nfs/src/amhello-1.0/configure
(can be shared among multiple machines)
/tmp/amh % make && sudo make install
Compilation on second host, assuming shared data
~ % mkdir /tmp/amh && cd /tmp/amh
/tmp/amh % /nfs/src/amhello-1.0/configure
/tmp/amh % make && sudo make install-exec
A.Duret-Lutz UsingGNUAutotools May16,2010 23/162 A.Duret-Lutz UsingGNUAutotools May16,2010 24/162
PackageUseCases ThePowerUserPointofView PackageUseCases ThePowerUserPointofView
Cross-Compilation Cross-Compilation
~/amhello-1.0 % ./configure --build i686-pc-linux-gnu \ ~/amhello-1.0 % ./configure --build i686-pc-linux-gnu \
--host i586-mingw32msvc --host i586-mingw32msvc
checking for a BSD-compatible install... /usr/bin/install -c ...
checking whether build environment is sane... yes ~/amhello-1.0 % make
checking for gawk... gawk
...
checking whether make sets $(MAKE)... yes ~/amhello-1.0 % cd src; file hello.exe
checking for i586-mingw32msvc-strip... i586-mingw32msvc-strip hello.exe: MS Windows PE 32-bit Intel 80386 console executable not relocatable
checking for i586-mingw32msvc-gcc... i586-mingw32msvc-gcc
Of course you need a cross-compiler installed first.
checking for C compiler default output file name... a.exe
checking whether the C compiler works... yes Cross-compilation configure options:
checking whether we are cross compiling... yes
‘--build=BUILD’ The system on which the package is built.
checking for suffix of executables... .exe
‘--host=HOST’ The system where built programs & libraries will
checking for suffix of object files... o
checking whether we are using the GNU C compiler... yes run.
checking whether i586-mingw32msvc-gcc accepts -g... yes ‘--target=TARGET’ Only when building compiler tools: the system for
checking for i586-mingw32msvc-gcc option to accept ANSI C... which the tools will create output.
...
For simple cross-compilation, only ‘--host=HOST’ is needed.
A.Duret-Lutz UsingGNUAutotools May16,2010 25/162 A.Duret-Lutz UsingGNUAutotools May16,2010 25/162
PackageUseCases ThePowerUserPointofView PackageUseCases ThePackagerPointofView
Renaming Programs at Install Time The Packager Point of View
Maybe hello is already a command on this host?
1 Goals
‘--program-prefix=PREFIX’ Portable Packages
prepend PREFIX to installed program names, Uniform Builds
‘--program-suffix=SUFFIX’
2 Package Use Cases
append SUFFIX to installed program names,
The User Point of View
‘--program-transform-name=PROGRAM’
The Power User Point of View
run ‘sed PROGRAM’ on installed program names.
The Packager Point of View
The Maintainer Point of View
~/amhello-1.0 % ./configure --program-prefix test-
~/amhello-1.0 % make 3 The configure Process
~/amhello-1.0 % sudo make install
4 Why We Need Tools
Will install hello as /usr/local/bin/test-hello.
A.Duret-Lutz UsingGNUAutotools May16,2010 26/162 A.Duret-Lutz UsingGNUAutotools May16,2010 27/162
PackageUseCases ThePackagerPointofView PackageUseCases TheMaintainerPointofView
Building Binary Packages Using DESTDIR The Maintainer Point of View
DESTDIR is used to relocate a package at install time.
~/amhello-1.0 % ./configure --prefix /usr 1 Goals
... Portable Packages
~/amhello-1.0 % make Uniform Builds
...
~/amhello-1.0 % make DESTDIR=$HOME/inst install 2 Package Use Cases
The User Point of View
...
The Power User Point of View
~/amhello-1.0 % cd ~/inst
The Packager Point of View
~/inst % tar zcvf ~/amhello-1.0-i686.tar.gz .
The Maintainer Point of View
./
./usr/
3 The configure Process
./usr/bin/
./usr/bin/hello
4 Why We Need Tools
... and ∼/amhello-1.0-i686.tar.gz is ready to be uncompressed in / on
many hosts.
A.Duret-Lutz UsingGNUAutotools May16,2010 28/162 A.Duret-Lutz UsingGNUAutotools May16,2010 29/162
PackageUseCases TheMaintainerPointofView PackageUseCases TheMaintainerPointofView
Preparing Distributions Automatic Dependency Tracking
~/amhello-1.0 % ./configure --prefix /usr
‘make dist’ Create PACKAGE-VERSION.tar.gz.
...
‘make distcheck’ Likewise, with many sanity checks. Prefer this one! checking dependency style of gcc... gcc3
...
‘make distcheck’ ensures most of the use cases presented so far work.
It tests VPATH builds (with read-only source tree) Dependency tracking is performed as a side-effect of compilation.
Several methods are supported, and checked for by configure.
It ensures ‘make clean’, ‘make distclean’, and ‘make uninstall’
(The gcc3 method above is the fastest.)
do not omit files,
It checks that DESTDIR installations work, Dependency tracking is only needed when the source files change;
it can be safely disabled for throw-away installation builds.
It runs the test suite (both ‘make check’ and ‘make
Slow methods must be enabled explicitly.
installcheck’).
‘--disable-dependency-tracking’ speed up one-time builds
Releasing a package that fails ‘make distcheck’ means releasing a
package that will disappoint many users. ‘--enable-dependency-tracking’ do not reject slow dependency
extractors
A.Duret-Lutz UsingGNUAutotools May16,2010 30/162 A.Duret-Lutz UsingGNUAutotools May16,2010 31/162
PackageUseCases TheMaintainerPointofView TheconfigureProcess
Nested Packages The configure Process
1 Goals
Autoconfiscated packages can be nested to arbitrary depth. Portable Packages
A package can distribute a third-party library it uses in a subdirectory. Uniform Builds
It’s possible to gather many packages this way to distribute a set of
tools. 2 Package Use Cases
For installers: The User Point of View
A single package to configure, build, and install. The Power User Point of View
‘configure’options are passed recursively to sub-packages. The Packager Point of View
‘configure --help=recursive’shows the help of all sub-packages.
The Maintainer Point of View
For maintainers:
Easier integration. 3 The configure Process
The sub-packageis autonomous.
4 Why We Need Tools
A.Duret-Lutz UsingGNUAutotools May16,2010 32/162 A.Duret-Lutz UsingGNUAutotools May16,2010 33/162
TheconfigureProcess TheconfigureProcess
The (simplified) configure process The (real) configure process
Makefile.in src/Makefile.in config.h.in Makefile.in src/Makefile.in config.h.in
configure
configure
config.log
Makefile src/Makefile config.h
*.in files are configuration templates config.log contains a trace of the configuration
from which configure generates the configuration files to use for building reconfiguration
A.Duret-Lutz UsingGNUAutotools May16,2010 34/162 A.Duret-Lutz UsingGNUAutotools May16,2010 35/162
TheconfigureProcess TheconfigureProcess
The (real) configure process The (real) configure process
Makefile.in src/Makefile.in config.h.in Makefile.in src/Makefile.in config.h.in
configure configure
config.status config.status
config.log config.cache config.log
Makefile src/Makefile config.h Makefile src/Makefile config.h
config.status will actually process the templates ‘configure -C’ caches results in config.cache to speed up
reconfiguration reconfigurations
A.Duret-Lutz UsingGNUAutotools May16,2010 35/162 A.Duret-Lutz UsingGNUAutotools May16,2010 35/162
WhyWeNeedTools WhyWeNeedTools
Why We Need Tools Why We Need Tools
If you try to mimic this build system by hand, you’ll discover that
1 Goals
The GNU Build System has a lot of features.
Portable Packages
Some users may expect features you do not use.
Uniform Builds
Implementing them portably is difficult, and exhausting.
2 Package Use Cases (Think portable shell scripts, portable Makefiles, on systems you may
The User Point of View not have handy.)
The Power User Point of View You will have to upgrade your setup to follow changes of the GNU
The Packager Point of View Coding Standards.
The Maintainer Point of View
GNU Autotools provide:
3 The configure Process
Tools to create the GNU Build System from simple instructions.
A central place where fixes and improvements are made.
4 Why We Need Tools
(A bug-fix for a portability issue benefits every package.)
A.Duret-Lutz UsingGNUAutotools May16,2010 36/162 A.Duret-Lutz UsingGNUAutotools May16,2010 37/162