GNU Automake

For version 1.14.1, 6 November 2013

David MacKenzie
Tom Tromey
Alexandre Duret-Lutz
Ralf Wildenhues
Stefano Lattarini

This manual is for GNU Automake (version 1.14.1, 6 November 2013), 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.14.1, 6 November 2013), 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 When Automake Isn’t Enough		When Automake is not Enough
24 Distributing ‘`Makefile.in`’s		Distributing the Makefile.in
25 Automake API Versioning		About compatibility between Automake versions
26 Upgrading a Package to a Newer Automake Version		Upgrading to a Newer Automake Version
27 Frequently Asked Questions about Automake		Frequently Asked Questions
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.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 Objective C++ Support		Compiling Objective C++ sources
8.12 Unified Parallel C Support		Compiling Unified Parallel C sources
8.13 Assembly Support		Compiling assembly sources
8.14 Fortran 77 Support		Compiling Fortran 77 sources
8.15 Fortran 9x Support		Compiling Fortran 9x sources
8.16 Compiling Java sources using gcj
8.17 Vala Support		Compiling Vala sources
8.18 Support for Other Languages		Compiling other languages
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.14.1 Preprocessing Fortran 77		Preprocessing Fortran 77 sources
8.14.2 Compiling Fortran 77 Files		Compiling Fortran 77 sources
8.14.3 Mixing Fortran 77 With C and C++
Mixing Fortran 77 With C and C++
8.14.3.1 How the Linker is Chosen		Automatic linker selection
Fortran 9x Support
8.15.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 Generalities about Testing		Generic concepts and terminology about testing
15.2 Simple Tests		Listing test scripts in `TESTS`
15.3 Custom Test Drivers		Writing and using custom test drivers
15.4 Using the TAP test protocol		Integrating test scripts that use the TAP protocol
15.5 DejaGnu Tests		Interfacing with the `dejagnu` testing framework
15.6 Install Tests		Running tests on installed packages
Simple Tests
15.2.1 Scripts-based Testsuites		Automake-specific concepts and terminology
15.2.2 Older (and discouraged) serial test harness
15.2.3 Parallel Test Harness		Generic concurrent test harness
Using the TAP test protocol
15.4.1 Introduction to TAP
15.4.2 Use TAP with the Automake test harness
15.4.3 Incompatibilities with other TAP parsers and drivers
15.4.4 Links and external resources on TAP
Custom Test Drivers
15.3.1 Overview of Custom Test Drivers Support
15.3.2 Declaring Custom Test Drivers
15.3.3 API for Custom Test Drivers
API for Custom Test Drivers
15.3.3.1 Command-line arguments for test drivers
15.3.3.2 Log files generation and test results recording
15.3.3.3 Testsuite progress output
Changing Automake’s Behavior
17.1 Options generalities		Semantics of Automake option
17.2 List of Automake options		A comprehensive list of Automake options
Miscellaneous Rules
18.1 Interfacing to `etags`		Interfacing to cscope, etags and mkid
18.2 Handling new file extensions
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
23.1 Extending Automake Rules		Adding new rules or overriding existing ones.
23.2 Third-Party ‘`Makefile`’s		Integrating Non-Automake ‘`Makefile`’s.
Frequently Asked Questions about Automake
27.1 CVS and generated files
27.2 `missing` and `AM_MAINTAINER_MODE`		missing and AM_MAINTAINER_MODE
27.3 Why doesn’t Automake support wildcards?
27.4 Limitations on File Names		Limitations on source and installed file names
27.5 Errors with distclean		Files left in build directory after distclean
27.6 Flag Variables Ordering		CFLAGS vs. AM_CFLAGS vs. mumble_CFLAGS
27.7 Why are object files sometimes renamed?
27.8 Per-Object Flags Emulation		How to simulate per-object flags?
27.9 Handling Tools that Produce Many Outputs		Writing rules for tools with many output files
27.10 Installing to Hard-Coded Locations		Installing to hard-coded locations
27.11 Debugging Make Rules		Strategies when things don’t work as expected
27.12 Reporting Bugs		Feedback on bugs and feature requests
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 January 25, 2014 using texi2html 5.0.