| [Top] | [Contents] | [Index] | [ ? ] |
@setcontentsaftertitlepage
This manual is for GNU Autoconf (version 2.57, 2 December 2002), 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 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.1 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 freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development."
| 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. Frequent Autoconf Questions, 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 Detailed Node Listing --- 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 | ||
| 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 Performing 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 on 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 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 | |
| 5.10.3 C Compiler Characteristics | Checking its characteristics | |
| 5.10.4 C++ Compiler Characteristics | Likewise | |
| 5.10.5 Fortran 77 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 Run Time Behavior | Testing for run-time 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 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 Using autom4te | The Autoconf executables backbone | |
| 8.3 Programming in M4sugar | Convenient pure M4 macros | |
| 8.4 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 changequote is Evil | Worse than INTERCAL: M4 + changequote | |
| 8.1.5 Quadrigraphs | Another way to escape special characters | |
| 8.1.6 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 Evaluation Macros | More quotation and evaluation control | |
| 8.3.3 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 | Formatting 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 | ||
| 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 | |
| 15.6.3 Hosts and Cross-Compilation | Bugward compatibility kludges | |
15.6.4 AC_LIBOBJ vs. LIBOBJS | LIBOBJS is a forbidden token | |
15.6.5 AC_FOO_IFELSE vs. AC_TRY_FOO | A more generic scheme for testing sources | |
Generating Test Suites with Autotest | ||
| 16.1 Using an Autotest Test Suite | Autotest and the user | |
| 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 | |
Using an Autotest Test Suite | ||
16.1.1 testsuite Scripts | The concepts of Autotest | |
| 16.1.2 Autotest Logs | Their contents | |
Frequent Autoconf Questions, with answers | ||
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 | |
17.5 How Do I #define Installation Directories? | Passing datadir to program | |
| 17.6 What is `autom4te.cache'? | What is it? Can I remove it? | |
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 | |
| [Top] | [Contents] | [Index] | [ ? ] |
This document was generated by John Paul Wallington on October, 29 2003 using texi2html 1.67.