Autoconf

Autoconf

This manual (26 July 2009) is for GNU Autoconf (version 2.64), a package for creating scripts to configure source code packages using templates and an M4 macro package.

Copyright © 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 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 the Front-Cover texts being “A GNU Manual,” and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled “GNU Free Documentation License.”

(a) The FSF's Back-Cover Text is: “You have the freedom to copy and modify this GNU manual. Buying copies from the FSF supports it in developing GNU and promoting software freedom.”

• Introduction: Autoconf's purpose, strengths, and weaknesses
• The GNU Build System: A set of tools for portable software packages
• Making configure Scripts: How to organize and produce Autoconf scripts
• Setup: Initialization and output
• Existing Tests: Macros that check for particular features
• Writing Tests: How to write new feature checks
• Results: What to do with results from feature checks
• Programming in M4: Layers on top of which Autoconf is written
• Programming in M4sh: Shell portability layer
• Writing Autoconf Macros: Adding new macros to Autoconf
• Portable Shell: Shell script portability pitfalls
• Portable Make: Makefile portability pitfalls
• Portable C and C++: C and C++ portability pitfalls
• Manual Configuration: Selecting features that can't be guessed
• Site Configuration: Local defaults for configure
• Running configure Scripts: How to use the Autoconf output
• config.status Invocation: Recreating a configuration
• Obsolete Constructs: Kept for backward compatibility
• Using Autotest: Creating portable test suites
• FAQ: Frequent Autoconf Questions, with answers
• History: History of Autoconf
• GNU Free Documentation License: License for copying this manual
• Indices: Indices of symbols, concepts, etc.

--- The Detailed Node Listing ---

The GNU Build System

• Automake: Escaping makefile hell
• Gnulib: The GNU portability library
• Libtool: Building libraries portably
• Pointers: More info on the GNU build system

Making configure Scripts

• Writing Autoconf Input: What to put in an Autoconf input file
• autoscan Invocation: Semi-automatic configure.ac writing
• ifnames Invocation: Listing the conditionals in source code
• autoconf Invocation: How to create configuration scripts
• autoreconf Invocation: Remaking multiple configure scripts

Writing configure.ac

• Shell Script Compiler: Autoconf as solution of a problem
• Autoconf Language: Programming in Autoconf
• Autoconf Input Layout: Standard organization of configure.ac

Initialization and Output Files

• Initializing configure: Option processing etc.
• Versioning: Dealing with Autoconf versions
• Notices: Copyright, version numbers in configure
• Input: Where Autoconf should find files
• Output: Outputting results from the configuration
• Configuration Actions: Preparing the output based on results
• Configuration Files: Creating output files
• Makefile Substitutions: Using output variables in makefiles
• Configuration Headers: Creating a configuration header file
• Configuration Commands: Running arbitrary instantiation commands
• Configuration Links: Links depending on the configuration
• Subdirectories: Configuring independent packages together
• Default Prefix: Changing the default installation prefix

Substitutions in Makefiles

• Preset Output Variables: Output variables that are always set
• Installation Directory Variables: Other preset output variables
• Changed Directory Variables: Warnings about datarootdir
• Build Directories: Supporting multiple concurrent compiles
• Automatic Remaking: Makefile rules for configuring

Configuration Header Files

• Header Templates: Input for the configuration headers
• autoheader Invocation: How to create configuration templates
• Autoheader Macros: How to specify CPP templates

Existing Tests

• Common Behavior: Macros' standard schemes
• Alternative Programs: Selecting between alternative programs
• Files: Checking for the existence of files
• Libraries: Library archives that might be missing
• Library Functions: C library functions that might be missing
• Header Files: Header files that might be missing
• Declarations: Declarations that may be missing
• Structures: Structures or members that might be missing
• Types: Types that might be missing
• Compilers and Preprocessors: Checking for compiling programs
• System Services: Operating system services
• Posix Variants: Special kludges for specific Posix variants
• Erlang Libraries: Checking for the existence of Erlang libraries

Common Behavior

• Standard Symbols: Symbols defined by the macros
• Default Includes: Includes used by the generic macros

Alternative Programs

• Particular Programs: Special handling to find certain programs
• Generic Programs: How to find other programs

Library Functions

• Function Portability: Pitfalls with usual functions
• Particular Functions: Special handling to find certain functions
• Generic Functions: How to find other functions

Header Files

• Header Portability: Collected knowledge on common headers
• Particular Headers: Special handling to find certain headers
• Generic Headers: How to find other headers

Declarations

• Particular Declarations: Macros to check for certain declarations
• Generic Declarations: How to find other declarations

Structures

• Particular Structures: Macros to check for certain structure members
• Generic Structures: How to find other structure members

Types

• Particular Types: Special handling to find certain types
• Generic Types: How to find other types

