GNU Automake

For version 1.11.3, 1 February 2012

David MacKenzie
Tom Tromey
Alexandre Duret-Lutz

This manual is for GNU Automake (version 1.11.3, 1 February 2012), a program that creates GNU standards-compliant Makefiles from template files.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License.”

GNU Automake

This manual is for GNU Automake (version 1.11.3, 1 February 2012), a program that creates GNU standards-compliant Makefiles from template files.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License.”

— The Detailed Node Listing — An Introduction to the Autotools
1 Introduction		Automake’s purpose
2 An Introduction to the Autotools
3 General ideas
4 Some example packages
5 Creating a ‘`Makefile.in`’		Creating a Makefile.in
6 Scanning ‘`configure.ac`’, using `aclocal`		Scanning configure.ac, using aclocal
7 Directories		Declaring subdirectories
8 Building Programs and Libraries		Building programs and libraries
9 Other Derived Objects		Other derived objects
10 Other GNU Tools
11 Building documentation
12 What Gets Installed		What gets installed
13 What Gets Cleaned		What gets cleaned
14 What Goes in a Distribution		What goes in a distribution
15 Support for test suites
16 Rebuilding Makefiles		Automatic rebuilding of Makefile
17 Changing Automake’s Behavior		Changing Automake’s behavior
18 Miscellaneous Rules		Miscellaneous rules
19 Include		Including extra files in an Automake template
20 Conditionals
21 Silencing `make`		Obtain less verbose output from `make`
22 The effect of ‘`--gnu`’ and ‘`--gnits`’
23 The effect of ‘`--cygnus`’
24 When Automake Isn’t Enough		When Automake is not Enough
25 Distributing ‘`Makefile.in`’s		Distributing the Makefile.in
26 Automake API Versioning		About compatibility between Automake versions
27 Upgrading a Package to a Newer Automake Version		Upgrading to a Newer Automake Version
28 Frequently Asked Questions about Automake		Frequently Asked Questions
29 History of Automake		Notes about the history of Automake
Appendix A Copying This Manual		How to make copies of this manual
Appendix B Indices		Indices of variables, macros, and concepts
2.1 Introducing the GNU Build System
2.2 Use Cases for the GNU Build System
2.3 How Autotools Help
2.4 A Small Hello World		A Small Hello World Package
Use Cases for the GNU Build System
2.2.1 Basic Installation		Common installation procedure
2.2.2 Standard ‘`Makefile`’ Targets		A list of standard Makefile targets
2.2.3 Standard Directory Variables		A list of standard directory variables
2.2.4 Standard Configuration Variables		Using configuration variables
2.2.5 Overriding Default Configuration Setting with ‘`config.site`’		Using a config.site file
2.2.6 Parallel Build Trees (a.k.a. VPATH Builds)		Parallel build trees
2.2.7 Two-Part Installation		Installing data and programs separately
2.2.8 Cross-Compilation		Building for other architectures
2.2.9 Renaming Programs at Install Time		Renaming programs at install time
2.2.10 Building Binary Packages Using DESTDIR		Building binary packages with DESTDIR
2.2.11 Preparing Distributions		Rolling out tarballs
2.2.12 Automatic Dependency Tracking		Automatic dependency tracking
2.2.13 Nested Packages		The GNU Build Systems can be nested
A Small Hello World
2.4.1 Creating ‘`amhello-1.0.tar.gz`’		Create ‘`amhello-1.0.tar.gz`’ from scratch
2.4.2 `amhello`’s ‘`configure.ac`’ Setup Explained
2.4.3 `amhello`’s ‘`Makefile.am`’ Setup Explained
General ideas
3.1 General Operation		General operation of Automake
3.2 Strictness		Standards conformance checking
3.3 The Uniform Naming Scheme
3.4 Staying below the command line length limit
3.5 How derived variables are named
3.6 Variables reserved for the user
3.7 Programs automake might require
Some example packages
4.1 A simple example, start to finish
4.2 Building true and false
Scanning ‘`configure.ac`’, using `aclocal`
6.1 Configuration requirements
6.2 Other things Automake recognizes
6.3 Auto-generating aclocal.m4
6.4 Autoconf macros supplied with Automake
Auto-generating aclocal.m4
6.3.1 aclocal Options		Options supported by aclocal
6.3.2 Macro Search Path		How aclocal finds .m4 files
6.3.3 Writing your own aclocal macros
6.3.4 Handling Local Macros		Organizing local macros
6.3.5 Serial Numbers		Serial lines in Autoconf macros
6.3.6 The Future of `aclocal`		aclocal’s scheduled death
Autoconf macros supplied with Automake
6.4.1 Public Macros		Macros that you can use.
6.4.2 Obsolete Macros		Macros that you should stop using.
6.4.3 Private Macros		Macros that you should not use.
Directories
7.1 Recursing subdirectories		Building subdirectories recursively
7.2 Conditional Subdirectories		Conditionally not building directories
7.3 An Alternative Approach to Subdirectories		Subdirectories without recursion
7.4 Nesting Packages		Nesting packages
Conditional Subdirectories
7.2.1 `SUBDIRS` vs. `DIST_SUBDIRS`		Two sets of directories
7.2.2 Subdirectories with `AM_CONDITIONAL`		Specifying conditional subdirectories
7.2.3 Subdirectories with `AC_SUBST`		Another way for conditional recursion
7.2.4 Unconfigured Subdirectories		Not even creating a ‘`Makefile`’
Building Programs and Libraries
8.1 Building a program
8.2 Building a library
8.3 Building a Shared Library		Building a Libtool library
8.4 Program and Library Variables		Variables controlling program and library builds
8.5 Default `_SOURCES`		Default source files
8.6 Special handling for `LIBOBJS` and `ALLOCA`		Special handling for LIBOBJS and ALLOCA
8.7 Variables used when building a program
8.8 Yacc and Lex support
8.9 C++ Support		Compiling C++ sources
8.10 Objective C Support		Compiling Objective C sources
8.11 Unified Parallel C Support		Compiling Unified Parallel C sources
8.12 Assembly Support		Compiling assembly sources
8.13 Fortran 77 Support		Compiling Fortran 77 sources
8.14 Fortran 9x Support		Compiling Fortran 9x sources
8.15 Compiling Java sources using gcj
8.16 Vala Support		Compiling Vala sources
8.17 Support for Other Languages		Compiling other languages
8.18 Automatic de-ANSI-fication (deprecated, soon to be removed)
8.19 Automatic dependency tracking
8.20 Support for executable extensions
Building a program
8.1.1 Defining program sources
8.1.2 Linking the program		Linking with libraries or extra objects
8.1.3 Conditional compilation of sources		Handling conditional sources
8.1.4 Conditional compilation of programs		Building a program conditionally
Building a Shared Library
8.3.1 The Libtool Concept		Introducing Libtool
8.3.2 Building Libtool Libraries		Declaring Libtool Libraries
8.3.3 Building Libtool Libraries Conditionally
8.3.4 Libtool Libraries with Conditional Sources		Choosing Library Sources Conditionally
8.3.5 Libtool Convenience Libraries		Building Convenience Libtool Libraries
8.3.6 Libtool Modules		Building Libtool Modules
8.3.7 `_LIBADD`, `_LDFLAGS`, and `_LIBTOOLFLAGS`		Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
8.3.8 `LTLIBOBJS` and `LTALLOCA`		Using $(LTLIBOBJS) and $(LTALLOCA)
8.3.9 Common Issues Related to Libtool’s Use
Common Issues Related to Libtool’s Use
8.3.9.1 Error: ‘required file `./ltmain.sh' not found’		The need to run libtoolize
8.3.9.2 Objects ‘`created with both libtool and without`’		Avoid a specific build race
Fortran 77 Support
8.13.1 Preprocessing Fortran 77		Preprocessing Fortran 77 sources
8.13.2 Compiling Fortran 77 Files		Compiling Fortran 77 sources
8.13.3 Mixing Fortran 77 With C and C++
Mixing Fortran 77 With C and C++
8.13.3.1 How the Linker is Chosen		Automatic linker selection
Fortran 9x Support
8.14.1 Compiling Fortran 9x Files		Compiling Fortran 9x sources
Other Derived Objects
9.1 Executable Scripts		Executable scripts
9.2 Header files
9.3 Architecture-independent data files
9.4 Built Sources		Derived sources
Built Sources
9.4.1 Built Sources Example		Several ways to handle built sources.
Other GNU Tools
10.1 Emacs Lisp
10.2 Gettext
10.3 Libtool
10.4 Java bytecode compilation (deprecated)
10.5 Python
Building documentation
11.1 Texinfo
11.2 Man Pages		Man pages
What Gets Installed
12.1 Basics of Installation		What gets installed where
12.2 The Two Parts of Install		Installing data and programs separately
12.3 Extending Installation		Adding your own rules for installation
12.4 Staged Installs		Installation in a temporary location
12.5 Install Rules for the User		Useful additional rules
What Goes in a Distribution
14.1 Basics of Distribution		Files distributed by default
14.2 Fine-grained Distribution Control		`dist_` and `nodist_` prefixes
14.3 The dist Hook		A target for last-minute distribution changes
14.4 Checking the Distribution		‘`make distcheck`’ explained
14.5 The Types of Distributions		A variety of formats and compression methods
Support for test suites
15.1 Simple Tests		Listing programs and scripts in `TESTS`
15.2 Simple Tests using ‘`parallel-tests`’		More powerful test driver
15.3 DejaGnu Tests		Interfacing with the external testing framework
15.4 Install Tests		Running tests on installed packages
Miscellaneous Rules
18.1 Interfacing to `etags`		Interfacing to etags and mkid
18.2 Handling new file extensions
18.3 Support for Multilibs (deprecated, soon to be removed).		Support for multilibs (deprecated, soon to be removed).
Conditionals
20.1 Usage of Conditionals		Declaring conditional content
20.2 Limits of Conditionals		Enclosing complete statements
Silencing Make
21.1 Make is verbose by default
21.2 Standard and generic ways to silence make
21.3 How Automake can help in silencing make
When Automake Isn’t Enough
24.1 Extending Automake Rules		Adding new rules or overriding existing ones.
24.2 Third-Party ‘`Makefile`’s		Integrating Non-Automake ‘`Makefile`’s.
Frequently Asked Questions about Automake
28.1 CVS and generated files
28.2 `missing` and `AM_MAINTAINER_MODE`		missing and AM_MAINTAINER_MODE
28.3 Why doesn’t Automake support wildcards?
28.4 Limitations on File Names		Limitations on source and installed file names
28.5 Files left in build directory after distclean
28.6 Flag Variables Ordering		CFLAGS vs. AM_CFLAGS vs. mumble_CFLAGS
28.7 Why are object files sometimes renamed?
28.8 Per-Object Flags Emulation		How to simulate per-object flags?
28.9 Handling Tools that Produce Many Outputs		Writing rules for tools with many output files
28.10 Installing to Hard-Coded Locations		Installing to hard-coded locations
28.11 Debugging Make Rules		Strategies when things don’t work as expected
28.12 Reporting Bugs		Feedback on bugs and feature requests
History of Automake
29.1 Timeline		The Automake story.
29.2 Dependency Tracking in Automake		Evolution of Automatic Dependency Tracking
29.3 Release Statistics		Statistics about Automake Releases
Dependency Tracking in Automake
29.2.1 First Take on Dependency Tracking		Precomputed dependency tracking
29.2.2 Dependencies As Side Effects		Update at developer compile time
29.2.3 Dependencies for the User		Update at user compile time
29.2.4 Techniques for Computing Dependencies		Alternative approaches
29.2.5 Recommendations for Tool Writers		What tool writers can do to help
29.2.6 Future Directions for Dependencies		Languages Automake does not know
Copying This Manual
A.1 GNU Free Documentation License		License for copying this manual
Indices
B.1 Macro Index		Index of Autoconf macros
B.2 Variable Index		Index of Makefile variables
B.3 General Index		General index

This document was generated on February 3, 2012 using texi2html 5.0.