(autoconf.info)Top


Autoconf
********

This manual (28 January 2021) is for GNU Autoconf (version 2.71), a
package for creating scripts to configure source code packages using
templates and an M4 macro package.

   Copyright © 1992–1996, 1998–2017, 2020–2021 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, no Front-Cover texts, and
     no Back-Cover Texts.  A copy of the license is included in the
     section entitled “GNU Free Documentation License.”

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
C and Posix Variants: Kludges for C and 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
Objective C++ Compiler: Likewise
Erlang Compiler and Interpreter: Likewise
Fortran Compiler: Likewise
Go 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

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

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

Writing Autoconf Macros

Macro Definitions: Basic format of an Autoconf macro
Macro Names: What to call your new macros
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
Invoking the Shell: Invoking the shell as a command
Here-Documents: Quirks and tricks
File Descriptors: FDs and redirections
Signal Handling: Shells, signals, and headaches
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-Empty: Empty lines after backslash-newline
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
Newlines in Make Rules: Using literal newlines in rules
Comments in Make Macros: Other problems with Make comments in macros
Trailing whitespace in Make Macros: Macro substitution problems
Command-line Macros and whitespace: Whitespace trimming of values
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: Sub-second 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

Integer Overflow

Integer Overflow Basics: Why integer overflow is a problem
Signed Overflow Examples: Examples of code assuming wraparound
Optimization and Wraparound: Optimizations that break uses of wraparound
Signed Overflow Advice: Practical advice for signed overflow issues
Signed Integer Division: ‘INT_MIN / -1’ and ‘INT_MIN % -1’

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
Debugging: Debugging ‘configure’ scripts

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
Cache Variable Index: Index of documented cache variables
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