configure Scripts
configureconfigureconfigure Input$< in Ordinary Make Rulesmake macro=value and SubmakesSHELLmake -kVPATH and Make
configure Scripts
Next: Introduction, Up: (dir) [Contents][Index]
This manual (31 August 2014) is for GNU Autoconf (version 2.69), a package for creating scripts to configure source code packages using templates and an M4 macro package.
Copyright © 1992-1996, 1998-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, 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 | ||
| • 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 | |
| • 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 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 | |
| • 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 | |
| • 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: | Subsecond timestamp resolution | |
| ||
| • 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 | ||
| • 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 | |
Next: The GNU Build System, Previous: Top, Up: Top [Contents][Index]
A physicist, an engineer, and a computer scientist were discussing the nature of God. “Surely a Physicist,” said the physicist, “because early in the Creation, God made Light; and you know, Maxwell’s equations, the dual nature of electromagnetic waves, the relativistic consequences...” “An Engineer!,” said the engineer, “because before making Light, God split the Chaos into Land and Water; it takes a hell of an engineer to handle that big amount of mud, and orderly separation of solids from liquids...” The computer scientist shouted: “And the Chaos, where do you think it was coming from, hmm?”
—Anonymous
Autoconf is a tool for producing shell scripts that automatically configure software source code packages to adapt to many kinds of Posix-like systems. The configuration scripts produced by Autoconf are independent of Autoconf when they are run, so their users do not need to have Autoconf.
The configuration scripts produced by Autoconf require no manual user intervention when run; they do not normally even need an argument specifying the system type. Instead, they individually test for the presence of each feature that the software package they are for might need. (Before each check, they print a one-line message stating what they are checking for, so the user doesn’t get too bored while waiting for the script to finish.) As a result, they deal well with systems that are hybrids or customized from the more common Posix variants. There is no need to maintain files that list the features supported by each release of each variant of Posix.
For each software package that Autoconf is used with, it creates a configuration script from a template file that lists the system features that the package needs or can use. After the shell code to recognize and respond to a system feature has been written, Autoconf allows it to be shared by many software packages that can use (or need) that feature. If it later turns out that the shell code needs adjustment for some reason, it needs to be changed in only one place; all of the configuration scripts can be regenerated automatically to take advantage of the updated code.
Those who do not understand Autoconf are condemned to reinvent it, poorly. The primary goal of Autoconf is making the user’s life easier; making the maintainer’s life easier is only a secondary goal. Put another way, the primary goal is not to make the generation of configure automatic for package maintainers (although patches along that front are welcome, since package maintainers form the user base of Autoconf); rather, the goal is to make configure painless, portable, and predictable for the end user of each autoconfiscated package. And to this degree, Autoconf is highly successful at its goal — most complaints to the Autoconf list are about difficulties in writing Autoconf input, and not in the behavior of the resulting configure. Even packages that don’t use Autoconf will generally provide a configure script, and the most common complaint about these alternative home-grown scripts is that they fail to meet one or more of the GNU Coding Standards (see Configuration in The GNU Coding Standards) that users have come to expect from Autoconf-generated configure scripts.
The Metaconfig package is similar in purpose to Autoconf, but the scripts it produces require manual user intervention, which is quite inconvenient when configuring large source trees. Unlike Metaconfig scripts, Autoconf scripts can support cross-compiling, if some care is taken in writing them.
Autoconf does not solve all problems related to making portable software packages—for a more complete solution, it should be used in concert with other GNU build tools like Automake and Libtool. These other tools take on jobs like the creation of a portable, recursi