Compilers and Preprocessors

• Specific Compiler Characteristics: Some portability issues
• Generic Compiler Characteristics: Language independent tests and features
• C Compiler: Checking its characteristics
• C++ Compiler: Likewise
• Objective C Compiler: Likewise
• Erlang Compiler and Interpreter: Likewise
• Fortran Compiler: Likewise

Writing Tests

• Language Choice: Selecting which language to use for testing
• Writing Test Programs: Forging source files for compilers
• Running the Preprocessor: Detecting preprocessor symbols
• Running the Compiler: Detecting language or header features
• Running the Linker: Detecting library features
• Runtime: Testing for runtime features
• Systemology: A zoology of operating systems
• Multiple Cases: Tests for several possible values

Writing Test Programs

• Guidelines: General rules for writing test programs
• Test Functions: Avoiding pitfalls in test programs
• Generating Sources: Source program boilerplate

Results of Tests

• Defining Symbols: Defining C preprocessor symbols
• Setting Output Variables: Replacing variables in output files
• Special Chars in Variables: Characters to beware of in variables
• Caching Results: Speeding up subsequent configure runs
• Printing Messages: Notifying configure users

Caching Results

• Cache Variable Names: Shell variables used in caches
• Cache Files: Files configure uses for caching
• Cache Checkpointing: Loading and saving the cache file

Programming in M4

• M4 Quotation: Protecting macros from unwanted expansion
• Using autom4te: The Autoconf executables backbone
• Programming in M4sugar: Convenient pure M4 macros
• Debugging via autom4te: Figuring out what M4 was doing

Programming in M4sh

• Common Shell Constructs: Portability layer for common shell constructs
• Polymorphic Variables: Support for indirect variable names
• Initialization Macros: Macros to establish a sane shell environment
• File Descriptor Macros: File descriptor macros for input and output

M4 Quotation

• Active Characters: Characters that change the behavior of M4
• One Macro Call: Quotation and one macro call
• Quoting and Parameters: M4 vs. shell parameters
• Quotation and Nested Macros: Macros calling macros
• Changequote is Evil: Worse than INTERCAL: M4 + changequote
• Quadrigraphs: Another way to escape special characters
• Balancing Parentheses: Dealing with unbalanced parentheses
• Quotation Rule Of Thumb: One parenthesis, one quote

Using autom4te

• autom4te Invocation: A GNU M4 wrapper
• Customizing autom4te: Customizing the Autoconf package

Programming in M4sugar

• Redefined M4 Macros: M4 builtins changed in M4sugar
• Diagnostic Macros: Diagnostic messages from M4sugar
• Diversion support: Diversions in M4sugar
• Conditional constructs: Conditions in M4
• Looping constructs: Iteration in M4
• Evaluation Macros: More quotation and evaluation control
• Text processing Macros: String manipulation in M4
• Number processing Macros: Arithmetic computation in M4
• Set manipulation Macros: Set manipulation in M4
• Forbidden Patterns: Catching unexpanded macros

Writing Autoconf Macros

• Macro Definitions: Basic format of an Autoconf macro
• Macro Names: What to call your new macros
• Reporting Messages: Notifying autoconf users
• Dependencies Between Macros: What to do when macros depend on other macros
• Obsoleting Macros: Warning about old ways of doing things
• Coding Style: Writing Autoconf macros à la Autoconf

Dependencies Between Macros

• Prerequisite Macros: Ensuring required information
• Suggested Ordering: Warning about possible ordering problems
• One-Shot Macros: Ensuring a macro is called only once

Portable Shell Programming

• Shellology: A zoology of shells
• Here-Documents: Quirks and tricks
• File Descriptors: FDs and redirections
• File System Conventions: File names
• Shell Pattern Matching: Pattern matching
• Shell Substitutions: Variable and command expansions
• Assignments: Varying side effects of assignments
• Parentheses: Parentheses in shell scripts
• Slashes: Slashes in shell scripts
• Special Shell Variables: Variables you should not change
• Shell Functions: What to look out for if you use them
• Limitations of Builtins: Portable use of not so portable /bin/sh
• Limitations of Usual Tools: Portable use of portable tools

Portable Make Programming

• $< in Ordinary Make Rules: $< in ordinary rules
• Failure in Make Rules: Failing portably in rules
• Special Chars in Names: Special Characters in Macro Names
• Backslash-Newline-Newline: Empty last lines in macro definitions
• Backslash-Newline Comments: Spanning comments across line boundaries
• Long Lines in Makefiles: Line length limitations
• Macros and Submakes: make macro=value and submakes
• The Make Macro MAKEFLAGS: $(MAKEFLAGS) portability issues
• The Make Macro SHELL: $(SHELL) portability issues
• Parallel Make: Parallel make quirks
• Comments in Make Rules: Other problems with Make comments
• obj/ and Make: Don't name a subdirectory obj
• make -k Status: Exit status of ‘make -k’
• VPATH and Make: VPATH woes
• Single Suffix Rules: Single suffix rules and separated dependencies
• Timestamps and Make: Subsecond timestamp resolution

