0% found this document useful (0 votes)

48 views556 pages

Auto Tools

Uploaded by

pvt1512

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

48 views556 pages

Auto Tools

Uploaded by

pvt1512

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 556

Foreword

Foreword (1/2)

This presentation targets developers familiar with Unix development tools (shell, make, compiler) that want to learn Autotools. The latest version of this document can be retrieved from
http://www.lrde.epita.fr/~adl/autotools.html

Please mail me corrections and suggestions about this document at [email protected]. Do not send me any general question about the Autotools. Use the appropriate mailing list instead ([email protected], or [email protected]).

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

1 / 162

Tool Versions

Foreword (2/2)
This document was updated for the following releases of the Autotools: GNU GNU GNU GNU Autoconf Automake Libtool Gettext 2.65 1.11.1 2.2.6b 0.17 (November (December (November (November 2009) 2009) 2009) 2007)

These were the last releases at the time of writing. The usage of these tools has improved a lot over the last years. Some syntaxes used here will not work with older tools. This a deliberate choice:
New users should learn todays 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 2 / 162

Title Page

Using GNU Autotools

Alexandre Duret-Lutz [email protected]

May 16, 2010 Copyright c 2010 Alexandre Duret-Lutz http://creativecommons.org/licenses/by-sa/2.0/

Trivial source code examples displayed in this tutorial (such as the C les, Makele.ams, and congure.acs of all the amhello projects) can be reused as if they were in the public domain.
A. Duret-Lutz Using GNU Autotools May 16, 2010 3 / 162

Part I The GNU Build System

Goals Portable Packages Uniform Builds Package Use Cases The User Point of View The Power User Point of View The Packager Point of View The Maintainer Point of View The congure Process Why We Need Tools
A. Duret-Lutz Using GNU Autotools May 16, 2010 4 / 162

3 4

May 16, 2010

7 / 162

Goals

Portable Packages

Possible Solutions

Slice the code with lots of #if/#else Create substitution macros Create substitution functions The latter two are to be preferred.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

7 / 162

Goals

Portable Packages

Code Cluttered with #if/#else

Excerpt of call-1.10s alloc trampoline()
#i f ! d e f i n e d (CODE EXECUTABLE) s t a t i c long pagesize = 0; #i f d e f i n e d (EXECUTABLE VIA MMAP DEVZERO) static int zero fd ; #e n d i f i f (! pagesize ) { #i f d e f i n e d (HAVE MACH VM) pagesize = vm page size ; #e l s e pagesize = getpagesize (); #e n d i f #i f d e f i n e d (EXECUTABLE VIA MMAP DEVZERO) z e r o f d = open ( / d e v / z e r o , O RDONLY, 0 6 4 4 ) ; i f ( z e r o f d < 0) { f p r i n t f ( s t d e r r , t r a m p o l i n e : Cannot open / d e v / z e r o ! \ n ) ; abort ( ) ; } #e n d i f } #e n d i f
A. Duret-Lutz Using GNU Autotools May 16, 2010 8 / 162

Goals

Portable Packages

Substitution macros

Excerpt of coreutils-5.2.1s system.h

#i f ! HAVE FSEEKO && ! d e f i n e d f s e e k o # d e f i n e f s e e k o ( s , o , w) ( ( o ) == ( long ) ( o ) \ ? f s e e k ( s , o , w) \ : ( e r r n o = EOVERFLOW, 1)) #e n d i f Then use fseeko() whether it exists or not.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

9 / 162

12 / 162

Goals

Uniform Builds

congures Purpose

congure

congure probes the systems for required functions, libraries, and tools

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

13 / 162

Goals

Uniform Builds

congures Purpose

congure

cong.h

congure probes the systems for required functions, libraries, and tools then it generates a cong.h le with all #defines

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

13 / 162

Goals

Uniform Builds

congures Purpose

congure

Makele

src/ Makele

cong.h

http://www.gnu.org/prep/standards/ Practices that packages of the GNU project should follow: program behavior
how to report errors, standard command line options, etc.

coding style

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

14 / 162

Goals

Uniform Builds

GNU Coding Standards

http://www.gnu.org/prep/standards/ Practices that packages of the GNU project should follow: program behavior
how to report errors, standard command line options, etc.

coding style conguration

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

14 / 162

Goals

Uniform Builds

GNU Coding Standards

http://www.gnu.org/prep/standards/ Practices that packages of the GNU project should follow: program behavior
how to report errors, standard command line options, etc.

coding style conguration Makele conventions etc.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

Package Use Cases

The User Point of View

Standard Installation Procedure

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

16 / 162

Package Use Cases

The User Point of View

Standard Installation Procedure

~ % tar zxf amhello-1.0.tar.gz ~ % cd amhello-1.0 ~/amhello-1.0 % ./configure ... ~/amhello-1.0 % make ... ~/amhello-1.0 % make check ... ~/amhello-1.0 % su Password: /home/adl/amhello-1.0 # make install ... /home/adl/amhello-1.0 # exit

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

16 / 162

Package Use Cases

The User Point of View

Standard Installation Procedure

Package Use Cases

The User Point of View

Standard Makele Targets

make all Build programs, libraries, documentation, etc. (Same as make.) make install Install what needs to be installed. make install-strip Same as make install, then strip debugging symbols. make uninstall The opposite of make install. make clean Erase what has been built (the opposite of make all). make distclean Additionally erase anything ./configure created. make check Run the test suite, if any. make installcheck Check the installed programs or libraries, if supported. make dist Create PACKAGE-VERSION.tar.gz.
A. Duret-Lutz Using GNU Autotools May 16, 2010 17 / 162

Package Use Cases

The User Point of View

Standard File System Hierarchy

Directory variable prex exec-prex bindir libdir ... includedir datarootdir datadir mandir infodir ... ~/amhello-1.0 % Default value /usr/ local prex exec-prex/bin exec-prex/lib prex/include prex/share datarootdir datarootdir/man datarootdir/info

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

18 / 162

Package Use Cases

Standard Conguration Variables

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

19 / 162

Package Use Cases

The User Point of View

Standard Conguration Variables

./configure automatically detects many settings. You can force some of them using conguration variables. CC C compiler command CFLAGS C compiler ags CXX C++ compiler command CXXFLAGS C++ compiler ags LDFLAGS linker ags CPPFLAGS C/C++ preprocessor ags ... See ./configure --help for a full list. ~/amhello-1.0 % ./configure --prefix ~/usr CC=gcc-3 \ CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib
A. Duret-Lutz Using GNU Autotools May 16, 2010 19 / 162

Package Use Cases

The Power User Point of View

3 4

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

20 / 162

Package Use Cases

The Power User Point of View

Overriding Default Conguration Settings with cong.site

Recall that old command
~/amhello-1.0 % ./configure --prefix ~/usr CC=gcc-3 \ CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

21 / 162

Package Use Cases

The Power User Point of View

Overriding Default Conguration Settings with cong.site

Recall that old command
~/amhello-1.0 % ./configure --prefix ~/usr CC=gcc-3 \ CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib

Common conguration settings can be put in prex/share/ cong.site

~/amhello-1.0 % cat ~/usr/share/config.site test -z "$CC" && CC=gcc-3 test -z "$CPPFLAGS" && CPPFLAGS=-I$HOME/usr/include test -z "$LDFLAGS" && LDFLAGS=-L$HOME/usr/lib

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

21 / 162

Package Use Cases

The Power User Point of View

Overriding Default Conguration Settings with cong.site

Recall that old command
~/amhello-1.0 % ./configure --prefix ~/usr CC=gcc-3 \ CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib

Common conguration settings can be put in prex/share/ cong.site

Using GNU Autotools

May 16, 2010

22 / 162

Package Use Cases

The Power User Point of View

Parallel Build Trees (a.k.a. VPATH Builds)

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

22 / 162

Package Use Cases

The Power User Point of View

Parallel Build Trees for Multiple Architectures

Builds for multiple architectures can share the same source tree.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

23 / 162

Package Use Cases

The Power User Point of View

Parallel Build Trees for Multiple Architectures

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

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

23 / 162

Package Use Cases

The Power User Point of View

Parallel Build Trees for Multiple Architectures

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

Compilation on rst host

~ % mkdir /tmp/amh && cd /tmp/amh /tmp/amh % /nfs/src/amhello-1.0/configure /tmp/amh % make && sudo make install

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

23 / 162

Package Use Cases

The Power User Point of View

Parallel Build Trees for Multiple Architectures

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

Compilation on rst host

~ % mkdir /tmp/amh && cd /tmp/amh /tmp/amh % /nfs/src/amhello-1.0/configure /tmp/amh % make && sudo make install

Compilation on second host

~ % mkdir /tmp/amh && cd /tmp/amh /tmp/amh % /nfs/src/amhello-1.0/configure /tmp/amh % make && sudo make install
A. Duret-Lutz Using GNU Autotools May 16, 2010 23 / 162

Package Use Cases

The Power User Point of View

Parallel Build Trees for Multiple Architectures

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

Compilation on rst host

~ % mkdir /tmp/amh && cd /tmp/amh /tmp/amh % /nfs/src/amhello-1.0/configure /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 Using GNU Autotools May 16, 2010 23 / 162

The Power User Point of View

Cross-Compilation
~/amhello-1.0 % ./configure
checking checking checking checking checking checking checking checking checking checking checking checking checking ... for a BSD-compatible install... /usr/bin/install -c whether build environment is sane... yes for gawk... gawk whether make sets $(MAKE)... yes for gcc... gcc for C compiler default output file name... a.out whether the C compiler works... yes whether we are cross compiling... no for suffix of executables... for suffix of object files... o whether we are using the GNU C compiler... yes whether gcc accepts -g... yes for gcc option to accept ANSI C...

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

25 / 162

Package Use Cases

The Power User Point of View

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

25 / 162

Package Use Cases

The Power User Point of View

Cross-Compilation
~/amhello-1.0 % ./configure --build i686-pc-linux-gnu \ --host i586-mingw32msvc
checking checking checking checking checking checking checking checking checking checking checking checking checking checking ... for a BSD-compatible install... /usr/bin/install -c whether build environment is sane... yes for gawk... gawk whether make sets $(MAKE)... yes for i586-mingw32msvc-strip... i586-mingw32msvc-strip for i586-mingw32msvc-gcc... i586-mingw32msvc-gcc for C compiler default output file name... a.exe whether the C compiler works... yes whether we are cross compiling... yes for suffix of executables... .exe for suffix of object files... o whether we are using the GNU C compiler... yes whether i586-mingw32msvc-gcc accepts -g... yes for i586-mingw32msvc-gcc option to accept ANSI C...
Using GNU Autotools May 16, 2010 25 / 162

