Foreword Tool Versions 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) The latest version of this document can be retrieved from GNU Libtool 2.2.6b (November 2009) 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 Using GNU Autotools May 16, 2010 1 / 162 A. Duret-Lutz Using GNU Autotools May 16, 2010 2 / 162 Title Page 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 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 Using GNU Autotools May 16, 2010 3 / 162 A. Duret-Lutz Using GNU Autotools May 16, 2010 4 / 162 Goals Portable Packages Goals Portable Packages 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()) 2 Package Use Cases that have varying prototypes The User Point of View (e.g., int setpgrp(void); vs. int setpgrp(int, int);) 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 Using GNU Autotools May 16, 2010 5 / 162 A. Duret-Lutz Using GNU Autotools May 16, 2010 6 / 162 Goals Portable Packages Goals Portable Packages Possible Solutions Code Cluttered with #if/#else Excerpt of ffcall-1.10’s alloc trampoline() #i f ! defined(CODE EXECUTABLE ) static long pagesize = 0; #i f d e f i n e d (EXECUTABLE VIA MMAP DEVZERO) static int zero fd ; Slice the code with lots of #if/#else #endif i f (! pagesize) { Create substitution macros #i f d e f i n e d (HAVE MACH VM) pagesize = vm page size; Create substitution functions #else pagesize = getpagesize(); The latter two are to be preferred. #endif #i f d e f i n e d (EXECUTABLE VIA MMAP DEVZERO) zero fd = open(”/dev/zero”, O RDONLY, 0 6 4 4 ) ; i f (zero f d < 0) { fprintf(stderr , ”trampoline: Cannot open /dev/zero! \ n”); abort (); } #endif } #endif A. Duret-Lutz Using GNU Autotools May 16, 2010 7 / 162 A. Duret-Lutz Using GNU Autotools May 16, 2010 8 / 162 Goals Portable Packages Goals Portable Packages 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) \ { : ( e r r n o = 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 Using GNU Autotools May 16, 2010 9 / 162 A. Duret-Lutz Using GNU Autotools May 16, 2010 10 / 162 Goals Uniform Builds Goals Uniform Builds Uniform Builds Need for Automatic Configuration 1 Goals Portable Packages Maintaining a collection of #define for each system by hand is Uniform Builds cumbersome. 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 Using GNU Autotools May 16, 2010 11 / 162 A. Duret-Lutz Using GNU Autotools May 16, 2010 12 / 162 Goals Uniform Builds Goals Uniform Builds 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 Using GNU Autotools May 16, 2010 13 / 162 A. Duret-Lutz Using GNU Autotools May 16, 2010 14 / 162 Package Use Cases The User Point of View Package Use Cases The User Point of View 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 ... 4 Why We Need Tools /home/adl/amhello-1.0 # exit ~/amhello-1.0 % make installcheck ... A. Duret-Lutz Using GNU Autotools May 16, 2010 15 / 162 A. Duret-Lutz Using GNU Autotools May 16, 2010 16 / 162 Package Use Cases The User Point of View Package Use Cases The User Point of View Standard Makefile Targets Standard File System Hierarchy ‘make all’ Build programs, libraries, documentation, etc. Directory variable Default value (Same as ‘make’.) prefix /usr/local ‘make install’ Install what needs to be installed. exec-prefix prefix 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 supported. ~/amhello-1.0 % ./configure --prefix ~/usr ‘make dist’ Create PACKAGE-VERSION.tar.gz. ~/amhello-1.0 % make ~/amhello-1.0 % make install A. Duret-Lutz Using GNU Autotools May 16, 2010 17 / 162 A. Duret-Lutz Using GNU Autotools May 16, 2010 18 / 162 Package Use Cases The User Point of View Package Use Cases The Power User Point of View Standard Configuration Variables The Power User Point of View ‘./configure’ automatically detects many settings. You can force some of them using configuration variables. 1 Goals Portable Packages CC C compiler command Uniform Builds CFLAGS C compiler flags CXX C++ compiler command 2 Package Use Cases 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 Using GNU Autotools May 16, 2010 19 / 162 A. Duret-Lutz Using GNU Autotools May 16, 2010 20 / 162 Package Use Cases The Power User Point of View Package Use Cases The Power User Point of View 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..