automake

GNU Automake

This manual is for GNU Automake (version 1.12.2a, 9 July 2012), a program that creates GNU standards-compliant Makefiles from template files.

Copyright © 1995-2012 Free Software Foundation, Inc.

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.”

• Introduction: Automake's purpose
• Autotools Introduction: An Introduction to the Autotools
• Generalities: General ideas
• Examples: Some example packages
• automake Invocation: Creating a Makefile.in
• configure: Scanning configure.ac, using aclocal
• Directories: Declaring subdirectories
• Programs: Building programs and libraries
• Other Objects: Other derived objects
• Other GNU Tools: Other GNU Tools
• Documentation: Building documentation
• Install: What gets installed
• Clean: What gets cleaned
• Dist: What goes in a distribution
• Tests: Support for test suites
• Rebuilding: Automatic rebuilding of Makefile
• Options: Changing Automake's behavior
• Miscellaneous: Miscellaneous rules
• Include: Including extra files in an Automake template
• Conditionals: Conditionals
• Silencing Make: Obtain less verbose output from make
• Gnits: The effect of --gnu and --gnits
• Cygnus: The effect of --cygnus (deprecated, soon to be removed)
• Not Enough: When Automake is not Enough
• Distributing: Distributing the Makefile.in
• API Versioning: About compatibility between Automake versions
• Upgrading: Upgrading to a Newer Automake Version
• FAQ: Frequently Asked Questions
• Copying This Manual: How to make copies of this manual
• Indices: Indices of variables, macros, and concepts

--- The Detailed Node Listing ---

An Introduction to the Autotools

• GNU Build System: Introducing the GNU Build System
• Use Cases: Use Cases for the GNU Build System
• Why Autotools: How Autotools Help
• Hello World: A Small Hello World Package

Use Cases for the GNU Build System

• Basic Installation: Common installation procedure
• Standard Targets: A list of standard Makefile targets
• Standard Directory Variables: A list of standard directory variables
• Standard Configuration Variables: Using configuration variables
• config.site: Using a config.site file
• VPATH Builds: Parallel build trees
• Two-Part Install: Installing data and programs separately
• Cross-Compilation: Building for other architectures
• Renaming: Renaming programs at install time
• DESTDIR: Building binary packages with DESTDIR
• Preparing Distributions: Rolling out tarballs
• Dependency Tracking: Automatic dependency tracking
• Nested Packages: The GNU Build Systems can be nested

A Small Hello World

• Creating amhello: Create amhello-1.0.tar.gz from scratch
• amhello's configure.ac Setup Explained
• amhello's Makefile.am Setup Explained

General ideas

• General Operation: General operation of Automake
• Strictness: Standards conformance checking
• Uniform: The Uniform Naming Scheme
• Length Limitations: Staying below the command line length limit
• Canonicalization: How derived variables are named
• User Variables: Variables reserved for the user
• Auxiliary Programs: Programs automake might require

Some example packages

• Complete: A simple example, start to finish
• true: Building true and false

Scanning configure.ac, using aclocal

• Requirements: Configuration requirements
• Optional: Other things Automake recognizes
• aclocal Invocation: Auto-generating aclocal.m4
• Macros: Autoconf macros supplied with Automake

Auto-generating aclocal.m4

• aclocal Options: Options supported by aclocal
• Macro Search Path: How aclocal finds .m4 files
• Extending aclocal: Writing your own aclocal macros
• Local Macros: Organizing local macros
• Serials: Serial lines in Autoconf macros
• Future of aclocal: aclocal's scheduled death

Autoconf macros supplied with Automake

• Public Macros: Macros that you can use.
• Obsolete Macros: Macros that will soon be removed.
• Private Macros: Macros that you should not use.

Directories

• Subdirectories: Building subdirectories recursively
• Conditional Subdirectories: Conditionally not building directories
• Alternative: Subdirectories without recursion
• Subpackages: Nesting packages

Conditional Subdirectories

• SUBDIRS vs DIST_SUBDIRS: Two sets of directories
• Subdirectories with AM_CONDITIONAL: Specifying conditional subdirectories
• Subdirectories with AC_SUBST: Another way for conditional recursion
• Unconfigured Subdirectories: Not even creating a ‘Makefile’

Building Programs and Libraries

• A Program: Building a program
• A Library: Building a library
• A Shared Library: Building a Libtool library
• Program and Library Variables: Variables controlling program and library builds
• Default _SOURCES: Default source files
• LIBOBJS: Special handling for LIBOBJS and ALLOCA
• Program Variables: Variables used when building a program
• Yacc and Lex: Yacc and Lex support
• C++ Support: Compiling C++ sources
• Objective C Support: Compiling Objective C sources
• Objective C++ Support: Compiling Objective C++ sources
• Unified Parallel C Support: Compiling Unified Parallel C sources
• Assembly Support: Compiling assembly sources
• Fortran 77 Support: Compiling Fortran 77 sources
• Fortran 9x Support: Compiling Fortran 9x sources
• Java Support with gcj: Compiling Java sources using gcj
• Vala Support: Compiling Vala sources
• Support for Other Languages: Compiling other languages
• Dependencies: Automatic dependency tracking
• EXEEXT: Support for executable extensions