A. Duret-Lutz

Package Use Cases

The Power User Point of View

Cross-Compilation
~/amhello-1.0 % ./configure --build i686-pc-linux-gnu \ --host i586-mingw32msvc ... ~/amhello-1.0 % make ...

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

25 / 162

Package Use Cases

The Power User Point of View

Cross-Compilation
~/amhello-1.0 % ./configure --build i686-pc-linux-gnu \ --host i586-mingw32msvc ... ~/amhello-1.0 % make ... ~/amhello-1.0 % cd src; file hello.exe
hello.exe: MS Windows PE 32-bit Intel 80386 console executable not relocatable

Of course you need a cross-compiler installed rst.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

25 / 162

Package Use Cases

The Power User Point of View

Of course you need a cross-compiler installed rst. Cross-compilation congure options: --build=BUILD The system on which the package is built. --host=HOST The system where built programs & libraries will run. --target=TARGET Only when building compiler tools: the system for which the tools will create output. For simple cross-compilation, only --host=HOST is needed.
A. Duret-Lutz Using GNU Autotools May 16, 2010 25 / 162

Package Use Cases

The Power User Point of View

Renaming Programs at Install Time

Maybe hello is already a command on this host?

.
A. Duret-Lutz Using GNU Autotools May 16, 2010 26 / 162

Package Use Cases

The Power User Point of View

Renaming Programs at Install Time

.
A. Duret-Lutz Using GNU Autotools May 16, 2010 26 / 162

Package Use Cases

The Power User Point of View

Renaming Programs at Install Time

~/amhello-1.0 % ./configure --prefix /usr ... checking dependency style of gcc... gcc3 ... Dependency tracking is performed as a side-eect of compilation. Several methods are supported, and checked for by congure. (The gcc3 method above is the fastest.) Dependency tracking is only needed when the source les change; it can be safely disabled for throw-away installation builds. Slow methods must be enabled explicitly. --disable-dependency-tracking speed up one-time builds --enable-dependency-tracking do not reject slow dependency extractors
A. Duret-Lutz Using GNU Autotools May 16, 2010 31 / 162

Package Use Cases

The Maintainer Point of View

Nested Packages

Autoconscated packages can be nested to arbitrary depth.

A package can distribute a third-party library it uses in a subdirectory. Its possible to gather many packages this way to distribute a set of tools.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

32 / 162

Package Use Cases

The Maintainer Point of View

Nested Packages

Autoconscated packages can be nested to arbitrary depth.

A package can distribute a third-party library it uses in a subdirectory. Its possible to gather many packages this way to distribute a set of tools.

For installers:
A single package to congure, build, and install. configure options are passed recursively to sub-packages. configure --help=recursive shows the help of all sub-packages.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

32 / 162

Package Use Cases

The Maintainer Point of View

Nested Packages

Autoconscated packages can be nested to arbitrary depth.

A package can distribute a third-party library it uses in a subdirectory. Its possible to gather many packages this way to distribute a set of tools.

For installers:
A single package to congure, build, and install. configure options are passed recursively to sub-packages. configure --help=recursive shows the help of all sub-packages.

For maintainers:
Easier integration. The sub-package is autonomous.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

32 / 162

The congure Process

3 4

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

33 / 162

The congure Process

The (simplied) congure process

Makele.in

src/ Makele.in

cong.h.in

congure

*.in les are conguration templates

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

34 / 162

The congure Process

The (simplied) congure process

Makele.in

src/ Makele.in

cong.h.in

congure

Makele

src/ Makele

cong.h

*.in les are conguration templates from which congure generates the conguration les to use for building
A. Duret-Lutz Using GNU Autotools May 16, 2010 34 / 162

The congure Process

The (real) congure process

cong.h.in

cong.status cong.log Makele src/ Makele cong.h

cong.status will actually process the templates reconguration

A. Duret-Lutz Using GNU Autotools May 16, 2010 35 / 162

The congure Process

The (real) congure process

Makele.in congure

src/ Makele.in

cong.h.in

cong.status cong.cache Makele cong.log src/ Makele cong.h

configure -C caches results in cong.cache to speed up recongurations

A. Duret-Lutz Using GNU Autotools May 16, 2010 35 / 162

Why We Need Tools

3 4

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

36 / 162

Why We Need Tools

Why We Need Tools

If you try to mimic this build system by hand, youll discover that The GNU Build System has a lot of features. Some users may expect features you do not use. Implementing them portably is dicult, and exhausting. (Think portable shell scripts, portable Makeles, on systems you may not have handy.) You will have to upgrade your setup to follow changes of the GNU Coding Standards. GNU Autotools provide: Tools to create the GNU Build System from simple instructions.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

37 / 162

Why We Need Tools

Part II GNU Autotools

Hello World Introducing Core Autotools Hello World Explained Using Autoconf Using Automake

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

38 / 162

Hello World

Hello World Introducing Core Autotools Hello World Explained Using Autoconf Using Automake

A. Duret-Lutz

Using GNU Autotools

Makele.in congure

src/ Makele.in

cong.h.in

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

41 / 162

Hello World

Generating All Template Files

Makele.in congure

src/ Makele.in

cong.h.in

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

41 / 162

Hello World

Generating All Template Files

congure.ac

autoreconf

Makele.in congure

src/ Makele.in

cong.h.in

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

41 / 162

Hello World

Generating All Template Files

congure.ac

43 / 162

Hello World

Preparing the Package

~/amhello % ls -R .: Makefile.am configure.ac

~/amhello % ./configure checking for a BSD-compatible install... /usr/bin/install -c checking whether build environment is sane... yes checking for gawk... gawk checking whether make sets $(MAKE)... yes checking for gcc... gcc ... checking dependency style of gcc... gcc3 configure: creating ./config.status config.status: creating Makefile config.status: creating src/Makefile config.status: creating config.h config.status: executing depfiles commands ~/amhello %

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

43 / 162

Hello World

Preparing the Package

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

43 / 162

Hello World

Preparing the Package

Hello World

Preparing the Package

~/amhello % src/hello Hello World! This is amhello 1.0. ~/amhello %

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

43 / 162

Hello World

Preparing the Package

~/amhello % src/hello Hello World! This is amhello 1.0. ~/amhello % make distcheck ... ======================================== amhello archives ready for distribution: amhello-1.0.tar.gz ======================================== ~/amhello %

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

43 / 162

Hello World

Preparing the Package

~/amhello % tar ztf amhello-1.0.tar.gz amhello-1.0/ amhello-1.0/Makefile.am amhello-1.0/Makefile.in amhello-1.0/aclocal.m4 amhello-1.0/config.h.in amhello-1.0/configure amhello-1.0/configure.ac amhello-1.0/depcomp amhello-1.0/install-sh amhello-1.0/missing amhello-1.0/src/ amhello-1.0/src/Makefile.am amhello-1.0/src/Makefile.in amhello-1.0/src/main.c ~/amhello %
A. Duret-Lutz Using GNU Autotools May 16, 2010 43 / 162

Introducing Core Autotools

Two Core Packages

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

45 / 162

Introducing Core Autotools

Two Core Packages

Makele.in

src/ Makele.in
May 16, 2010 46 / 162

Using GNU Autotools

Introducing Core Autotools

autoreconf is Your Friend

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

47 / 162

Introducing Core Autotools

autoreconf is Your Friend

In practice, You do not have to remember the interaction of all tools. Use autoreconf --install to setup the package initially. Rely on the rebuild rules (output in Makeles) to rerun the right autotool when you change some input le. You only need a rough idea of the purpose of each tool to understand errors. (What tool complains and about what?) autoconf autoheader automake aclocal Creates congure from congure.ac. Creates cong.h.in from congure.ac. Creates Makele.ins from Makele.ams and congure.ac. Scans congure.ac for uses of third-party macros, and gather denitions in aclocal.m4 . autom4te Autoconf driver for M4. All tools that process congure.ac do so through autom4te.
A. Duret-Lutz Using GNU Autotools May 16, 2010 47 / 162

Hello World Explained

Hello World Introducing Core Autotools Hello World Explained Using Autoconf Using Automake

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

48 / 162

Hello World Explained

amhellos congure.ac explained

congure.ac
AC_INIT([amhello], [1.0], [bug-report@address]) AM_INIT_AUTOMAKE([foreign -Wall -Werror]) AC_PROG_CC AC_CONFIG_HEADERS([config.h]) AC_CONFIG_FILES([Makefile src/Makefile]) AC_OUTPUT

congure.ac
... AM_INIT_AUTOMAKE([foreign -Wall -Werror]) ... ~/amhello % autoreconf --install configure.ac:2: installing ./install-sh configure.ac:2: installing ./missing src/Makefile.am: installing ./depcomp

May 16, 2010

51 / 162

Hello World Explained

amhellos congure.ac explained

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

51 / 162

Hello World Explained

Using GNU Autotools

May 16, 2010

53 / 162

amhellos src/ Makele.am explained

src/ Makele.am
bin_PROGRAMS = hello hello_SOURCES = main.c We are building some programs. These programs will be installed in bindir. There is only one program to build: hello. To create hello, just compile main.c.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

55 / 162

Using Autoconf

Hello World Introducing Core Autotools Hello World Explained Using Autoconf Using Automake

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

56 / 162

Using Autoconf

From congure.ac to congure and cong.h.in

autoconf is a macro processor. It converts congure.ac, which is a shell script using macro instructions, into congure, a full-edged shell script.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

57 / 162

Using Autoconf

From congure.ac to congure and cong.h.in

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

57 / 162

Using Autoconf

From congure.ac to congure and cong.h.in

autoconf is a macro processor. It converts congure.ac, which is a shell script using macro instructions, into congure, a full-edged shell script. Autoconf oers many macros to perform common conguration checks. It is not uncommon to have a congure.ac without shell constructs, using only macros. While processing congure.ac it is also possible to trace the occurrences of macros. This is how autoheader creates cong.h.in. It just looks for the macros that #dene symbols.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

57 / 162

Using Autoconf

From congure.ac to congure and cong.h.in

