| [Top] | [Contents] | [Index] | [ ? ] |
Autoconf
This manual (21 September 2010) is for GNU Autoconf (version 2.68), 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, 2010 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.”
| 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. Programming in M4sh | Shell portability layer | |
| 10. Writing Autoconf Macros | Adding new macros to Autoconf | |
| 11. Portable Shell Programming | Shell script portability pitfalls | |
| 12. Portable Make Programming | Makefile portability pitfalls | |
| 13. Portable C and C++ Programming | C and C++ portability pitfalls | |
| 14. Manual Configuration | Selecting features that can’t be guessed | |
| 15. Site Configuration | Local defaults for configure
| |
16. Running configure Scripts | How to use the Autoconf output | |
| 17. config.status Invocation | Recreating a configuration | |
| 18. Obsolete Constructs | Kept for backward compatibility | |
| 19. Generating Test Suites with Autotest | Creating portable test suites | |
| 20. Frequent Autoconf Questions, with answers | ||
| 21. History of Autoconf | ||
| A. GNU Free Documentation License | License for copying this manual | |
| B. Indices | Indices of symbols, concepts, etc. | |
— The Detailed Node Listing — The GNU Build System | ||
|---|---|---|
| 2.1 Automake | Escaping makefile hell | |
| 2.2 Gnulib | The GNU portability library | |
| 2.3 Libtool | Building libraries portably | |
| 2.4 Pointers | More info on the GNU build system | |
Making | ||
| 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 Dealing with Autoconf versions | ||
4.3 Notices in configure | Copyright, version numbers in configure
| |
4.4 Finding configure Input | Where Autoconf should find files | |
| 4.5 Outputting Files | Outputting results from the configuration | |
| 4.6 Performing Configuration Actions | Preparing the output based on results | |
| 4.7 Creating Configuration Files | Creating output files | |
| 4.8 Substitutions in Makefiles | Using output variables in makefiles | |
| 4.9 Configuration Header Files | Creating a configuration header file | |
| 4.10 Running Arbitrary Configuration Commands | Running arbitrary instantiation commands | |
| 4.11 Creating Configuration Links | Links depending on the configuration | |
| 4.12 Configuring Other Packages in Subdirectories | Configuring independent packages together | |
| 4.13 Default Prefix | Changing the default installation prefix | |
Substitutions in Makefiles | ||
| 4.8.1 Preset Output Variables | Output variables that are always set | |
| 4.8.2 Installation Directory Variables | Other preset output variables | |
| 4.8.3 Changed Directory Variables | Warnings about ‘datarootdir’ | |
| 4.8.4 Build Directories | Supporting multiple concurrent compiles | |
| 4.8.5 Automatic Remaking | Makefile rules for configuring | |
Configuration Header Files | ||
| 4.9.1 Configuration Header Templates | Input for the configuration headers | |
4.9.2 Using autoheader to Create ‘config.h.in’ | How to create configuration templates | |
| 4.9.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 Posix Variants | Special kludges for specific Posix variants | |
| 5.13 Erlang Libraries | Checking for the existence of Erlang libraries | |
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 Portability of Headers | Collected knowledge on common headers | |
| 5.6.2 Particular Header Checks | Special handling to find certain headers | |
| 5.6.3 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 Specific Compiler Characteristics | Some portability issues | |
| 5.10.2 Generic Compiler Characteristics | Language independent tests and features | |
| 5.10.3 C Compiler Characteristics | Checking its characteristics | |
| 5.10.4 C++ Compiler Characteristics | Likewise | |
| 5.10.5 Objective C Compiler Characteristics | Likewise | |
| 5.10.6 Objective C++ Compiler Characteristics | Likewise | |
| 5.10.7 Erlang Compiler and Interpreter Characteristics | Likewise | |
| 5.10.8 Fortran Compiler Characteristics | Likewise | |
Writing Tests | ||
| 6.1 Language Choice | Selecting which language to use for testing | |
| 6.2 Writing Test Programs | Forging source files for compilers | |
| 6.3 Running the Preprocessor | Detecting preprocessor symbols | |
| 6.4 Running the Compiler | Detecting language or header features | |
| 6.5 Running the Linker | Detecting library features | |
| 6.6 Checking Runtime Behavior | Testing for runtime features | |
| 6.7 Systemology | A zoology of operating systems | |
| 6.8 Multiple Cases | Tests for several possible values | |
Writing Test Programs | ||
| 6.2.1 Guidelines for Test Programs | General rules for writing test programs | |
| 6.2.2 Test Functions | Avoiding pitfalls in test programs | |
| 6.2.3 Generating Sources | Source program boilerplate | |
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 Special Characters in Output Variables | Characters to beware of in variables | |
| 7.4 Caching Results | Speeding up subsequent configure runs
| |
| 7.5 Printing Messages | Notifying configure users
| |
Caching Results | ||
| 7.4.1 Cache Variable Names | Shell variables used in caches | |
| 7.4.2 Cache Files | Files configure uses for caching
| |
| 7.4.3 Cache Checkpointing | Loading and saving the cache file | |
Programming in M4 | ||
| 8.1 M4 Quotation | Protecting macros from unwanted expansion | |
8.2 Using autom4te | The Autoconf executables backbone | |
| 8.3 Programming in M4sugar | Convenient pure M4 macros | |
| 8.4 Debugging via autom4te | Figuring out what M4 was doing | |
Programming in M4sh | ||
| 9.1 Common Shell Constructs | Portability layer for common shell constructs | |
| 9.2 Support for indirect variable names | ||
| 9.3 Initialization Macros | Macros to establish a sane shell environment | |
| 9.4 File Descriptor Macros | File descriptor macros for input and output | |
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 Quoting and Parameters | M4 vs. shell parameters | |
| 8.1.4 Quotation and Nested Macros | Macros calling macros | |
8.1.5 changequote is Evil | Worse than INTERCAL: M4 + changequote | |
| 8.1.6 Quadrigraphs | Another way to escape special characters | |
| 8.1.7 Dealing with unbalanced parentheses | ||
| 8.1.8 Quotation Rule Of Thumb | One parenthesis, one quote | |
Using | ||
8.2.1 Invoking autom4te | A GNU M4 wrapper | |
8.2.2 Customizing autom4te | Customizing the Autoconf package | |
Programming in M4sugar | ||
| 8.3.1 Redefined M4 Macros | M4 builtins changed in M4sugar | |
| 8.3.2 Diagnostic messages from M4sugar | ||
| 8.3.3 Diversion support | Diversions in M4sugar | |
| 8.3.4 Conditional constructs | Conditions in M4 | |
| 8.3.5 Looping constructs | Iteration in M4 | |
| 8.3.6 Evaluation Macros | More quotation and evaluation control | |
| 8.3.7 String manipulation in M4 | ||
| 8.3.8 Arithmetic computation in M4 | ||
| 8.3.9 Set manipulation in M4 | ||
| 8.3.10 Forbidden Patterns | Catching unexpanded macros | |
Writing Autoconf Macros | ||
| 10.1 Macro Definitions | Basic format of an Autoconf macro | |
| 10.2 Macro Names | What to call your new macros | |
| 10.3 Reporting Messages | Notifying autoconf users
| |
| 10.4 Dependencies Between Macros | What to do when macros depend on other macros | |
| 10.5 Obsoleting Macros | Warning about old ways of doing things | |
| 10.6 Coding Style | Writing Autoconf macros à la Autoconf | |
Dependencies Between Macros | ||
| 10.4.1 Prerequisite Macros | Ensuring required information | |
| 10.4.2 Suggested Ordering | Warning about possible ordering problems | |
| 10.4.3 One-Shot Macros | Ensuring a macro is called only once | |
Portable Shell Programming | ||
| 11.1 Shellology | A zoology of shells | |
| 11.2 Here-Documents | Quirks and tricks | |
| 11.3 File Descriptors | FDs and redirections | |
| 11.4 File System Conventions | File names | |
| 11.5 Shell Pattern Matching | Pattern matching | |
| 11.6 Shell Substitutions | Variable and command expansions | |
| 11.7 Assignments | Varying side effects of assignments | |
| 11.8 Parentheses in Shell Scripts | Parentheses in shell scripts | |
| 11.9 Slashes in Shell Scripts | Slashes in shell scripts | |
| 11.10 Special Shell Variables | Variables you should not change | |
| 11.11 Shell Functions | What to look out for if you use them | |
| 11.12 Limitations of Shell Builtins | Portable use of not so portable /bin/sh | |
| 11.13 Limitations of Usual Tools | Portable use of portable tools | |
Portable Make Programming | ||
12.1 $< in Ordinary Make Rules | $< in ordinary rules | |
| 12.2 Failure in Make Rules | Failing portably in rules | |
| 12.3 Special Characters in Make Macro Names | Special Characters in Macro Names | |
| 12.4 Backslash-Newline-Newline in Make Macro Values | Empty last lines in macro definitions | |
| 12.5 Backslash-Newline in Make Comments | Spanning comments across line boundaries | |
| 12.6 Long Lines in Makefiles | Line length limitations | |
12.7 make macro=value and Submakes | make macro=value and submakes
| |
| 12.8 The Make Macro MAKEFLAGS | $(MAKEFLAGS) portability issues
| |
12.9 The Make Macro SHELL | $(SHELL) portability issues
| |
| 12.10 Parallel Make | Parallel make quirks
| |
| 12.11 Comments in Make Rules | Other problems with Make comments | |
| 12.12 Newlines in Make Rules | Using literal newlines in rules | |
| 12.13 The ‘obj/’ Subdirectory and Make | Don’t name a subdirectory ‘obj’ | |
12.14 Exit Status of make -k | Exit status of ‘make -k’ | |
12.15 VPATH and Make | VPATH woes
| |
| 12.16 Single Suffix Rules and Separated Dependencies | Single suffix rules and separated dependencies | |
| 12.17 Timestamp Resolution and Make | Subsecond timestamp resolution | |
| ||
12.15.1 Variables listed in VPATH | VPATH must be literal on ancient hosts
| |
12.15.2 VPATH and Double-colon Rules | Problems with ‘::’ on ancient hosts | |
12.15.3 $< Not Supported in Explicit Rules | $< does not work in ordinary rules
| |
| 12.15.4 Automatic Rule Rewriting | VPATH goes wild on Solaris
| |
12.15.5 Tru64 make Creates Prerequisite Directories Magically | mkdir goes wild on Tru64
| |
| 12.15.6 Make Target Lookup | More details about VPATH lookup
| |
Portable C and C++ Programming | ||
| 13.1 Varieties of Unportability | How to make your programs unportable | |
| 13.2 Integer Overflow | When integers get too large | |
| 13.3 Preprocessor Arithmetic | #if expression problems
| |
| 13.4 Properties of Null Pointers | Properties of null pointers | |
| 13.5 Buffer Overruns and Subscript Errors | Subscript errors and the like | |
| 13.6 Volatile Objects | volatile and signals
| |
| 13.7 Floating Point Portability | Portable floating-point arithmetic | |
| 13.8 Exiting Portably | Exiting and the exit status | |
Manual Configuration | ||
| 14.1 Specifying target triplets | ||
| 14.2 Getting the Canonical System Type | Getting the canonical system type | |
| 14.3 Using the System Type | What to do with the system type | |
Site Configuration | ||
| 15.1 Controlling Help Output | Customizing ‘configure --help’ | |
| 15.2 Working With External Software | Working with other optional software | |
| 15.3 Choosing Package Options | Selecting optional features | |
| 15.4 Making Your Help Strings Look Pretty | Formatting help string | |
15.5 Controlling Checking of configure Options | Controlling checking of configure options
| |
| 15.6 Configuring Site Details | Configuring site details | |
| 15.7 Transforming Program Names When Installing | Changing program names when installing | |
| 15.8 Setting Site Defaults | Giving configure local defaults
| |
Transforming Program Names When Installing | ||
| 15.7.1 Transformation Options | configure options to transform names
| |
| 15.7.2 Transformation Examples | Sample uses of transforming names | |
| 15.7.3 Transformation Rules | Makefile uses of transforming names | |
Running | ||
| 16.1 Basic Installation | Instructions for typical cases | |
| 16.2 Compilers and Options | Selecting compilers and optimization | |
| 16.3 Compiling For Multiple Architectures | Compiling for multiple architectures at once | |
| 16.4 Installation Names | Installing in different directories | |
| 16.5 Optional Features | Selecting optional features | |
| 16.6 Particular systems | ||
| 16.7 Specifying the System Type | Specifying the system type | |
| 16.8 Sharing Defaults | Setting site-wide defaults for configure
| |
| 16.9 Defining Variables | Specifying the compiler etc. | |
16.10 configure Invocation | Changing how configure runs
| |
Obsolete Constructs | ||
| 18.1 Obsolete ‘config.status’ Invocation | Obsolete convention for config.status
| |
| 18.2 ‘acconfig.h’ | Additional entries in ‘config.h.in’ | |
18.3 Using autoupdate to Modernize ‘configure.ac’ | Automatic update of ‘configure.ac’ | |
| 18.4 Obsolete Macros | Backward compatibility macros | |
| 18.5 Upgrading From Version 1 | Tips for upgrading your files | |
| 18.6 Upgrading From Version 2.13 | Some fresher tips | |
Upgrading From Version 1 | ||
| 18.5.1 Changed File Names | Files you might rename | |
| 18.5.2 Changed Makefiles | New things to put in ‘Makefile.in’ | |
| 18.5.3 Changed Macros | Macro calls you might replace | |
| 18.5.4 Changed Results | Changes in how to check test results | |
| 18.5.5 Changed Macro Writing | Better ways to write your own macros | |
Upgrading From Version 2.13 | ||
| 18.6.1 Changed Quotation | Broken code which used to work | |
| 18.6.2 New Macros | Interaction with foreign macros | |
| 18.6.3 Hosts and Cross-Compilation | Bugward compatibility kludges | |
18.6.4 AC_LIBOBJ vs. LIBOBJS | LIBOBJS is a forbidden token | |
18.6.5 AC_ACT_IFELSE vs. AC_TRY_ACT | A more generic scheme for testing sources | |
Generating Test Suites with Autotest | ||
| 19.1 Using an Autotest Test Suite | Autotest and the user | |
| 19.2 Writing ‘testsuite.at’ | Autotest macros | |
19.3 Running testsuite Scripts | Running testsuite scripts
| |
19.4 Making testsuite Scripts | Using autom4te to create testsuite
| |
Using an Autotest Test Suite | ||
19.1.1 testsuite Scripts | The concepts of Autotest | |
| 19.1.2 Autotest Logs | Their contents | |
Frequent Autoconf Questions, with answers | ||
20.1 Distributing configure Scripts | Distributing configure scripts
| |
| 20.2 Why Require GNU M4? | Why not use the standard M4? | |
| 20.3 How Can I Bootstrap? | Autoconf and GNU M4 require each other? | |
| 20.4 Why Not Imake? | Why GNU uses configure instead of Imake
| |
20.5 How Do I #define Installation Directories? | Passing datadir to program
| |
| 20.6 What is ‘autom4te.cache’? | What is it? Can I remove it? | |
| 20.7 Header Present But Cannot Be Compiled | Compiler and Preprocessor Disagree | |
| 20.8 Expanded Before Required | ||
20.9 Debugging configure scripts | ||
History of Autoconf | ||
| 21.1 Genesis | Prehistory and naming of configure
| |
| 21.2 Exodus | The plagues of M4 and Perl | |
| 21.3 Leviticus | The priestly code of portability arrives | |
| 21.4 Numbers | Growth and contributors | |
| 21.5 Deuteronomy | Approaching the promises of easy configuration | |
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 Cache Variable Index | Index of documented cache variables | |
| B.5 Autoconf Macro Index | Index of Autoconf macros | |
| B.6 M4 Macro Index | Index of M4, M4sugar, and M4sh macros | |
| B.7 Autotest Macro Index | Index of Autotest macros | |
| B.8 Program and Function Index | Index of those with portability problems | |
| B.9 Concept Index | General index | |
| [Top] | [Contents] | [Index] | [ ? ] |