configure Scripts
configureconfigure$< in Ordinary Make Rulesmake macro=value and SubmakesSHELLmake -kVPATH and Make
configure Scripts
Next: Introduction, Up: (dir) [Contents][Index]
This manual (7 December 2020) is for GNU Autoconf (version 2.70), a package for creating scripts to configure source code packages using templates and an M4 macro package.
Copyright © 1992–1996, 1998–2017, 2020 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 | |
| • 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 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 | |
| ||
| • 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: Introduction, Up: (dir) [Contents][Index]