1 1 Autoconf 1 ******** 1 1 This manual (24 April 2012) is for GNU Autoconf (version 2.69), a 1 package for creating scripts to configure source code packages using 1 templates and an M4 macro package. 1 1 Copyright (C) 1992-1996, 1998-2012 Free Software Foundation, Inc. 1 1 Permission is granted to copy, distribute and/or modify this 1 document under the terms of the GNU Free Documentation License, 1 Version 1.3 or any later version published by the Free Software 1 Foundation; with no Invariant Sections, no Front-Cover texts, and 1 no Back-Cover Texts. A copy of the license is included in the 1 section entitled "GNU Free Documentation License." 1
1 · 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. 1 1 --- The Detailed Node Listing --- 1 1 The GNU Build System 1 · Automake Escaping makefile hell · Gnulib The GNU portability library · Libtool Building libraries portably · Pointers More info on the GNU build system 1 1 Making `configure' Scripts 1 · 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 1 1 Writing `configure.ac' 1 · Shell Script Compiler Autoconf as solution of a problem · Autoconf Language Programming in Autoconf · Autoconf Input Layout Standard organization of `configure.ac' 1 1 Initialization and Output Files 1 · 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 1 1 Substitutions in Makefiles 1 · 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 1 1 Configuration Header Files 1 · Header Templates Input for the configuration headers · autoheader Invocation How to create configuration templates · Autoheader Macros How to specify CPP templates 1 1 Existing Tests 1 · 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 1 1 Common Behavior 1 · Standard Symbols Symbols defined by the macros · Default Includes Includes used by the generic macros 1 1 Alternative Programs 1 · Particular Programs Special handling to find certain programs · Generic Programs How to find other programs 1 1 Library Functions 1 · Function Portability Pitfalls with usual functions · Particular Functions Special handling to find certain functions · Generic Functions How to find other functions 1 1 Header Files 1 · Header Portability Collected knowledge on common headers · Particular Headers Special handling to find certain headers · Generic Headers How to find other headers 1 1 Declarations 1 · Particular Declarations Macros to check for certain declarations · Generic Declarations How to find other declarations 1 1 Structures 1 · Particular Structures Macros to check for certain structure members · Generic Structures How to find other structure members 1 1 Types 1 · Particular Types Special handling to find certain types · Generic Types How to find other types 1 1 Compilers and Preprocessors 1 · 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 1 1 Writing Tests 1 · 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 1 1 Writing Test Programs 1 · Guidelines General rules for writing test programs · Test Functions Avoiding pitfalls in test programs · Generating Sources Source program boilerplate 1 1 Results of Tests 1 · 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 1 1 Caching Results 1 · Cache Variable Names Shell variables used in caches · Cache Files Files `configure' uses for caching · Cache Checkpointing Loading and saving the cache file 1 1 Programming in M4 1 · 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 1 1 M4 Quotation 1 · 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 1 1 Using `autom4te' 1 · autom4te Invocation A GNU M4 wrapper · Customizing autom4te Customizing the Autoconf package 1 1 Programming in M4sugar 1 · 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 1 1 Programming in M4sh 1 · 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 1 1 Writing Autoconf Macros 1 · 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 1 1 Dependencies Between Macros 1 · Prerequisite Macros Ensuring required information · Suggested Ordering Warning about possible ordering problems · One-Shot Macros Ensuring a macro is called only once 1 1 Portable Shell Programming 1 · 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 1 1 Portable Make Programming 1 · $< 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 Subsecond timestamp resolution 1 1 `VPATH' and Make 1 · 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 1 1 Portable C and C++ Programming 1 · 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 1 1 Integer Overflow 1 · 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' 1 1 Manual Configuration 1 · Specifying Target Triplets Specifying target triplets · Canonicalizing Getting the canonical system type · Using System Type What to do with the system type 1 1 Site Configuration 1 · 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 1 1 Transforming Program Names When Installing 1 · Transformation Options `configure' options to transform names · Transformation Examples Sample uses of transforming names · Transformation Rules Makefile uses of transforming names 1 1 Running `configure' Scripts 1 · 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 1 1 Obsolete Constructs 1 · 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 1 1 Upgrading From Version 1 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 1 1 Upgrading From Version 2.13 1 · 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 1 1 Generating Test Suites with Autotest 1 · 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' 1 1 Using an Autotest Test Suite 1 · testsuite Scripts The concepts of Autotest · Autotest Logs Their contents 1 1 Frequent Autoconf Questions, with answers 1 · 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 1 1 History of Autoconf 1 · 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 1 1 Indices 1 · 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 1