VPATH and Make

• Variables listed in VPATH: VPATH must be literal on ancient hosts
• VPATH and Double-colon: Problems with ‘::’ on ancient hosts
• $< in Explicit Rules: $< does not work in ordinary rules
• Automatic Rule Rewriting: VPATH goes wild on Solaris
• Tru64 Directory Magic: mkdir goes wild on Tru64
• Make Target Lookup: More details about VPATH lookup

Portable C and C++ Programming

• Varieties of Unportability: How to make your programs unportable
• Integer Overflow: When integers get too large
• Preprocessor Arithmetic: #if expression problems
• Null Pointers: Properties of null pointers
• Buffer Overruns: Subscript errors and the like
• Volatile Objects: volatile and signals
• Floating Point Portability: Portable floating-point arithmetic
• Exiting Portably: Exiting and the exit status

Manual Configuration

• Specifying Target Triplets: Specifying target triplets
• Canonicalizing: Getting the canonical system type
• Using System Type: What to do with the system type

Site Configuration

• Help Formatting: Customizing ‘configure --help’
• External Software: Working with other optional software
• Package Options: Selecting optional features
• Pretty Help Strings: Formatting help string
• Option Checking: Controlling checking of configure options
• Site Details: Configuring site details
• Transforming Names: Changing program names when installing
• Site Defaults: Giving configure local defaults

Transforming Program Names When Installing

• Transformation Options: configure options to transform names
• Transformation Examples: Sample uses of transforming names
• Transformation Rules: Makefile uses of transforming names

Running configure Scripts

• Basic Installation: Instructions for typical cases
• Compilers and Options: Selecting compilers and optimization
• Multiple Architectures: Compiling for multiple architectures at once
• Installation Names: Installing in different directories
• Optional Features: Selecting optional features
• Particular Systems: Particular systems
• System Type: Specifying the system type
• Sharing Defaults: Setting site-wide defaults for configure
• Defining Variables: Specifying the compiler etc.
• configure Invocation: Changing how configure runs

Obsolete Constructs

• Obsolete config.status Use: Obsolete convention for config.status
• acconfig Header: Additional entries in config.h.in
• autoupdate Invocation: Automatic update of configure.ac
• Obsolete Macros: Backward compatibility macros
• Autoconf 1: Tips for upgrading your files
• Autoconf 2.13: Some fresher tips

Upgrading From Version 1

• Changed File Names: Files you might rename
• Changed Makefiles: New things to put in Makefile.in
• Changed Macros: Macro calls you might replace
• Changed Results: Changes in how to check test results
• Changed Macro Writing: Better ways to write your own macros

Upgrading From Version 2.13

• Changed Quotation: Broken code which used to work
• New Macros: Interaction with foreign macros
• Hosts and Cross-Compilation: Bugward compatibility kludges
• AC_LIBOBJ vs LIBOBJS: LIBOBJS is a forbidden token
• AC_ACT_IFELSE vs AC_TRY_ACT: A more generic scheme for testing sources

Generating Test Suites with Autotest

• Using an Autotest Test Suite: Autotest and the user
• Writing Testsuites: Autotest macros
• testsuite Invocation: Running testsuite scripts
• Making testsuite Scripts: Using autom4te to create testsuite

Using an Autotest Test Suite

• testsuite Scripts: The concepts of Autotest
• Autotest Logs: Their contents

Frequent Autoconf Questions, with answers

• Distributing: Distributing configure scripts
• Why GNU M4: Why not use the standard M4?
• Bootstrapping: Autoconf and GNU M4 require each other?
• Why Not Imake: Why GNU uses configure instead of Imake
• Defining Directories: Passing datadir to program
• Autom4te Cache: What is it? Can I remove it?
• Present But Cannot Be Compiled: Compiler and Preprocessor Disagree
• Expanded Before Required: Expanded Before Required

History of Autoconf

• Genesis: Prehistory and naming of configure
• Exodus: The plagues of M4 and Perl
• Leviticus: The priestly code of portability arrives
• Numbers: Growth and contributors
• Deuteronomy: Approaching the promises of easy configuration

Indices

• Environment Variable Index: Index of environment variables used
• Output Variable Index: Index of variables set in output files
• Preprocessor Symbol Index: Index of C preprocessor symbols defined
• Autoconf Macro Index: Index of Autoconf macros
• M4 Macro Index: Index of M4, M4sugar, and M4sh macros
• Autotest Macro Index: Index of Autotest macros
• Program & Function Index: Index of those with portability problems
• Concept Index: General index