example.m4
m4_define(NAME1, Harry, Jr.) m4_define(NAME2, Sally) m4_define(MET, $1 met $2) MET(NAME1, NAME2) Can you guess the output of the above?
A. Duret-Lutz Using GNU Autotools May 16, 2010 59 / 162

Using Autoconf

example.m4
m4_define(NAME2, Sally) m4_define(MET, $1 met $2) MET(NAME1, NAME2) Can you guess the output of the above?
A. Duret-Lutz Using GNU Autotools May 16, 2010 59 / 162

Using Autoconf

example.m4
m4_define(NAME2, Sally) m4_define(MET, $1 met $2) MET(NAME1, NAME2) Can you guess the output of the above?
A. Duret-Lutz Using GNU Autotools May 16, 2010 59 / 162

Using Autoconf

example.m4
m4_define(NAME2, Sally) m4_define(MET, $1 met $2) MET(NAME1, NAME2) Can you guess the output of the above?
A. Duret-Lutz Using GNU Autotools May 16, 2010 59 / 162

Using Autoconf

example.m4
m4_define(NAME2, Sally) m4_define(MET, $1 met $2) MET(NAME1, NAME2) Can you guess the output of the above?
A. Duret-Lutz Using GNU Autotools May 16, 2010 59 / 162

Using Autoconf

example.m4

m4_define(MET, $1 met $2) MET(NAME1, NAME2) Can you guess the output of the above?
A. Duret-Lutz Using GNU Autotools May 16, 2010 59 / 162

Using Autoconf

example.m4

m4_define(MET, $1 met $2) MET(NAME1, NAME2) Can you guess the output of the above?
A. Duret-Lutz Using GNU Autotools May 16, 2010 59 / 162

Using Autoconf

example.m4

m4_define(MET, $1 met $2) MET(NAME1, NAME2) Can you guess the output of the above?
A. Duret-Lutz Using GNU Autotools May 16, 2010 59 / 162

Using Autoconf

example.m4

m4_define(MET, $1 met $2) MET(NAME1, NAME2) Can you guess the output of the above?
A. Duret-Lutz Using GNU Autotools May 16, 2010 59 / 162

Using Autoconf

example.m4

m4_define(MET, $1 met $2) MET(NAME1, NAME2) Can you guess the output of the above?
A. Duret-Lutz Using GNU Autotools May 16, 2010 59 / 162

Using Autoconf

example.m4

MET(NAME1, NAME2) Can you guess the output of the above?

A. Duret-Lutz Using GNU Autotools May 16, 2010 59 / 162

Using Autoconf

example.m4

MET(Harry, Jr., NAME2) Can you guess the output of the above?
A. Duret-Lutz Using GNU Autotools May 16, 2010 59 / 162

Using Autoconf

example.m4

MET(Harry, Jr., NAME2) Can you guess the output of the above?
A. Duret-Lutz Using GNU Autotools May 16, 2010 59 / 162

Using Autoconf

example.m4

MET(Harry, Jr., NAME2) Can you guess the output of the above?
A. Duret-Lutz Using GNU Autotools May 16, 2010 59 / 162

Using Autoconf

example.m4

MET(Harry, Jr., NAME2) Can you guess the output of the above?
A. Duret-Lutz Using GNU Autotools May 16, 2010 59 / 162

Using Autoconf

example.m4

MET(Harry, Jr., Sally) Can you guess the output of the above?
A. Duret-Lutz Using GNU Autotools May 16, 2010 59 / 162

Using Autoconf

example.m4

MET(Harry, Jr., Sally) Can you guess the output of the above?
A. Duret-Lutz Using GNU Autotools May 16, 2010 59 / 162

Using Autoconf

example.m4

MET(Harry, Jr., Sally) Can you guess the output of the above?
A. Duret-Lutz Using GNU Autotools May 16, 2010 59 / 162

Using Autoconf

example.m4

Harry met Jr. Can you guess the output of the above?
A. Duret-Lutz Using GNU Autotools May 16, 2010 59 / 162

Using Autoconf

example.m4

Harry met Jr. Can you guess the output of the above?
A. Duret-Lutz Using GNU Autotools May 16, 2010 59 / 162

Using Autoconf

example.m4

Harry met Jr. Can you guess the output of the above?
A. Duret-Lutz Using GNU Autotools May 16, 2010 59 / 162

Using Autoconf

example.m4

Harry met Jr. Can you guess the output of the above?
A. Duret-Lutz Using GNU Autotools May 16, 2010 59 / 162

Using Autoconf

example.m4

Harry met Jr. Can you guess the output of the above?
A. Duret-Lutz Using GNU Autotools May 16, 2010 59 / 162

Using Autoconf

M4 Quoting Rule of the Thumb

Quote each macro argument once.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

60 / 162

Using Autoconf

example.m4

Harry, Jr. met Sally

Spacing Matters
The parenthesis must stick to the macro name. Spaces after or inside quotes are part of the arguments.

example.m4
m4_define(NAME1, Harry, Jr.) m4_define(NAME2, Sally) m4_define(MET, $1 met $2) MET( NAME1 , NAME2) ~ % m4 -P example.m4

Harry, Jr.
A. Duret-Lutz

met Sally
Using GNU Autotools May 16, 2010 61 / 162

Using Autoconf

Spacing Matters
The parenthesis must stick to the macro name. Spaces after or inside quotes are part of the arguments. Spaces before quotes are ignored.

example.m4
m4_define(NAME1, Harry, Jr.) m4_define(NAME2, Sally) m4_define(MET, $1 met $2) MET( NAME1, NAME2) ~ % m4 -P example.m4

Harry, Jr. met Sally

A. Duret-Lutz Using GNU Autotools May 16, 2010 61 / 162

Using Autoconf

Autoconf on Top of M4
Autoconf = M4 with more machinery, and many predened macros.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

62 / 162

May 16, 2010

62 / 162

Using Autoconf

The Structure of a congure.ac

congure.ac
# Prelude. AC_INIT([PACKAGE], [VERSION], [BUG-REPORT-ADDRESS]) # Checks for programs. # # # # # Checks for libraries. Checks for header les. Checks for typedefs, structures, and compiler characteristics. Checks for library functions. Output les.

AC_CONFIG_FILES([FILES]) AC_OUTPUT
A. Duret-Lutz Using GNU Autotools May 16, 2010 63 / 162

Using Autoconf

The Structure of a congure.ac

congure.ac
# Prelude. AC_INIT([amhello], [1.0], [bug-report@address]) # Checks for programs. # # # # # Checks for libraries. Checks for header les. Checks for typedefs, structures, and compiler characteristics. Checks for library functions. Output les.

AC_CONFIG_FILES([FILES]) AC_OUTPUT
A. Duret-Lutz Using GNU Autotools May 16, 2010 63 / 162

Using Autoconf

The Structure of a congure.ac

congure.ac
# Prelude. AC_INIT([amhello], [1.0], [bug-report@address]) AM_INIT_AUTOMAKE([foreign -Wall -Werror]) # Checks for programs. # # # # # Checks for libraries. Checks for header les. Checks for typedefs, structures, and compiler characteristics. Checks for library functions. Output les.

AC_CONFIG_FILES([FILES]) AC_OUTPUT
A. Duret-Lutz Using GNU Autotools May 16, 2010 63 / 162

Using Autoconf

The Structure of a congure.ac

congure.ac
# Prelude. AC_INIT([amhello], [1.0], [bug-report@address]) AM_INIT_AUTOMAKE([foreign -Wall -Werror]) # Checks for programs. AC_PROG_CC # Checks for libraries. # Checks for header les. # Checks for typedefs, structures, and compiler characteristics. # Checks for library functions. # Output les. AC_CONFIG_FILES([FILES]) AC_OUTPUT
A. Duret-Lutz Using GNU Autotools May 16, 2010 63 / 162

Using Autoconf

The Structure of a congure.ac

congure.ac
# Prelude. AC_INIT([amhello], [1.0], [bug-report@address]) AM_INIT_AUTOMAKE([foreign -Wall -Werror]) # Checks for programs. AC_PROG_CC # Checks for libraries. # Checks for header les. # Checks for typedefs, structures, and compiler characteristics. # Checks for library functions. # Output les. AC_CONFIG_FILES([Makefile src/Makefile]) AC_OUTPUT
A. Duret-Lutz Using GNU Autotools May 16, 2010 63 / 162

Using Autoconf

Useful Program Checks

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

67 / 162

Using Autoconf

Useful Program Checks

AC PROG CC, AC PROG CXX, AC PROG F77, ... Compiler checks. (Handle search cross-compilers if needed.) AC PROG SED, AC PROG YACC, AC PROG LEX, ... Find good implementations and set $SED, $YACC, $LEX, etc. AC CHECK PROGS(VAR, PROGS, [VAL-IF-NOT-FOUND]) Dene VAR to the rst PROGS found, or to VAL-IF-NOT-FOUND otherwise. AC_CHECK_PROGS([TAR], [tar gtar], [:]) if test "$TAR" = :; then AC_MSG_ERROR([This package needs tar.]) fi ... and many more
A. Duret-Lutz Using GNU Autotools May 16, 2010 67 / 162

Using Autoconf

Useful Program Checks

Using Autoconf

Useful Autoconf Action Macros

AC MSG ERROR(ERROR-DESCRIPTION, [EXIT-STATUS]) Print ERROR-DESCRIPTION (also to cong.log ) and abort configure. AC MSG WARN(ERROR-DESCRIPTION) Likewise, but dont abort.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

68 / 162

Using Autoconf

Useful Autoconf Action Macros

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

68 / 162

Using Autoconf

Useful Autoconf Action Macros

AC MSG ERROR(ERROR-DESCRIPTION, [EXIT-STATUS]) Print ERROR-DESCRIPTION (also to cong.log ) and abort configure. AC MSG WARN(ERROR-DESCRIPTION) Likewise, but dont abort. AC DEFINE(VARIABLE, VALUE, DESCRIPTION) Output the following to cong.h. /* DESCRIPTION */ #define VARIABLE VALUE AC SUBST(VARIABLE, [VALUE]) Dene $(VARIABLE) as VALUE in Makele. AC_SUBST([FOO], [foo]) All equivalent.
A. Duret-Lutz Using GNU Autotools May 16, 2010 68 / 162

FOO=foo AC_SUBST([FOO])

AC_SUBST([FOO]) FOO=foo

Using Autoconf

Checking for Libraries

