Autoconf

This file documents the GNU Autoconf package for creating scripts to configure source code packages using templates and the GNU M4 macro package. This is edition 2.52e, for Autoconf version 2.52e.

1. Introduction		Autoconf's purpose, strengths, and weaknesses
2. The GNU build system		A set of tools for portable software packages
3. Making configure Scripts		How to organize and produce Autoconf scripts
4. Initialization and Output Files		Initialization and output
5. Existing Tests		Macros that check for particular features
6. Writing Tests		How to write new feature checks
7. Results of Tests		What to do with results from feature checks
8. Programming in M4		Layers on top of which Autoconf is written
9. Writing Autoconf Macros		Adding new macros to Autoconf
10. Portable Shell Programming		Shell script portability pitfalls
11. Manual Configuration		Selecting features that can't be guessed
12. Site Configuration		Local defaults for configure
13. Running configure Scripts		How to use the Autoconf output
14. Recreating a Configuration		Recreating a configuration
15. Obsolete Constructs		Kept for backward compatibility
16. Generating Test Suites with Autotest		Creating portable test suites
17. Questions About Autoconf		Questions about Autoconf, with answers
18. History of Autoconf
A. Copying This Manual		How to make copies of this manual
B. Indices		Indices of symbols, concepts, etc.

The GNU build system

2.1 Automake		Escaping Makefile hell
2.2 Libtool		Building libraries portably
2.3 Pointers		More info on the GNU build system

Making configure Scripts

3.1 Writing `configure.ac'		What to put in an Autoconf input file
3.2 Using autoscan to Create `configure.ac'		Semi-automatic `configure.ac' writing
3.3 Using ifnames to List Conditionals		Listing the conditionals in source code
3.4 Using autoconf to Create configure		How to create configuration scripts
3.5 Using autoreconf to Update configure Scripts		Remaking multiple configure scripts

Writing `configure.ac'

3.1.1 A Shell Script Compiler		Autoconf as solution of a problem
3.1.2 The Autoconf Language		Programming in Autoconf
3.1.3 Standard `configure.ac' Layout		Standard organization of configure.ac

Initialization and Output Files

4.1 Initializing configure		Option processing etc.
4.2 Notices in configure		Copyright, version numbers in configure
4.3 Finding configure Input		Where Autoconf should find files
4.4 Outputting Files		Outputting results from the configuration
4.5 Taking Configuration Actions		Preparing the output based on results
4.6 Creating Configuration Files		Creating output files
4.7 Substitutions in Makefiles		Using output variables in `Makefile's
4.8 Configuration Header Files		Creating a configuration header file
4.9 Running Arbitrary Configuration Commands		Running arbitrary instantiation commands
4.10 Creating Configuration Links		Links depending from the configuration
4.11 Configuring Other Packages in Subdirectories		Configuring independent packages together
4.12 Default Prefix		Changing the default installation prefix

Substitutions in Makefiles

4.7.1 Preset Output Variables		Output variables that are always set
4.7.2 Installation Directory Variables		Other preset output variables
4.7.3 Build Directories		Supporting multiple concurrent compiles
4.7.4 Automatic Remaking		Makefile rules for configuring

Configuration Header Files

4.8.1 Configuration Header Templates		Input for the configuration headers
4.8.2 Using autoheader to Create `config.h.in'		How to create configuration templates
4.8.3 Autoheader Macros		How to specify CPP templates

Existing Tests

5.1 Common Behavior		Macros' standard schemes
5.2 Alternative Programs		Selecting between alternative programs
5.3 Files		Checking for the existence of files
5.4 Library Files		Library archives that might be missing
5.5 Library Functions		C library functions that might be missing
5.6 Header Files		Header files that might be missing
5.7 Declarations		Declarations that may be missing
5.8 Structures		Structures or members that might be missing
5.9 Types		Types that might be missing
5.10 Compilers and Preprocessors		Checking for compiling programs
5.11 System Services		Operating system services
5.12 UNIX Variants		Special kludges for specific UNIX variants

Common Behavior

5.1.1 Standard Symbols		Symbols defined by the macros
5.1.2 Default Includes		Includes used by the generic macros

Alternative Programs

5.2.1 Particular Program Checks		Special handling to find certain programs
5.2.2 Generic Program and File Checks		How to find other programs

Library Functions

5.5.1 Portability of C Functions		Pitfalls with usual functions
5.5.2 Particular Function Checks		Special handling to find certain functions
5.5.3 Generic Function Checks		How to find other functions

Header Files

5.6.1 Particular Header Checks		Special handling to find certain headers
5.6.2 Generic Header Checks		How to find other headers

Declarations

5.7.1 Particular Declaration Checks		Macros to check for certain declarations
5.7.2 Generic Declaration Checks		How to find other declarations

Structures

5.8.1 Particular Structure Checks		Macros to check for certain structure members
5.8.2 Generic Structure Checks		How to find other structure members

Types

5.9.1 Particular Type Checks		Special handling to find certain types
5.9.2 Generic Type Checks		How to find other types

Compilers and Preprocessors

5.10.1 Generic Compiler Characteristics		Language independent tests
5.10.2 C Compiler Characteristics		Checking its characteristics
5.10.3 C++ Compiler Characteristics		Likewise
5.10.4 Fortran 77 Compiler Characteristics		Likewise

Writing Tests

6.1 Examining Declarations		Detecting header files and declarations
6.2 Examining Syntax		Detecting language syntax features
6.3 Examining Libraries		Detecting functions and global variables
6.4 Checking Run Time Behavior		Testing for run-time features
6.5 Systemology		A zoology of operating systems
6.6 Multiple Cases		Tests for several possible values
6.7 Language Choice		Selecting which language to use for testing

