(autoconf.info)Top

Next: Introduction Up: (dir)


Autoconf
********

This manual is for GNU Autoconf (version 2.62, 5 April 2008), a package
for creating scripts to configure source code packages using templates
and an M4 macro package.

   Copyright (C) 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001,
2002, 2003, 2004, 2005, 2006, 2007, 2008 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.2 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."

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
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
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
Erlang Compiler and Interpreter: Likewise
Fortran 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
Programming in M4sh: Common shell Constructs
File Descriptor Macros: File descriptor macros for input and output

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
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
Forbidden Patterns: Catching unexpanded macros

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 a` 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
Here-Documents: Quirks and tricks
File Descriptors: FDs and redirections
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-Newline: Empty last lines in macro definitions
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
Comments in Make Rules: Other problems with Make comments
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

`VPATH' and Make

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

Manual Configuration

Specifying Names: Specifying the system type
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 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_FOO_IFELSE vs AC_TRY_FOO: 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

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

automatically generated by info2www