AC CHECK LIB(LIBRARY, FUNCT, [ACT-IF-FOUND], [ACT-IF-NOT]) Check whether LIBRARY exists and contains FUNCT. Execute ACT-IF-FOUND if it does, ACT-IF-NOT otherwise.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

69 / 162

Using Autoconf

Checking for Libraries

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

69 / 162

Using Autoconf

Checking for Libraries

AC CHECK LIB(LIBRARY, FUNCT, [ACT-IF-FOUND], [ACT-IF-NOT]) Check whether LIBRARY exists and contains FUNCT. Execute ACT-IF-FOUND if it does, ACT-IF-NOT otherwise. AC_CHECK_LIB([efence], [malloc], [EFENCELIB=-lefence]) AC_SUBST([EFENCELIB]) ... we would later use $(EFENCELIB) in the link rule. If ACT-IF-FOUND is not set and the library is found, AC CHECK LIB will do LIBS="-lLIBRARY $LIBS" and #define HAVE LIBLIBRARY. (Automake uses $LIBS for linking everything.)

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

69 / 162

Using Autoconf

Checking for Headers

script.in
#!/bin/sh SED=@SED@ TAR=@TAR@ d=$1; shift; mkdir "$d" for f; do "$SED" s/#.*// "$f" \ >"$d/$f" done "$TAR" cf "$d.tar" "$d" .in les are templates

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

72 / 162

Using Autoconf

AC CONFIG FILES([script.sh:script.in]) Example

script.in
#!/bin/sh SED=@SED@ TAR=@TAR@ d=$1; shift; mkdir "$d" for f; do "$SED" s/#.*// "$f" \ >"$d/$f" done "$TAR" cf "$d.tar" "$d" .in les are templates where @XYZ@ are placeholders for AC SUBST([XYZ]) denitions.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

72 / 162

Using Autoconf

AC CONFIG FILES([script.sh:script.in]) Example

script.in
#!/bin/sh SED=@SED@ TAR=@TAR@ d=$1; shift; mkdir "$d" for f; do "$SED" s/#.*// "$f" \ >"$d/$f" done "$TAR" cf "$d.tar" "$d"

script.sh
#!/bin/sh SED=/usr/xpg4/bin/sed TAR=/usr/bin/tar d=$1; shift; mkdir "$d" for f; do "$SED" s/#.*// "$f" \ >"$d/$f" done "$TAR" cf "$d.tar" "$d"

.in les are templates where @XYZ@ are placeholders for AC SUBST([XYZ]) denitions. config.status substitutes them.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

72 / 162

Using Autoconf

AC CONFIG FILES([script.sh:script.in]) Example

script.in
#!/bin/sh SED=@SED@ TAR=@TAR@ d=$1; shift; mkdir "$d" for f; do "$SED" s/#.*// "$f" \ >"$d/$f" done "$TAR" cf "$d.tar" "$d"

script.sh
#!/bin/sh SED=/usr/xpg4/bin/sed TAR=/usr/bin/tar d=$1; shift; mkdir "$d" for f; do "$SED" s/#.*// "$f" \ >"$d/$f" done "$TAR" cf "$d.tar" "$d"

74 / 162

Using Automake

AM INIT AUTOMAKE([OPTIONS...]) Check for tools needed by automake-generated Makeles.

A. Duret-Lutz

Using GNU Autotools

Using GNU Autotools

May 16, 2010

78 / 162

Using Automake

where PRIMARY Convention for Declaring Targets

Makele.am
where_PRIMARY = targets ... targets should be built as... PROGRAMS LIBRARIES LTLIBRARIES (Libtool libraries) HEADERS SCRIPTS DATA

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

78 / 162

Using Automake

where PRIMARY Convention for Declaring Targets

where PRIMARY Convention for Declaring Targets

Makele.am
option_where_PRIMARY = targets ... targets should be installed in... bin $(bindir) lib $(libdir) ... custom $(customdir ) You dene customdir. targets should be built as... PROGRAMS LIBRARIES LTLIBRARIES (Libtool libraries) HEADERS SCRIPTS DATA

noinst Not installed. check Built by make check. Optionally:

A. Duret-Lutz

dist Distribute targets (if not the default) nodist Dont.

Using GNU Autotools May 16, 2010 80 / 162

May 16, 2010

81 / 162

Using Automake

(Static) Libraries

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

82 / 162

Using Automake

(Static) Libraries

Add AC PROG RANLIB to congure.ac.

Makele.am
lib_LIBRARIES = libfoo.a libbar.a libfoo_a_SOURCES = foo.c privfoo.h libbar_a_SOURCES = bar.c privbar.h include_HEADERS = foo.h bar.h These libraries will be installed in $(libdir). Library names must match lib*.a. Public headers will be installed in $(includedir).

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

82 / 162

Using Automake

(Static) Libraries

Add AC PROG RANLIB to congure.ac.

A. Duret-Lutz

May 16, 2010

83 / 162

Using Automake

Directory Layout
You may have one Makele (hence one Makele.am) per directory. They must all be declared in congure.ac.

Makele.am
SUBDIRS = lib src

src/ Makele.am
SUBDIRS = dira dirb

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

83 / 162

Using Automake

Directory Layout
You may have one Makele (hence one Makele.am) per directory. They must all be declared in congure.ac.

Makele.am
SUBDIRS = lib src

src/ Makele.am

SUBDIRS = dira dirb The current directory is implicitly built after subdirectories.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

83 / 162

Using Automake

Directory Layout
You may have one Makele (hence one Makele.am) per directory. They must all be declared in congure.ac.

Makele.am
SUBDIRS = lib src

src/ Makele.am

SUBDIRS = dira dirb . The current directory is implicitly built after subdirectories. You can put . where you want to override this.
A. Duret-Lutz Using GNU Autotools May 16, 2010 83 / 162

Using Automake

Directory Layout
You may have one Makele (hence one Makele.am) per directory. They must all be declared in congure.ac.

Makele.am
SUBDIRS = lib src

src/ Makele.am

SUBDIRS = dira . dirb The current directory is implicitly built after subdirectories. You can put . where you want to override this.
A. Duret-Lutz Using GNU Autotools May 16, 2010 83 / 162

Using Automake

Directory Layout
You may have one Makele (hence one Makele.am) per directory. They must all be declared in congure.ac.

Makele.am
SUBDIRS = lib src

src/ Makele.am

SUBDIRS = . dira dirb The current directory is implicitly built after subdirectories. You can put . where you want to override this.
A. Duret-Lutz Using GNU Autotools May 16, 2010 83 / 162

Using Automake

$(srcdir) and VPATH Builds

Remember VPATH builds: a source le is not necessary in the current directory.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

84 / 162

Using Automake

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

86 / 162

Using Automake

Using GNU Autotools

May 16, 2010

87 / 162

Using Automake

Convenience Libraries
lib/ Makele.am
noinst_LIBRARIES = libcompat.a libcompat_a_SOURCES = xalloc.c xalloc.h This is a convenience library, used only when building the package.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

87 / 162

Using Automake

Convenience Libraries
lib/ Makele.am
noinst_LIBRARIES = libcompat.a libcompat_a_SOURCES = xalloc.c xalloc.h This is a convenience library, used only when building the package.

src/ Makele.am
LDADD = ../lib/libcompat.a AM_CPPFLAGS = -I$(srcdir)/../lib bin_PROGRAMS = foo run-me foo_SOURCES = foo.c foo.h print.c print.h run_me_SOURCES = run.c run.h print.c LDADD is added when linking all programs. AM CPPFLAGS contains additional preprocessor ags.
A. Duret-Lutz Using GNU Autotools May 16, 2010 87 / 162

Using Automake

Convenience Libraries
lib/ Makele.am
noinst_LIBRARIES = libcompat.a libcompat_a_SOURCES = xalloc.c xalloc.h This is a convenience library, used only when building the package.

src/ Makele.am
bin_PROGRAMS = foo run-me foo_SOURCES = foo.c foo.h print.c print.h run_me_SOURCES = run.c run.h print.c run_me_LDADD = ../lib/libcompat.a run_me_CPPFLAGS = -I$(srcdir)/../lib LDADD is added when linking all programs. AM CPPFLAGS contains additional preprocessor ags. You can use per-target variables: they apply to a single program.
A. Duret-Lutz Using GNU Autotools May 16, 2010 87 / 162

Using Automake

Per-Target Flags
Assuming foo is a program or library: foo CFLAGS Additional C compiler ags foo CPPFLAGS Additional preprocessor ags (-Is and -Ds)

The default value for foo XXXFLAGS is $(AM XXXFLAGS).

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

88 / 162

Using Automake

Per-Target Flags
Assuming foo is a program or library: foo CFLAGS Additional C compiler ags foo CPPFLAGS Additional preprocessor ags (-Is and -Ds) foo LDADD Additional link objects, -ls and -Ls (if foo is a program) foo LIBADD Additional link objects, -ls and -Ls (if foo is a library) foo LDFLAGS Additional linker ags The default value for foo XXXFLAGS is $(AM XXXFLAGS).

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

88 / 162

Using Automake

src/ Makele.am
bin_PROGRAMS = foo run-me foo_SOURCES = foo.c foo.h print.c print.h run_me_SOURCES = run.c run.h print.c run_me_CPPFLAGS = -I$(srcdir)/../lib run_me_LDADD = ../lib/libcompat.a
A. Duret-Lutz Using GNU Autotools May 16, 2010 88 / 162

Using Automake

Checking for Libraries

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

89 / 162

Using Automake

src/ Makele.am
bin_PROGRAMS = foo run-me foo_SOURCES = foo.c foo.h print.c print.h run_me_SOURCES = run.c run.h print.c run_me_CPPFLAGS = -I$(srcdir)/../lib run_me_LDADD = ../lib/libcompat.a $(EFENCELIB)
A. Duret-Lutz Using GNU Autotools May 16, 2010 90 / 162

Using Automake

What Gets Distributed

make dist and make distcheck create a tarball containing: All sources declared using ... SOURCES All headers declared using ... HEADERS

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

91 / 162

Using Automake

What Gets Distributed

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

91 / 162

Using Automake

What Gets Distributed

make dist and make distcheck create a tarball containing: All sources declared using ... SOURCES All headers declared using ... HEADERS All scripts declared with dist ... SCRIPTS All data les declared with dist ... DATA ... Common les such as ChangeLog , NEWS, etc. See automake --help for a list of those les.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

