File: autoconf.info,  Node: Top,  Next: Introduction,  Up: (dir)

Autoconf
********

This manual (4 December 2023) is for GNU Autoconf (version 2.72), a
package for creating scripts to configure source code packages using
templates and an M4 macro package.

   Copyright © 1992-1996, 1998-2017, 2020-2023 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."

* Menu:

* 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 ‘configure’ Scripts

* 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’

* 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

‘VPATH’ and Make

* 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 ‘configure’ Scripts

* 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
* System Types::                Specifying a 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