Building a program

• Program Sources: Defining program sources
• Linking: Linking with libraries or extra objects
• Conditional Sources: Handling conditional sources
• Conditional Programs: Building a program conditionally

Building a Shared Library

• Libtool Concept: Introducing Libtool
• Libtool Libraries: Declaring Libtool Libraries
• Conditional Libtool Libraries: Building Libtool Libraries Conditionally
• Conditional Libtool Sources: Choosing Library Sources Conditionally
• Libtool Convenience Libraries: Building Convenience Libtool Libraries
• Libtool Modules: Building Libtool Modules
• Libtool Flags: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
• LTLIBOBJS: Using $(LTLIBOBJS) and $(LTALLOCA)
• Libtool Issues: Common Issues Related to Libtool's Use

Common Issues Related to Libtool's Use

• Error required file ltmain.sh not found: The need to run libtoolize
• Objects created both with libtool and without: Avoid a specific build race

Fortran 77 Support

• Preprocessing Fortran 77: Preprocessing Fortran 77 sources
• Compiling Fortran 77 Files: Compiling Fortran 77 sources
• Mixing Fortran 77 With C and C++: Mixing Fortran 77 With C and C++

Mixing Fortran 77 With C and C++

• How the Linker is Chosen: Automatic linker selection

Fortran 9x Support

• Compiling Fortran 9x Files: Compiling Fortran 9x sources

Other Derived Objects

• Scripts: Executable scripts
• Headers: Header files
• Data: Architecture-independent data files
• Sources: Derived sources

Built Sources

• Built Sources Example: Several ways to handle built sources.

Other GNU Tools

• Emacs Lisp: Emacs Lisp
• gettext: Gettext
• Libtool: Libtool
• Java: Java bytecode compilation (deprecated)
• Python: Python

Building documentation

• Texinfo: Texinfo
• Man Pages: Man pages

What Gets Installed

• Basics of Installation: What gets installed where
• The Two Parts of Install: Installing data and programs separately
• Extending Installation: Adding your own rules for installation
• Staged Installs: Installation in a temporary location
• Install Rules for the User: Useful additional rules

What Goes in a Distribution

• Basics of Distribution: Files distributed by default
• Fine-grained Distribution Control: dist_ and nodist_ prefixes
• The dist Hook: A target for last-minute distribution changes
• Checking the Distribution: ‘make distcheck’ explained
• The Types of Distributions: A variety of formats and compression methods

Support for test suites

• Generalities about Testing: Generic concepts and terminology about testing
• Simple Tests: Listing test scripts in TESTS
• Custom Test Drivers: Writing and using custom test drivers
• Using the TAP test protocol: Integrating test scripts that use the TAP protocol
• DejaGnu Tests: Interfacing with the dejagnu testing framework
• Install Tests: Running tests on installed packages

Simple Tests

• Scripts-based Testsuites: Automake-specific concepts and terminology
• Serial Test Harness: Older (and obsolescent) serial test harness
• Parallel Test Harness: Generic concurrent test harness

Using the TAP test protocol

• Introduction to TAP
• Use TAP with the Automake test harness
• Incompatibilities with other TAP parsers and drivers
• Links and external resources on TAP

Custom Test Drivers

• Overview of Custom Test Drivers Support
• Declaring Custom Test Drivers
• API for Custom Test Drivers

API for Custom Test Drivers

• Command-line arguments for test drivers
• Log files generation and test results recording
• Testsuite progress output

Changing Automake's Behavior

• Options generalities: Semantics of Automake option
• List of Automake options: A comprehensive list of Automake options

Miscellaneous Rules

• Tags: Interfacing to cscope, etags and mkid
• Suffixes: Handling new file extensions

Conditionals

• Usage of Conditionals: Declaring conditional content
• Limits of Conditionals: Enclosing complete statements

Silencing Make

• Make verbosity: Make is verbose by default
• Tricks For Silencing Make: Standard and generic ways to silence make
• Automake silent-rules Option: How Automake can help in silencing make

When Automake Isn't Enough

• Extending: Adding new rules or overriding existing ones.
• Third-Party Makefiles: Integrating Non-Automake Makefiles.

Frequently Asked Questions about Automake

• CVS: CVS and generated files
• maintainer-mode: missing and AM_MAINTAINER_MODE
• Wildcards: Why doesn't Automake support wildcards?
• Limitations on File Names: Limitations on source and installed file names
• Errors with distclean: Files left in build directory after distclean
• Flag Variables Ordering: CFLAGS vs. AM_CFLAGS vs. mumble_CFLAGS
• Renamed Objects: Why are object files sometimes renamed?
• Per-Object Flags: How to simulate per-object flags?
• Multiple Outputs: Writing rules for tools with many output files
• Hard-Coded Install Paths: Installing to hard-coded locations
• Debugging Make Rules: Strategies when things don't work as expected
• Reporting Bugs: Feedback on bugs and feature requests

Copying This Manual

• GNU Free Documentation License: License for copying this manual

Indices

• Macro Index: Index of Autoconf macros
• Variable Index: Index of Makefile variables
• General Index: General index