91 / 162

Using Automake

What Gets Distributed

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

91 / 162

Using Automake

What Gets Distributed

Makele.am
SUBDIRS = lib src EXTRA_DIST = HACKING ... will additionally distribute HACKING .
A. Duret-Lutz Using GNU Autotools May 16, 2010 91 / 162

Using Automake

Conditionals: Usage
Conditionals allow for conditional builds and unconditional distribution.

A. Duret-Lutz

May 16, 2010

92 / 162

Using Automake

Conditionals: Usage
Conditionals allow for conditional builds and unconditional distribution.

Conditional Programs

bin_PROGRAMS = foo bin_PROGRAMS = foo if WANT_BAR foo_SOURCES = foo.c bin_PROGRAMS += bar if WANT_BAR endif foo_SOURCES += bar.c foo_SOURCES = foo.c endif bar_SOURCES = bar.c bar is built i WANT BAR is true. bar.o is linked in foo i WANT BAR is true. In all cases foo.c and bar.c are distributed regardless of WANT BAR. This is portable. config.status will comment rules of Makele.in that must be disabled.
A. Duret-Lutz Using GNU Autotools May 16, 2010 92 / 162

Conditional Sources

Using Automake

Conditionals: Usage
Conditionals allow for conditional builds and unconditional distribution.

Conditional Programs

bin_PROGRAMS = foo bin_PROGRAMS = foo if WANT_BAR foo_SOURCES = foo.c bin_PROGRAMS += bar if WANT_BAR endif foo_SOURCES += bar.c foo_SOURCES = foo.c endif bar_SOURCES = bar.c bar is built i WANT BAR is true. bar.o is linked in foo i WANT BAR is true. In all cases foo.c and bar.c are distributed regardless of WANT BAR. This is portable. config.status will comment rules of Makele.in that must be disabled. WANT BAR must be declared and valued in congure.ac.
A. Duret-Lutz Using GNU Autotools May 16, 2010 92 / 162

Conditional Sources

Using Automake

Conditionals: Declaration

AM CONDITIONAL(NAME, CONDITION) Declare conditional NAME. CONDITION should be a shell instruction that succeeds i NAME should be enabled.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

93 / 162

Using Automake

Conditionals: Declaration

AM CONDITIONAL(NAME, CONDITION) Declare conditional NAME. CONDITION should be a shell instruction that succeeds i NAME should be enabled.

congure.ac
AC_CHECK_HEADER([bar.h], [use_bar=yes]) AM_CONDITIONAL([WANT_BAR], [test "$use_bar" = yes]) Will enable WANT BAR only if bar.h is present on the system.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

93 / 162

Using Automake

Extending Automake Rules

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

94 / 162

Using Automake

Extending Automake Rules

The contents of Makele.am are copied almost verbatim to Makele.in. automake adds new rules and variables in Makele.in, to achieve the semantics of the special variables you have dened. Some minor rewriting is done to handle constructs like conditionals or += portably. Its OK to dene your own rules in Makele.am.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

94 / 162

Using Automake

Extending Automake Rules

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

94 / 162

Using Automake

Extending Automake Rules

Its OK to dene variables that are meaningless to Automake.

For use in custom rules.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

94 / 162

Using Automake

Extending Automake Rules

Its OK to dene variables that are meaningless to Automake.

For use in custom rules.

Beware of conicts: your denitions (of variables or rules) will override those of Automake.
-Wall will diagnose these.
A. Duret-Lutz Using GNU Autotools May 16, 2010 94 / 162

Using Automake

Recommendations

Use -Wall -Werror.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

95 / 162

Using Automake

Recommendations

Use -Wall -Werror. Keep Your Setup Simple (KYSS!).

You will spend a large part of time debugging your cunning tricks if you try to automatize too much.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

95 / 162

Using Automake

Recommendations

96 / 162

Using Automake

Lost? autoreconf is Still Your Friend

If make fails to rebuild conguration les, run autoreconf manually. ~/amhello % autoreconf --install If this does not help, try harder. ~/amhello % autoreconf --install --force If this still does not help, try even harder. ~/amhello % make -k maintainer-clean ~/amhello % autoreconf --install --force Do this only when necessary. Each of these commands will cause your package to take longer to recongure and recompile.
A. Duret-Lutz Using GNU Autotools May 16, 2010 96 / 162

Part III More Autotools

Writing and Managing Custom Macros Writing Autoconf Macros Managing Custom Macros with aclocal Libtool Gettext Introducing Gettext Internationalizing a Package, Start to Finish Localizing a Package Nested Packages The End
A. Duret-Lutz Using GNU Autotools May 16, 2010 97 / 162

11 12

13 14

Writing Autoconf Macros

Writing an Autoconf Macro? Why? How?

Two fundamentally dierent types of new macros: Macros that factor related tests in a single reusable entity.
High-level. Combination of existing lower-level macros. May not use shell code at all.

Writing Autoconf Macros

mkdir() Example
POSIX systems dene mkdir() with two arguments. On Mingw32 (at least), mkdir() takes only one argument. On Win32 (at least), the name is mkdir() with one argument. #if HAVE_MKDIR # if MKDIR_ONE_ARG # define mkdir(a,b) mkdir(a) # endif #else # if HAVE__MKDIR # define mkdir(a,b) _mkdir(a) # else # error "Dont know how to create a directory." # endif #endif
A. Duret-Lutz Using GNU Autotools May 16, 2010 101 / 162

Writing and Managing Custom Macros

Writing Autoconf Macros

mkdir() Example
POSIX systems dene mkdir() with two arguments. On Mingw32 (at least), mkdir() takes only one argument. On Win32 (at least), the name is mkdir() with one argument. #if HAVE_MKDIR # if MKDIR_ONE_ARG # define mkdir(a,b) mkdir(a) # endif #else # if HAVE__MKDIR # define mkdir(a,b) _mkdir(a) # else # error "Dont know how to create a directory." # endif #endif Lets write an Autoconf macro to dene these C macros.
A. Duret-Lutz Using GNU Autotools May 16, 2010 101 / 162

Writing and Managing Custom Macros

Writing Autoconf Macros

Writing a High-Level Macro: AX FUNC MKDIR

AC_DEFUN([AX_FUNC_MKDIR], [AC_CHECK_FUNCS([mkdir _mkdir]) AC_CHECK_HEADERS([io.h]) AX_FUNC_MKDIR_ONE_ARG ])

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

102 / 162

Writing and Managing Custom Macros

Writing and Managing Custom Macros

Writing Autoconf Macros

Writing a High-Level Macro: AX FUNC MKDIR

AC_DEFUN([AX_FUNC_MKDIR], [AC_CHECK_FUNCS([mkdir _mkdir]) AC_CHECK_HEADERS([io.h]) AX_FUNC_MKDIR_ONE_ARG ]) Suggested name space for extension macros. Use same convention as Autoconf for categorizing macros. Denes HAVE MKDIR and HAVE MKDIR. Denes HAVE IO H if io.h exists. (mkdir() may also be dened there, and sys/ stat.h and unistd.h are always tested by AC PROG CC)

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

102 / 162

Writing and Managing Custom Macros

Writing Autoconf Macros

Writing a High-Level Macro: AX FUNC MKDIR

Writing and Managing Custom Macros

Writing Autoconf Macros

Checking mkdir()s number of arguments

Writing a Low-Level Macro

Low-level macros need to print a checking whether... message do the actual check cache the result of the check Most of this is achieved via the AC CACHE CHECK macro. AC_DEFUN(MACRO-NAME, [AC_CACHE_CHECK(WHETHER-MESSAGE, CACHE-VARIABLE, CODE-TO-SET-CACHE-VARIABLE) CODE-USING-CACHE-VARIABLE]) The CACHE-VARIABLE should match * cv *. CODE-TO-SET-CACHE-VARIABLE should contain the check. It will be skipped when the cache is used.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

106 / 162

Writing and Managing Custom Macros

Writing Autoconf Macros

Writing a Low-Level Macro

Writing and Managing Custom Macros

Writing Autoconf Macros

A Low-Level Macro: AX FUNC MKDIR ONE ARG

AC_DEFUN([AX_FUNC_MKDIR_ONE_ARG], [AC_CACHE_CHECK([whether mkdir takes one argument], [ax_cv_mkdir_one_arg], [_AX_FUNC_MKDIR_ONE_ARG([ax_cv_mkdir_one_arg=yes], [ax_cv_mkdir_one_arg=no])]) if test x"$ax_cv_mkdir_one_arg" = xyes; then AC_DEFINE([MKDIR_ONE_ARG], 1, [Define if mkdir takes only one argument.]) fi]) # AX_FUNC_MKDIR_ONE_ARG

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

107 / 162

Writing and Managing Custom Macros

Writing Autoconf Macros

A Low-Level Macro: AX FUNC MKDIR ONE ARG

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

107 / 162

Writing and Managing Custom Macros

Writing Autoconf Macros

A Low-Level Macro: AX FUNC MKDIR ONE ARG

Keep conguration actions outside AC CACHE CHECK: they have to be executed whether the check is run or cached.
A. Duret-Lutz Using GNU Autotools May 16, 2010 107 / 162

Writing and Managing Custom Macros

Writing Autoconf Macros

Recommendations for Writing Autoconf Macros

Test for features, not for systems.
E.g., check whether mkdir() takes one argument, not whether you are compiling for Win32. Your package will be more likely to adapt to untested systems.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

108 / 162

Writing and Managing Custom Macros

Writing Autoconf Macros

Recommendations for Writing Autoconf Macros

Test for features, not for systems.
E.g., check whether mkdir() takes one argument, not whether you are compiling for Win32. Your package will be more likely to adapt to untested systems.

Avoid writing tests that are conditional on previous tests.

Have unconditional tests, with conditional actions. E.g., check for mkdir() even if mkdir() exists.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

108 / 162

Writing and Managing Custom Macros

Writing Autoconf Macros

Recommendations for Writing Autoconf Macros

Test for features, not for systems.
E.g., check whether mkdir() takes one argument, not whether you are compiling for Win32. Your package will be more likely to adapt to untested systems.

Avoid writing tests that are conditional on previous tests.

Have unconditional tests, with conditional actions. E.g., check for mkdir() even if mkdir() exists.

Do not reinvent the wheel.

Autoconf comes with a lot of well-tested macros. Use them.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

108 / 162