Checking Run Time Behavior

6.4.1 Running Test Programs		Running test programs
6.4.2 Guidelines for Test Programs		General rules for writing test programs
6.4.3 Test Functions		Avoiding pitfalls in test programs

Results of Tests

7.1 Defining C Preprocessor Symbols		Defining C preprocessor symbols
7.2 Setting Output Variables		Replacing variables in output files
7.3 Caching Results		Speeding up subsequent configure runs
7.4 Printing Messages		Notifying configure users

Caching Results

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

Programming in M4

8.1 M4 Quotation		Protecting macros from unwanted expansion
8.2 Programming in M4sugar		Convenient pure M4 macros
8.3 Programming in M4sh		Common Shell Constructs

M4 Quotation

8.1.1 Active Characters		Characters that change the behavior of m4
8.1.2 One Macro Call		Quotation and one macro call
8.1.3 Quotation and Nested Macros		Macros calling macros
8.1.4 Quadrigraphs		Another way to escape special characters
8.1.5 Quotation Rule Of Thumb		One parenthesis, one quote

Programming in M4sugar

8.2.1 Redefined M4 Macros		M4 builtins changed in M4sugar
8.2.2 Forbidden Patterns		Catching unexpanded macros

Writing Autoconf Macros

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

Dependencies Between Macros

9.4.1 Prerequisite Macros		Ensuring required information
9.4.2 Suggested Ordering		Warning about possible ordering problems

Portable Shell Programming

10.1 Shellology		A zoology of shells
10.2 Here-Documents		Quirks and tricks
10.3 File Descriptors		FDs and redirections
10.4 File System Conventions		File- and pathnames
10.5 Shell Substitutions		Variable and command expansions
10.6 Assignments		Varying side effects of assignments
10.7 Special Shell Variables		Variables you should not change
10.8 Limitations of Shell Builtins		Portable use of not so portable /bin/sh
10.9 Limitations of Usual Tools		Portable use of portable tools
10.10 Limitations of Make		Portable Makefiles

Manual Configuration

11.1 Specifying the System Type		Specifying the system type
11.2 Getting the Canonical System Type		Getting the canonical system type
11.3 Using the System Type		What to do with the system type

Site Configuration

12.1 Working With External Software		Working with other optional software
12.2 Choosing Package Options		Selecting optional features
12.3 Making Your Help Strings Look Pretty		Formating help string
12.4 Configuring Site Details		Configuring site details
12.5 Transforming Program Names When Installing		Changing program names when installing
12.6 Setting Site Defaults		Giving configure local defaults

Transforming Program Names When Installing

12.5.1 Transformation Options		configure options to transform names
12.5.2 Transformation Examples		Sample uses of transforming names
12.5.3 Transformation Rules		`Makefile' uses of transforming names

Running configure Scripts

13.1 Basic Installation		Instructions for typical cases
13.2 Compilers and Options		Selecting compilers and optimization
13.3 Compiling For Multiple Architectures		Compiling for multiple architectures at once
13.4 Installation Names		Installing in different directories
13.5 Optional Features		Selecting optional features
13.6 Specifying the System Type		Specifying the system type
13.7 Sharing Defaults		Setting site-wide defaults for configure
13.8 Defining Variables		Specifying the compiler etc.
13.9 configure Invocation		Changing how configure runs

Obsolete Constructs

15.1 Obsolete `config.status' Invocation		Different calling convention
15.2 `acconfig.h'		Additional entries in `config.h.in'
15.3 Using autoupdate to Modernize `configure.ac'		Automatic update of `configure.ac'
15.4 Obsolete Macros		Backward compatibility macros
15.5 Upgrading From Version 1		Tips for upgrading your files
15.6 Upgrading From Version 2.13		Some fresher tips

Upgrading From Version 1

15.5.1 Changed File Names		Files you might rename
15.5.2 Changed Makefiles		New things to put in `Makefile.in'
15.5.3 Changed Macros		Macro calls you might replace
15.5.4 Changed Results		Changes in how to check test results
15.5.5 Changed Macro Writing		Better ways to write your own macros

Upgrading From Version 2.13

15.6.1 Changed Quotation		Broken code which used to work
15.6.2 New Macros		Interaction with foreign macros

Generating Test Suites with Autotest

16.1 testsuite Scripts		The concepts of Autotest
16.2 Writing `testsuite.at'		Autotest macros
16.3 Running testsuite Scripts		Running testsuite scripts
16.4 Making testsuite Scripts		Using autom4te to create testsuite

Questions About Autoconf

17.1 Distributing configure Scripts		Distributing configure scripts
17.2 Why Require GNU M4?		Why not use the standard M4?
17.3 How Can I Bootstrap?		Autoconf and GNU M4 require each other?
17.4 Why Not Imake?		Why GNU uses configure instead of Imake

History of Autoconf

18.1 Genesis		Prehistory and naming of configure
18.2 Exodus		The plagues of M4 and Perl
18.3 Leviticus		The priestly code of portability arrives
18.4 Numbers		Growth and contributors
18.5 Deuteronomy		Approaching the promises of easy configuration

Copying This Manual

A.1 GNU Free Documentation License

License for copying this manual

Indices

B.1 Environment Variable Index		Index of environment variables used
B.2 Output Variable Index		Index of variables set in output files
B.3 Preprocessor Symbol Index		Index of C preprocessor symbols defined
B.4 Autoconf Macro Index		Index of Autoconf macros
B.5 M4 Macro Index		Index of M4, M4sugar, and M4sh macros
B.6 Autotest Macro Index		Index of Autotest macros
B.7 Program and Function Index		Index of those with portability problems
B.8 Concept Index		General index