Writing and Managing Custom Macros

Writing Autoconf Macros

Recommendations for Writing Autoconf Macros

Test for features, not for systems.
E.g., check whether mkdir() takes one argument, not whether you are compiling for Win32. Your package will be more likely to adapt to untested systems.

Avoid writing tests that are conditional on previous tests.

Have unconditional tests, with conditional actions. E.g., check for mkdir() even if mkdir() exists.

Do not reinvent the wheel.

Autoconf comes with a lot of well-tested macros. Use them.

Remember to [quote]. Read the Portable Shell section of the Autoconf manual, before writing shell code.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

108 / 162

Writing and Managing Custom Macros

Writing Autoconf Macros

Recommendations for Writing Autoconf Macros

Test for features, not for systems.
E.g., check whether mkdir() takes one argument, not whether you are compiling for Win32. Your package will be more likely to adapt to untested systems.

Avoid writing tests that are conditional on previous tests.

Have unconditional tests, with conditional actions. E.g., check for mkdir() even if mkdir() exists.

Do not reinvent the wheel.

Autoconf comes with a lot of well-tested macros. Use them.

Remember to [quote]. Read the Portable Shell section of the Autoconf manual, before writing shell code. Test your macros on dierent systems.
Check test results in cong.log . Get accounts on foreign systems (Google for free shell account).
A. Duret-Lutz Using GNU Autotools May 16, 2010 108 / 162

Writing and Managing Custom Macros

Managing Custom Macros with aclocal

11 12

13 14

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

109 / 162

Writing and Managing Custom Macros

Writing and Managing Custom Macros

Managing Custom Macros with aclocal

Behind autoreconf
congure.ac aclocal.m4 Makele.am src/ Makele.am

aclocal automake autoheader autoconf

congure
A. Duret-Lutz

cong.h.in

Makele.in

src/ Makele.in
May 16, 2010 111 / 162

Using GNU Autotools

Writing and Managing Custom Macros

Managing Custom Macros with aclocal

aclocal.m4 and Third-Party Macros

autoconf knows only the macros it provides. (m4 *, AS *, AH *, AC *, AT *). autoconf knows nothing about macro supplied by third-party tools (e.g., Automakes AM * macros). autoconf reads aclocal.m4 in addition to congure.ac. aclocal.m4 should dene the extra macros required by congure.ac. aclocal automates the construction of aclocal.m4 from various sources. aclocal searches macros in directories specied with -I options a system-wide directory (usually /usr/ share/ aclocal/ ) where third-party packages may install their macros Automakes own private macro directory
A. Duret-Lutz Using GNU Autotools May 16, 2010 112 / 162

Writing and Managing Custom Macros

Managing Custom Macros with aclocal

Managing Custom Macros in Your Package

Create a m4/ subdirectory. Put your macros there. E.g., dene AX FUNC MKDIR and AX FUNC MKDIR ONE ARG in m4/ mkdir.m4 . (The extension must be *.m4 )

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

113 / 162

Writing and Managing Custom Macros

Managing Custom Macros with aclocal

Managing Custom Macros in Your Package

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

113 / 162

Writing and Managing Custom Macros

Managing Custom Macros with aclocal

Managing Custom Macros in Your Package

Create a m4/ subdirectory. Put your macros there. E.g., dene AX FUNC MKDIR and AX FUNC MKDIR ONE ARG in m4/ mkdir.m4 . (The extension must be *.m4 ) Add ACLOCAL AMFLAGS = -I m4 to the top-level Makele.am. Add AC CONFIG MACRO DIR([m4]) to congure.ac. Use your macros in congure.ac. The ACLOCAL AMFLAGS are used by autoreconf and by the Makele rebuild rule when they need to run aclocal. Local macros that are used are automatically distributed. (Those that are not used are simply ignored.)

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

113 / 162

Writing and Managing Custom Macros

Managing Custom Macros with aclocal

Managing Custom Macros in Your Package

Libtool

Libtool
10

11 12

13 14

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

114 / 162

Libtool

Shared Libraries: A Portability Hell

Almost each system has its own format of shared library
libhello.so libhello.dll libhello.sl libhello.dylib ...

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

115 / 162

Libtool

Shared Libraries: A Portability Hell

Almost each system has its own format of shared library
libhello.so libhello.dll libhello.sl libhello.dylib ...

Building will require dierent ags

Linking against the library may also require specic ags. There is no way for a developer to keep track of all these details.
Quiz: match each of the above example with its OS.

Not all systems support shared libraries.

A. Duret-Lutz Using GNU Autotools May 16, 2010 115 / 162

Libtool

Shared Libraries: Libtools Solution

A new library format that abstracts all the others

libhello.la (libtool archive)

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

116 / 162

Libtool

Shared Libraries: Libtools Solution

A new library format that abstracts all the others

libhello.la (libtool archive)

A wrapper script for the compiler and linker

translates operations involving libhello.la into the correct operation for the current system using the real library

117 / 162

Libtool

Setting Up Libtool: Roadmap

Libtool will require some local Autoconf macros for all the checks it has to perform. Use an m4/ subdirectory as explained earlier. Call LT INIT in congure.ac. Use LTLIBRARIES to declare libtool archives in Makele.am

Makele.am
lib_LTLIBRARIES = libfoo.la libfoo_la_SOURCES = foo.c foo.h etc.c

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

117 / 162

Libtool

Setting Up Libtool: Roadmap

Makele.am
lib_LTLIBRARIES = libfoo.la libfoo_la_SOURCES = foo.c foo.h etc.c bin_PROGRAMS = runme runme_SOURCES = main.c runme_LDADD = libfoo.la
A. Duret-Lutz Using GNU Autotools May 16, 2010 117 / 162

Libtool

Hello World Using Libtool: C Files

lib/ say.c
#include <config.h> #include <stdio.h> void say_hello (void) { puts ("Hello World!"); puts ("This is " PACKAGE_STRING "."); }

src/ main.c
#include "say.h" int main (void) { say_hello (); return 0; }

lib/ say.h
void say_hello (void);

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

118 / 162

Libtool

Hello World Using Libtool: Makele.ams

lib/ Makele.am
lib_LTLIBRARIES = libhello.la libhello_la_SOURCES = say.c say.h

src/ Makele.am
AM_CPPFLAGS = -I$(srcdir)/../lib bin_PROGRAMS = hello hello_SOURCES = main.c hello_LDADD = ../lib/libhello.la

Makele.am
SUBDIRS = lib src ACLOCAL_AMFLAGS = -I m4
A. Duret-Lutz Using GNU Autotools May 16, 2010 119 / 162

Libtool

Hello World Using Libtool: congure.ac

congure.ac
AC_INIT([amhello], [2.0], [bug-report@address]) AC_CONFIG_AUX_DIR([build-aux]) AC_CONFIG_MACRO_DIR([m4]) AM_INIT_AUTOMAKE([foreign -Wall -Werror]) LT_INIT AC_PROG_CC AC_CONFIG_HEADERS([config.h]) AC_CONFIG_FILES([Makefile lib/Makefile src/Makefile]) AC_OUTPUT

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

120 / 162

Libtool

Hello World Using Libtool: autoreconf

~/amhello % ls -R

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

121 / 162

Libtool

Hello World Using Libtool: autoreconf

~/amhello % ls -R .: Makefile.am configure.ac ./lib: Makefile.am ./src: Makefile.am

lib/

src/

say.c

say.h

May 16, 2010

121 / 162

Libtool

Hello World Using Libtool: autoreconf

~/amhello ~/amhello ... ~/amhello ... ~/amhello ... ~/amhello

% mkdir m4 % autoreconf --install % ./configure --prefix ~/test % make && make install %

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

121 / 162

Libtool

Hello World Using Libtool: autoreconf

~/amhello % mkdir m4 ~/amhello % autoreconf --install ... ~/amhello % ./configure --prefix ~/test ... ~/amhello % make && make install ... ~/amhello % ~/test/bin/hello Hello World! This is amhello 2.0. ~/amhello %

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

121 / 162

Libtool

What Was Built and Installed

~/amhello % ls -R ~/test /home/adl/test: bin/ lib/ /home/adl/test/bin: hello* /home/adl/test/lib: libhello.a libhello.so@ libhello.la* libhello.so.0@ ~/amhello %

libhello.so.0.0.0*

By default, both static and shared libraries are built. This default can be changed in a package using options passed to LT INIT(options...): disable-shared do not build shared libraries by default disable-static do not build static libraries by default The installer can override these settings using congure options. --enable-shared build shared libraries --disable-shared dont --enable-static build static libraries --disable-static dont

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

123 / 162

Libtool

Building Shared or Static Libraries

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

123 / 162

Libtool

The src/ hello Wrapper Script

src/ hello can be a wrapper script
Depending on Libtools conguration.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

124 / 162

Libtool

The src/ hello Wrapper Script

src/ hello can be a wrapper script
Depending on Libtools conguration.

The real binary has been built elsewhere

Libtool hides it in the build tree (dont bother about it)

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

124 / 162

Libtool

The src/ hello Wrapper Script

src/ hello can be a wrapper script
Depending on Libtools conguration.

The real binary has been built elsewhere

Libtool hides it in the build tree (dont bother about it)

This wrapper script runs the real binary, and arranges so it nds the not-yet-installed libraries
This way src/ hello can be run, for instance in a test suite

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

124 / 162

Libtool

The src/ hello Wrapper Script

src/ hello can be a wrapper script
Depending on Libtools conguration.

The real binary has been built elsewhere

Libtool hides it in the build tree (dont bother about it)

This wrapper script runs the real binary, and arranges so it nds the not-yet-installed libraries
This way src/ hello can be run, for instance in a test suite

Do not debug the shell script!

~/amhello % gdb -q src/hello
"src/hello": not in executable format: File format not recognized

(gdb)

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

124 / 162

Libtool

The src/ hello Wrapper Script

src/ hello can be a wrapper script
Depending on Libtools conguration.

The real binary has been built elsewhere

Libtool hides it in the build tree (dont bother about it)

This wrapper script runs the real binary, and arranges so it nds the not-yet-installed libraries
This way src/ hello can be run, for instance in a test suite

Do not debug the shell script!

~/amhello % gdb -q src/hello
"src/hello": not in executable format: File format not recognized

(gdb)

Prex such commands with libtool --mode=execute

~/amhello % libtool --mode=execute gdb -q src/hello
A. Duret-Lutz Using GNU Autotools May 16, 2010 124 / 162

Libtool

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

127 / 162

129 / 162

#include <config.h> #include <stdio.h>

void say_hello (void) { puts ("Hello World!"); puts ("This is " PACKAGE_STRING "."); } The program is written in English.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

130 / 162

Gettext

Introducing Gettext

Translating Messages Made Easy

#include <config.h> #include <stdio.h> #include "gettext.h" #define _(string) gettext (string) void say_hello (void) { puts (_("Hello World!")); printf (_("This is %s.\n"), PACKAGE_STRING); } The program is written in English. Messages that must be translated are marked with (...).
xgettext builds catalogs of translatable messages from such strings. Translators will provide translated catalogs for their locale.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

130 / 162

Gettext

Introducing Gettext

Translating Messages Made Easy

gettext looks up the translation of the English message in the current locales catalog.
A. Duret-Lutz Using GNU Autotools May 16, 2010 130 / 162

Gettext

Internationalizing a Package, Start to Finish

11 12

13 14

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

131 / 162

Gettext

Internationalizing a Package, Start to Finish

Roadmap:
1 2 3 4 5 6

Start with a non-internationalized Hello World. Invoke AM GNU GETTEXT from congure.ac Run gettextize to provide the basic infrastructure. Fill in the conguration les left by gettextize. Update src/ Makele.am to link hello with the necessary library. Update the code:
Initialize Gettext in main() Mark translatable strings.

Generate messages catalogs automatically.

Well talk about localization once this is done.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

132 / 162

Gettext

Internationalizing a Package, Start to Finish

Non Internationalized Hello World (1/2)

src/ say.h
#ifndef AMHELLO_SAY_H # define AMHELLO_SAY_H void say_hello (void); #endif

src/ main.c
#include "say.h" int main (void) { say_hello (); return 0; }

src/ say.c
#include <config.h> #include <stdio.h> void say_hello (void) { puts ("Hello World!"); puts ("This is " PACKAGE_STRING "."); }
Using GNU Autotools May 16, 2010 133 / 162

A. Duret-Lutz

Gettext

Internationalizing a Package, Start to Finish

Non Internationalized Hello World (2/2)

congure.ac
AC_INIT([amhello], [3.0], [bug-report@address]) AC_CONFIG_AUX_DIR([build-aux]) AM_INIT_AUTOMAKE([foreign -Wall -Werror]) AC_PROG_CC AC_CONFIG_HEADERS([config.h]) AC_CONFIG_FILES([Makefile src/Makefile]) AC_OUTPUT

Makele.am
SUBDIRS = src

src/ Makele.am
bin_PROGRAMS = hello hello_SOURCES = main.c say.c say.h

congure.ac
AC_INIT([amhello], [3.0], [bug-report@address]) AC_CONFIG_AUX_DIR([build-aux]) AM_INIT_AUTOMAKE([foreign -Wall -Werror]) AM_GNU_GETTEXT_VERSION([0.17]) AM_GNU_GETTEXT([external]) AC_PROG_CC AC_CONFIG_HEADERS([config.h]) AC_CONFIG_FILES([Makefile src/Makefile]) AC_OUTPUT AM GNU GETTEXT VERSION = exactly which Gettext version to use. AM GNU GETTEXT([external])
the GNU libc or an external (= not distributed) Gettext library will be used if found NLS (Native Language System) will be disabled otherwise
A. Duret-Lutz Using GNU Autotools May 16, 2010 135 / 162

Gettext

Internationalizing a Package, Start to Finish

Running gettextize

You should run gettextize: A rst time, to install the Gettext infrastructure in your package. Each time you upgrade Gettext to a new version. ~/amhello %

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

136 / 162

Gettext

Internationalizing a Package, Start to Finish

Running gettextize

You should run gettextize: A rst time, to install the Gettext infrastructure in your package. Each time you upgrade Gettext to a new version. ~/amhello % gettextize --copy --no-changelog [...] ~/amhello % Install most of the Gettext infrastructure.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

136 / 162

Gettext

Internationalizing a Package, Start to Finish

Running gettextize

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

136 / 162

Gettext

Internationalizing a Package, Start to Finish

Gettextize Updated Some Files

congure.ac
AC_INIT([amhello], [3.0], [bug-report@address]) AC_CONFIG_AUX_DIR([build-aux]) AM_GNU_GETTEXT_VERSION([0.17]) AM_GNU_GETTEXT([external]) AM_INIT_AUTOMAKE([foreign -Wall -Werror]) AC_PROG_CC AC_CONFIG_HEADERS([config.h]) AC_CONFIG_FILES([Makefile src/Makefile po/Makefile.in]) AC_OUTPUT

Makele.am

SUBDIRS = po src bin_PROGRAMS = hello ACLOCAL_AMFLAGS = -I m4 hello_SOURCES = main.c say.c say.h EXTRA_DIST = ...
A. Duret-Lutz Using GNU Autotools May 16, 2010 137 / 162

src/ Makele.am

Gettext

Internationalizing a Package, Start to Finish

po/ Makevars and po/ POTFILES.in

Fill po/ Makevars.template and rename it as po/ Makevars:

po/ Makevars
DOMAIN = $(PACKAGE) subdir = po top_builddir = .. XGETTEXT_OPTIONS = --keyword=_ --keyword=N_ COPYRIGHT_HOLDER = Your Name or Your Employer MSGID_BUGS_ADDRESS = $(PACKAGE BUGREPORT) EXTRA_LOCALE_CATEGORIES =

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

138 / 162

Gettext

Internationalizing a Package, Start to Finish

po/ Makevars and po/ POTFILES.in

Fill po/ Makevars.template and rename it as po/ Makevars: $(PACKAGE BUGREPORT) is the po/ Makevars third argument of AC INIT. Some DOMAIN = $(PACKAGE) packages use a mailing list subdir = po dedicated to translation issues top_builddir = .. instead. XGETTEXT_OPTIONS = --keyword=_ --keyword=N_ COPYRIGHT_HOLDER = Your Name or Your Employer MSGID_BUGS_ADDRESS = $(PACKAGE BUGREPORT) EXTRA_LOCALE_CATEGORIES =

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

138 / 162

Gettext

Internationalizing a Package, Start to Finish

po/ Makevars and po/ POTFILES.in

Fill po/ Makevars.template and rename it as po/ Makevars:

po/ POTFILES.in
src/main.c src/say.c
A. Duret-Lutz Using GNU Autotools May 16, 2010 138 / 162

Gettext

Internationalizing a Package, Start to Finish

Whats Next?
Done:
1 2 3 4

Start with a non-internationalized Hello World. Invoke AM GNU GETTEXT from congure.ac Run gettextize to provide the basic infrastructure. Fill in the conguration les left by gettextize.

Now, autoreconf --install; ./configure; make should work.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

139 / 162

Gettext

Internationalizing a Package, Start to Finish

Whats Next?
Done:
1 2 3 4

Start with a non-internationalized Hello World. Invoke AM GNU GETTEXT from congure.ac Run gettextize to provide the basic infrastructure. Fill in the conguration les left by gettextize.

Now, autoreconf --install; ./configure; make should work. To do:

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

140 / 162

Gettext

Internationalizing a Package, Start to Finish

Initializing Gettext
src/ main.c

#include "say.h" int main (void) {

say_hello(); return 0; }
A. Duret-Lutz Using GNU Autotools May 16, 2010 141 / 162

Gettext

Internationalizing a Package, Start to Finish

Initializing Gettext
src/ main.c
#include <locale.h> #include "say.h" int main (void) { setlocale (LC_ALL, ""); Initialize the locale as specied in the environment. (E.g., the user sets LANG=fr FR in the environment to get French messages.)

say_hello(); return 0; }
A. Duret-Lutz Using GNU Autotools May 16, 2010 141 / 162

Gettext

Internationalizing a Package, Start to Finish

Initializing Gettext
src/ main.c
#include <config.h> #include <locale.h> #include "gettext.h" #include "say.h" int main (void) { setlocale (LC_ALL, ""); bindtextdomain (PACKAGE, LOCALEDIR); textdomain (PACKAGE); say_hello(); return 0; }
A. Duret-Lutz Using GNU Autotools

Initialize the locale as specied in the environment. (E.g., the user sets LANG=fr FR in the environment to get French messages.) Tell Gettext where to nd message catalogs for this program. (All programs in the same package usually share the same message catalog.)
May 16, 2010 141 / 162

Gettext

Internationalizing a Package, Start to Finish

Marking Strings for Translation

src/ say.c
#include <config.h> #include <stdio.h>

void say_hello (void) { puts ("Hello World!"); puts ("This is " PACKAGE_STRING "."); }

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

142 / 162

Gettext

Internationalizing a Package, Start to Finish

Marking Strings for Translation

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

142 / 162

Gettext

Internationalizing a Package, Start to Finish

Marking Strings for Translation

src/ say.c
#include <config.h> #include <stdio.h> #include "gettext.h" #define _(string) gettext (string) void say_hello (void) { puts (_("Hello World!")); printf (_("This is %s.\n"), PACKAGE_STRING); } Messages that must be translated are marked with (...). NLS (Native Language System) can be disabled.
Explicitly with ./configure --disable-nls Implicitly if no gettext implementation is installed.

Then gettext.h denes gettext(), textdomain(), . . . , as no-ops.

A. Duret-Lutz Using GNU Autotools May 16, 2010 142 / 162

Gettext

Internationalizing a Package, Start to Finish

Building the Whole Shebang

Our Hello World is now internationalized. ~/amhello % autoreconf --install ... ~/amhello % ./configure ... ~/amhello % make ...

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

143 / 162

Gettext

Internationalizing a Package, Start to Finish

Building the Whole Shebang

Our Hello World is now internationalized. ~/amhello % autoreconf --install ... ~/amhello % ./configure ... ~/amhello % make ... Making all in po make amhello.pot-update ... The po/ directory contains messages catalogs. po/ amhello.pot is the template message catalog. Updating po/ amhello.pot is costly and occurs only before releases (e.g., during make distcheck) or if the le did not exist (our case above). It can be updated explicitly with cd po; make update-po.
A. Duret-Lutz Using GNU Autotools May 16, 2010 143 / 162

Gettext

Localizing a Package

Localizing a Package
10

11 12

13 14

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

144 / 162

Gettext

Localizing a Package

po/ amhello.pot: The PO Template File

# ... COMMENTS ... #, fuzzy msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" "Report-Msgid-Bugs-To: bug-report@address\n" "POT-Creation-Date: 2005-03-05 00:27+0100\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" "Language-Team: LANGUAGE <[email protected]>\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=CHARSET\n" "Content-Transfer-Encoding: 8bit\n" #: src/say.c:9 msgid "Hello World!" msgstr "" #: src/say.c:10 #, c-format msgid "This is %s.\n" msgstr ""
A. Duret-Lutz Using GNU Autotools May 16, 2010 145 / 162

Gettext

Localizing a Package

po/ amhello.pot: The PO Template File

po/ amhello.pot: The PO Template File

Gettext

Localizing a Package

150 / 162

Gettext

Localizing a Package

Preparing po/ fr.po

~/amhello % cd po ~/amhello/po % msginit -l fr ... ~/amhello/po % emacs fr.po & The PO mode of emacs (
M-x

po-mode):

The buer is modied only indirectly.

Enter

on a message will open a buer to edit the translation.

Localizing a Package

po/ fr.po: Header

A. Duret-Lutz

Localizing a Package

po/ fr.po: Validation and Addition

Once po/ fr.po is completed, hit

1 2 3

. This will:

Update the revision date Save the le Run msgfmt --statistics --check on po/ fr.po, to validate it.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

153 / 162

Gettext

Localizing a Package

po/ fr.po: Validation and Addition

Once po/ fr.po is completed, hit

1 2 3

. This will:

Update the revision date Save the le Run msgfmt --statistics --check on po/ fr.po, to validate it.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

154 / 162

Gettext

Localizing a Package

Updating Message Catalogs

Because maintainers can change the strings marked for translation, the messages catalogs are varying, and are not always up-to-date.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

155 / 162

Gettext

Localizing a Package

Updating Message Catalogs

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

155 / 162

Gettext

Localizing a Package

Updating Message Catalogs

Because maintainers can change the strings marked for translation, the messages catalogs are varying, and are not always up-to-date. Varying messages. update-po modify *.po le: New messages are added with a blank translation. Obsolete translations, not used anymore, are commented. Messages with tiny changes keep their translation, but are marked fuzzy. Translators remove fuzzy attributes ( Tab ) after verication. Not up-to-date. gettext copes with incomplete translations as follows. Untranslated messages are output untranslated. Fuzzy messages are also output untranslated. (Better output the original sentence, rather than an inappropriate translation.)

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

155 / 162

Gettext

Localizing a Package

Updating Message Catalogs

Gettext

Localizing a Package

Language Teams & The Translation Project

http://www.iro.umontreal.ca/translation/ The Translation Project provides an infrastructure for package maintainers and translators to exchange messages catalogs.

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

156 / 162

Gettext

Localizing a Package

Language Teams & The Translation Project

http://www.iro.umontreal.ca/translation/ The Translation Project provides an infrastructure for package maintainers and translators to exchange messages catalogs. Translators gather in Language Teams (consider joining the team of your own language) to discuss issues. Maintainer submit *.pot les and are notied when *.po les are updated. Pages in The Translation Project will show where work is needed (consider adopting an orphan *.po le.)

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

156 / 162

Gettext

Localizing a Package

Language Teams & The Translation Project

Nested Packages

Nested Packages
10

11 12

13 14

A. Duret-Lutz

Using GNU Autotools

May 16, 2010

157 / 162

Nested Packages

Autoconscated packages can be nested to arbitrary depth.

A package can distribute a third-party library it uses in a subdirectory. Its possible to gather many packages this way to distribute a set of tools.

For installers:
A single package to congure, build, and install. configure options are passed recursively to sub-packages. configure --help=recursive shows the help of all sub-packages.

The arm program links with an hand library, a nested package in hand/ .

arms congure.ac
AC_INIT([arm], [1.0]) AM_INIT_AUTOMAKE([foreign -Wall -Werror]) arms Makele.am AC_PROG_CC SUBDIRS = hand src AC_CONFIG_FILES([Makefile src/Makefile]) AC_CONFIG_SUBDIRS([hand]) AC_OUTPUT

May 16, 2010

162 / 162

Object Oriented Programming Using C++: ETCS-258
No ratings yet
Object Oriented Programming Using C++: ETCS-258
27 pages
Learning Cmake
100% (6)
Learning Cmake
45 pages
Mastering Cmake PDF
100% (3)
Mastering Cmake PDF
448 pages
Prakas 12
No ratings yet
Prakas 12
140 pages
Internship Presentation
No ratings yet
Internship Presentation
40 pages
Development Tools
No ratings yet
Development Tools
40 pages
C C++ Development Toolkit User Guide
No ratings yet
C C++ Development Toolkit User Guide
406 pages
Autotools-Automake, Autoconfig, Autogen, Libtool: Understanding Build Systems
No ratings yet
Autotools-Automake, Autoconfig, Autogen, Libtool: Understanding Build Systems
43 pages
Make
No ratings yet
Make
24 pages
Week3 M
No ratings yet
Week3 M
18 pages
C++ Development Tools For Linux - Jesper K. Pedersen PDF
No ratings yet
C++ Development Tools For Linux - Jesper K. Pedersen PDF
13 pages
Week3 M
No ratings yet
Week3 M
18 pages
Ken Martin, Bill Hoffman-Mastering CMake-Kitware PDF
100% (1)
Ken Martin, Bill Hoffman-Mastering CMake-Kitware PDF
448 pages
PDF For C
No ratings yet
PDF For C
9 pages
Makefile Generation From Autotools
No ratings yet
Makefile Generation From Autotools
25 pages
11 Development Tools: 11.1 Program Builds
No ratings yet
11 Development Tools: 11.1 Program Builds
21 pages
Autotools
No ratings yet
Autotools
8 pages
Unit III
No ratings yet
Unit III
3 pages
Auto Tools Tutorial
No ratings yet
Auto Tools Tutorial
8 pages
Compiling Source Code Guide
No ratings yet
Compiling Source Code Guide
8 pages
Auto Make
No ratings yet
Auto Make
182 pages
Computer Fundamental: For Programming
No ratings yet
Computer Fundamental: For Programming
11 pages
Makefile
No ratings yet
Makefile
114 pages
Programming in C++
No ratings yet
Programming in C++
46 pages
Linux - Iv Unit
No ratings yet
Linux - Iv Unit
34 pages
Mastering CMake
No ratings yet
Mastering CMake
7 pages
Compiling Software From Source
No ratings yet
Compiling Software From Source
12 pages
Development Tools: We Have Variety of FOSS Development Tools Development Tools
No ratings yet
Development Tools: We Have Variety of FOSS Development Tools Development Tools
29 pages
Auto Make
No ratings yet
Auto Make
193 pages
Chapter 7: Directory Organization and Makefile Style: Organizing Your Directories
No ratings yet
Chapter 7: Directory Organization and Makefile Style: Organizing Your Directories
12 pages
C Programming
No ratings yet
C Programming
32 pages
The Makefile Utility: Courtesy: UCCS
No ratings yet
The Makefile Utility: Courtesy: UCCS
28 pages
39 Make
No ratings yet
39 Make
26 pages
Programming On Unix
No ratings yet
Programming On Unix
17 pages
Makefile Guide
No ratings yet
Makefile Guide
36 pages
Mastering CMake
No ratings yet
Mastering CMake
448 pages
Building The GNU Toolchain For ARM Targets: % Hello - Help
No ratings yet
Building The GNU Toolchain For ARM Targets: % Hello - Help
12 pages
Porting Newlib
No ratings yet
Porting Newlib
41 pages
Unix Book
No ratings yet
Unix Book
57 pages
Auto Make
No ratings yet
Auto Make
189 pages
How To Compile Linux Software With Debian Linux
No ratings yet
How To Compile Linux Software With Debian Linux
11 pages
C/C++ Unix Dev Tutorial: Maslab 2003
No ratings yet
C/C++ Unix Dev Tutorial: Maslab 2003
45 pages
Cross Compile Hacks Andy Huang 0423
No ratings yet
Cross Compile Hacks Andy Huang 0423
43 pages
Mastering CMake 118 270
No ratings yet
Mastering CMake 118 270
463 pages
Programming On Stanford)
No ratings yet
Programming On Stanford)
17 pages
Rdist Tutorial
No ratings yet
Rdist Tutorial
13 pages
Gnu Make - Kickstart: Nicholas MC Guire Opentech Edv-Research GMBH June 11, 2005
No ratings yet
Gnu Make - Kickstart: Nicholas MC Guire Opentech Edv-Research GMBH June 11, 2005
15 pages
Advanced C Programming: Gmake, GDB
No ratings yet
Advanced C Programming: Gmake, GDB
25 pages
Unix File System
No ratings yet
Unix File System
95 pages
The Mac Terminal Reference and Scripting Primer
From Everand
The Mac Terminal Reference and Scripting Primer
Jay Docherty
4.5/5 (3)
Update to Modern C++
From Everand
Update to Modern C++
James Raynard
No ratings yet
The 1 Page Python Book
From Everand
The 1 Page Python Book
Barani Kumar
2/5 (1)
Mastering Go A Practical Guide to Developers: A Practical Guide to Developers
From Everand
Mastering Go A Practical Guide to Developers: A Practical Guide to Developers
Miguel Miranda de Mattos
No ratings yet
Learn R By Coding
From Everand
Learn R By Coding
Thomas Kurnicki
No ratings yet
Python for Beginners: An Introduction to Learn Python Programming with Tutorials and Hands-On Examples
From Everand
Python for Beginners: An Introduction to Learn Python Programming with Tutorials and Hands-On Examples
Nathan Metzler
4/5 (2)
Python-Deprecated Library v1.1 Documentation
From Everand
Python-Deprecated Library v1.1 Documentation
Laurent LAPORTE
No ratings yet
R Programming - a Comprehensive Guide: Software
From Everand
R Programming - a Comprehensive Guide: Software
Editor IJSMI
No ratings yet
Ubuntu: MOTU Developer
From Everand
Ubuntu: MOTU Developer
Frank Cheung
No ratings yet
Learning Rust
From Everand
Learning Rust
IT Campus Academy
No ratings yet
Mastering Python Programming: A Comprehensive Guide: The IT Collection
From Everand
Mastering Python Programming: A Comprehensive Guide: The IT Collection
Christopher Ford
5/5 (1)