[SCM] eclipse-cdt - Plug-in for eclipse to handle C/C++ - Debian package. branch, master, updated. debian/8.1.0-1-8-gcc38e9c
Jakub Adam
jakub.adam at ktknet.cz
Thu Jun 28 17:00:54 UTC 2012
The following commit has been merged in the master branch:
commit a1a5872a02215036e291ea8553117bbb0429b5fd
Author: Jakub Adam <jakub.adam at ktknet.cz>
Date: Thu Jun 28 17:03:37 2012 +0200
Enable eclipse-cdt-autotools plugin
diff --git a/debian/changelog b/debian/changelog
index 22517aa..2307435 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,6 +1,7 @@
eclipse-cdt (8.1.0+dfsg-1) UNRELEASED; urgency=low
* Remove files generated out of texi documentation.
+ * Enable eclipse-cdt-autotools plugin.
-- Jakub Adam <jakub.adam at ktknet.cz> Thu, 28 Jun 2012 16:58:26 +0200
diff --git a/debian/control b/debian/control
index e99b550..fe43792 100644
--- a/debian/control
+++ b/debian/control
@@ -64,3 +64,29 @@ Description: C/C++ Development Tools for Eclipse (JNI)
.
This package contains architecture specific JNI libraries
+Package: eclipse-cdt-autotools
+Architecture: all
+Depends: eclipse-cdt (= ${source:Version}),
+ autoconf,
+ automake,
+ ${misc:Depends},
+ ${orbit:Depends}
+Description: Autotools support for Eclipse CDT
+ The Autotools suite of plugins adds to the CDT a support for building and
+ maintaining C/C++ projects that use Autotools. With this additional support,
+ a vast repository of C/C++ code can be checked out, built, and maintained
+ under the CDT rather easily without having to resort to the command line.
+ .
+ In conjunction with the CDT, the plugin can do the following:
+ * Build a C/C++ project that uses a configure script or an autogen
+ script or a Makefile.cvs script
+ * Create a simple C or C++ hello world Autotools project via a template
+ * Allow configuration parameters to be set via a gui and to rebuild when
+ configuration parameters are changed
+ * Colorized editing of configuration files such as configure.in, configure.ac,
+ Makefile.am, and Makefile.in with full hover help for autoconf/automake
+ macros
+ * Allow specification of multiple build configurations for a single project
+ * Run autotools such as autoconf, automake, or aclocal directly using a gui
+ interface
+ * Includes hover help for autoconf and automake macros in the editors
diff --git a/debian/copyright b/debian/copyright
index df3f9d1..ff4f884 100644
--- a/debian/copyright
+++ b/debian/copyright
@@ -91,6 +91,14 @@ Copyright: 2008, Andrew Overholt
2008-2010, Jeff Johnston
License: Fedora-contribution
+Files: debian/docs/src/autoconf/*
+Copyright: 1992-1996, 1998-2012, Free Software Foundation, Inc.
+License: GFDL-NIV
+
+Files: debian/docs/src/automake/*
+Copyright: 1995-2012, Free Software Foundation, Inc.
+License: GFDL-NIV
+
License: BSD-like
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
@@ -475,3 +483,10 @@ License: EPL-1.0
this Agreement will bring a legal action under this Agreement more than
one year after the cause of action arose. Each party waives its rights to
a jury trial in any resulting litigation.
+
+License: GFDL-NIV
+ On a Debian system, full text of the GNU Free Documentation License 1.3
+ can be found at /usr/share/common-licenses/GFDL-1.3.
+ .
+ Files contained in this source package released under GFDL do not
+ identify any "Invariant Sections" that would make them DFSG incompatible.
diff --git a/debian/docs/regenerateFromTexinfo.sh b/debian/docs/regenerateFromTexinfo.sh
new file mode 100755
index 0000000..c30d1d2
--- /dev/null
+++ b/debian/docs/regenerateFromTexinfo.sh
@@ -0,0 +1,38 @@
+#!/bin/sh
+# Make sure d/patches are applied to upstream source before running this script.
+
+mkdir -p tmp
+cd tmp
+
+CLASSPATH=$PWD/parsers
+
+ant -f ../src/parsers/build.xml -Dbuild=$CLASSPATH
+
+# Generate acmacros xml
+
+for AC_SRCDIR in ../src/autoconf/*; do
+ AC_VERSION=$(basename $AC_SRCDIR)
+ AC_MACROS=acmacros-$AC_VERSION.xml
+
+ java -cp $CLASSPATH \
+ org.eclipse.linuxtools.cdt.libhover.texinfoparsers.ParseAutoconfTexinfo \
+ $AC_SRCDIR ../$AC_MACROS
+
+ echo Generated $AC_MACROS
+done
+
+# generate ammacros xml
+
+for AM_SRCDIR in ../src/automake/*; do
+ AM_VERSION=$(basename $AM_SRCDIR)
+ AM_MACROS=ammacros-$AM_VERSION.xml
+
+ java -cp $CLASSPATH \
+ org.eclipse.linuxtools.cdt.libhover.texinfoparsers.ParseAutomakeTexinfo \
+ $AM_SRCDIR ../$AM_MACROS
+
+ echo Generated $AM_MACROS
+done
+
+cd ..
+rm -rf tmp
diff --git a/debian/docs/src/autoconf/2.69/autoconf.texi b/debian/docs/src/autoconf/2.69/autoconf.texi
new file mode 100644
index 0000000..34ca213
--- /dev/null
+++ b/debian/docs/src/autoconf/2.69/autoconf.texi
@@ -0,0 +1,26667 @@
+\input texinfo @c -*-texinfo-*-
+ at comment ========================================================
+ at comment %**start of header
+ at setfilename autoconf.info
+ at include version.texi
+ at settitle Autoconf
+ at setchapternewpage odd
+ at ifnothtml
+ at setcontentsaftertitlepage
+ at end ifnothtml
+ at finalout
+
+ at c @ovar(ARG)
+ at c ----------
+ at c The ARG is an optional argument. To be used for macro arguments in
+ at c their documentation (@defmac).
+ at macro ovar{varname}
+ at r{[}@var{\varname\}@r{]}@c
+ at end macro
+
+ at c @dvar(ARG, DEFAULT)
+ at c -------------------
+ at c The ARG is an optional argument, defaulting to DEFAULT. To be used
+ at c for macro arguments in their documentation (@defmac).
+ at macro dvar{varname, default}
+ at r{[}@var{\varname\} = @samp{\default\}@r{]}@c
+ at end macro
+
+ at c Handling the indexes with Texinfo yields several different problems.
+ at c
+ at c Because we want to drop out the AC_ part of the macro names in the
+ at c printed manual, but not in the other outputs, we need a layer above
+ at c the usual @acindex{} etc. That's why we first define indexes such as
+ at c acx meant to become the macro @acindex. First of all, using ``ac_''
+ at c does not work with makeinfo, and using ``ac1'' doesn't work with TeX.
+ at c So use something more regular ``acx''. Then you finish with a printed
+ at c index saying ``index is not existent''. Of course: you ought to use
+ at c two letters :( So you use capitals.
+ at c
+ at c Second, when defining a macro in the TeX world, following spaces are
+ at c eaten. But then, since we embed @acxindex commands that use the end
+ at c of line as an end marker, the whole things wrecks itself. So make
+ at c sure you do *force* an additional end of line, add a ``@c''.
+ at c
+ at c Finally, you might want to get rid of TeX expansion, using --expand
+ at c with texi2dvi. But then you wake up an old problem: we use macros
+ at c in @defmac etc. where TeX does perform the expansion, but not makeinfo.
+
+ at c Define an environment variable index, for variables users may set
+ at c in their environment or on the configure command line.
+ at defcodeindex ev
+ at c Define an output variable index, for commonly AC_SUBST'ed variables.
+ at defcodeindex ov
+ at c Define a cache variable index, for variables matching *_cv_*.
+ at defcodeindex CA
+ at c Other shell variables not fitting the above categories should be
+ at c listed in the predefined vrindex, which we merge in the concept index.
+ at syncodeindex vr cp
+ at c Define a CPP preprocessor macro index, for #define'd strings.
+ at defcodeindex cv
+ at c Define an Autoconf macro index that @defmac doesn't write to.
+ at defcodeindex AC
+ at c Define an Autotest macro index that @defmac doesn't write to.
+ at defcodeindex AT
+ at c Define an M4sugar macro index that @defmac doesn't write to.
+ at defcodeindex MS
+ at c Define an index for *foreign* programs: `mv' etc. Used for the
+ at c portability sections and so on.
+ at defindex pr
+
+ at c shortindexflag
+ at c --------------
+ at c Shall we factor AC_ out of the Autoconf macro index etc.?
+ at iftex
+ at set shortindexflag
+ at end iftex
+
+ at c @acindex{MACRO}
+ at c ---------------
+ at c Registering an AC_\MACRO\.
+ at ifset shortindexflag
+ at macro acindex{macro}
+ at ACindex \macro\
+ at c
+ at end macro
+ at end ifset
+ at ifclear shortindexflag
+ at macro acindex{macro}
+ at ACindex AC_\macro\
+ at end macro
+ at end ifclear
+
+ at c @ahindex{MACRO}
+ at c ---------------
+ at c Registering an AH_\MACRO\.
+ at macro ahindex{macro}
+ at ACindex AH_\macro\
+ at c
+ at end macro
+
+ at c @asindex{MACRO}
+ at c ---------------
+ at c Registering an AS_\MACRO\.
+ at ifset shortindexflag
+ at macro asindex{macro}
+ at MSindex \macro\
+ at c
+ at end macro
+ at end ifset
+ at ifclear shortindexflag
+ at macro asindex{macro}
+ at MSindex AS_\macro\
+ at end macro
+ at end ifclear
+
+ at c @atindex{MACRO}
+ at c ---------------
+ at c Registering an AT_\MACRO\.
+ at ifset shortindexflag
+ at macro atindex{macro}
+ at ATindex \macro\
+ at c
+ at end macro
+ at end ifset
+ at ifclear shortindexflag
+ at macro atindex{macro}
+ at ATindex AT_\macro\
+ at end macro
+ at end ifclear
+
+ at c @auindex{MACRO}
+ at c ---------------
+ at c Registering an AU_\MACRO\.
+ at macro auindex{macro}
+ at ACindex AU_\macro\
+ at c
+ at end macro
+
+ at c @hdrindex{MACRO}
+ at c ----------------
+ at c Indexing a header.
+ at macro hdrindex{macro}
+ at prindex @file{\macro\}
+ at c
+ at end macro
+
+ at c @msindex{MACRO}
+ at c ---------------
+ at c Registering an m4_\MACRO\.
+ at ifset shortindexflag
+ at macro msindex{macro}
+ at MSindex \macro\
+ at c
+ at end macro
+ at end ifset
+ at ifclear shortindexflag
+ at macro msindex{macro}
+ at MSindex m4_\macro\
+ at end macro
+ at end ifclear
+
+
+ at c @caindex{VARIABLE}
+ at c ------------------
+ at c Registering an ac_cv_\VARIABLE\ cache variable.
+ at ifset shortindexflag
+ at macro caindex{macro}
+ at CAindex \macro\
+ at end macro
+ at end ifset
+ at ifclear shortindexflag
+ at macro caindex{macro}
+ at CAindex ac_cv_\macro\
+ at end macro
+ at end ifclear
+
+ at c Define an index for functions: `alloca' etc. Used for the
+ at c portability sections and so on. We can't use `fn' (aka `fnindex),
+ at c since `@defmac' goes into it => we'd get all the macros too.
+
+ at c FIXME: Aaarg! It seems there are too many indices for TeX :(
+ at c
+ at c ! No room for a new @write .
+ at c l.112 @defcodeindex fu
+ at c
+ at c so don't define yet another one :( Just put some tags before each
+ at c @prindex which is actually a @funindex.
+ at c
+ at c @defcodeindex fu
+ at c
+ at c
+ at c @c Put the programs and functions into their own index.
+ at c @syncodeindex fu pr
+
+ at comment %**end of header
+ at comment ========================================================
+
+ at copying
+
+This manual (@value{UPDATED}) is for GNU Autoconf
+(version @value{VERSION}),
+a package for creating scripts to configure source code packages using
+templates and an M4 macro package.
+
+Copyright @copyright{} 1992-1996, 1998-2012 Free Software Foundation,
+Inc.
+
+ at quotation
+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.''
+ at end quotation
+ at end copying
+
+
+
+ at dircategory Software development
+ at direntry
+* Autoconf: (autoconf). Create source code configuration scripts.
+ at end direntry
+
+ at dircategory Individual utilities
+ at direntry
+* autoscan: (autoconf)autoscan Invocation.
+ Semi-automatic @file{configure.ac} writing
+* ifnames: (autoconf)ifnames Invocation. Listing conditionals in source.
+* autoconf-invocation: (autoconf)autoconf Invocation.
+ How to create configuration scripts
+* autoreconf: (autoconf)autoreconf Invocation.
+ Remaking multiple @command{configure} scripts
+* autoheader: (autoconf)autoheader Invocation.
+ How to create configuration templates
+* autom4te: (autoconf)autom4te Invocation.
+ The Autoconf executables backbone
+* configure: (autoconf)configure Invocation. Configuring a package.
+* autoupdate: (autoconf)autoupdate Invocation.
+ Automatic update of @file{configure.ac}
+* config.status: (autoconf)config.status Invocation. Recreating configurations.
+* testsuite: (autoconf)testsuite Invocation. Running an Autotest test suite.
+ at end direntry
+
+ at titlepage
+ at title Autoconf
+ at subtitle Creating Automatic Configuration Scripts
+ at subtitle for version @value{VERSION}, @value{UPDATED}
+ at author David MacKenzie
+ at author Ben Elliston
+ at author Akim Demaille
+ at page
+ at vskip 0pt plus 1filll
+ at insertcopying
+ at end titlepage
+
+ at contents
+
+
+ at ifnottex
+ at node Top
+ at top Autoconf
+ at insertcopying
+ at end ifnottex
+
+ at c The master menu, created with texinfo-master-menu, goes here.
+
+ at 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 @command{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.
+
+ at detailmenu
+ --- 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 @command{configure} Scripts
+
+* Writing Autoconf Input:: What to put in an Autoconf input file
+* autoscan Invocation:: Semi-automatic @file{configure.ac} writing
+* ifnames Invocation:: Listing the conditionals in source code
+* autoconf Invocation:: How to create configuration scripts
+* autoreconf Invocation:: Remaking multiple @command{configure} scripts
+
+Writing @file{configure.ac}
+
+* Shell Script Compiler:: Autoconf as solution of a problem
+* Autoconf Language:: Programming in Autoconf
+* Autoconf Input Layout:: Standard organization of @file{configure.ac}
+
+Initialization and Output Files
+
+* Initializing configure:: Option processing etc.
+* Versioning:: Dealing with Autoconf versions
+* Notices:: Copyright, version numbers in @command{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 @file{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
+* 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 @command{configure} runs
+* Printing Messages:: Notifying @command{configure} users
+
+Caching Results
+
+* Cache Variable Names:: Shell variables used in caches
+* Cache Files:: Files @command{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 @command{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
+* Reporting Messages:: Notifying @command{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
+* 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:: @code{make macro=value} and submakes
+* The Make Macro MAKEFLAGS:: @code{$(MAKEFLAGS)} portability issues
+* The Make Macro SHELL:: @code{$(SHELL)} portability issues
+* Parallel Make:: Parallel @command{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 @file{obj}
+* make -k Status:: Exit status of @samp{make -k}
+* VPATH and Make:: @code{VPATH} woes
+* Single Suffix Rules:: Single suffix rules and separated dependencies
+* Timestamps and Make:: Subsecond timestamp resolution
+
+ at code{VPATH} and Make
+
+* Variables listed in VPATH:: @code{VPATH} must be literal on ancient hosts
+* VPATH and Double-colon:: Problems with @samp{::} on ancient hosts
+* $< in Explicit Rules:: @code{$<} does not work in ordinary rules
+* Automatic Rule Rewriting:: @code{VPATH} goes wild on Solaris
+* Tru64 Directory Magic:: @command{mkdir} goes wild on Tru64
+* Make Target Lookup:: More details about @code{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:: @code{#if} expression problems
+* Null Pointers:: Properties of null pointers
+* Buffer Overruns:: Subscript errors and the like
+* Volatile Objects:: @code{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:: @code{INT_MIN / -1} and @code{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 @samp{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 @command{configure} options
+* Site Details:: Configuring site details
+* Transforming Names:: Changing program names when installing
+* Site Defaults:: Giving @command{configure} local defaults
+
+Transforming Program Names When Installing
+
+* Transformation Options:: @command{configure} options to transform names
+* Transformation Examples:: Sample uses of transforming names
+* Transformation Rules:: Makefile uses of transforming names
+
+Running @command{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
+* Particular Systems:: Particular systems
+* System Type:: Specifying the system type
+* Sharing Defaults:: Setting site-wide defaults for @command{configure}
+* Defining Variables:: Specifying the compiler etc.
+* configure Invocation:: Changing how @command{configure} runs
+
+Obsolete Constructs
+
+* Obsolete config.status Use:: Obsolete convention for @command{config.status}
+* acconfig Header:: Additional entries in @file{config.h.in}
+* autoupdate Invocation:: Automatic update of @file{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 @file{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 @command{testsuite} scripts
+* Making testsuite Scripts:: Using autom4te to create @command{testsuite}
+
+Using an Autotest Test Suite
+
+* testsuite Scripts:: The concepts of Autotest
+* Autotest Logs:: Their contents
+
+Frequent Autoconf Questions, with answers
+
+* Distributing:: Distributing @command{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 @command{configure} instead of Imake
+* Defining Directories:: Passing @code{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 @command{configure} scripts
+
+History of Autoconf
+
+* Genesis:: Prehistory and naming of @command{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
+
+ at end detailmenu
+ at end menu
+
+ at c ============================================================= Introduction.
+
+ at node Introduction
+ at chapter Introduction
+ at cindex Introduction
+
+ at flushright
+A physicist, an engineer, and a computer scientist were discussing the
+nature of God. ``Surely a Physicist,'' said the physicist, ``because
+early in the Creation, God made Light; and you know, Maxwell's
+equations, the dual nature of electromagnetic waves, the relativistic
+consequences at enddots{}'' ``An Engineer!,'' said the engineer, ``because
+before making Light, God split the Chaos into Land and Water; it takes a
+hell of an engineer to handle that big amount of mud, and orderly
+separation of solids from liquids at enddots{}'' The computer scientist
+shouted: ``And the Chaos, where do you think it was coming from, hmm?''
+
+---Anonymous
+ at end flushright
+ at c (via Franc,ois Pinard)
+
+Autoconf is a tool for producing shell scripts that automatically
+configure software source code packages to adapt to many kinds of
+Posix-like systems. The configuration scripts produced by Autoconf
+are independent of Autoconf when they are run, so their users do not
+need to have Autoconf.
+
+The configuration scripts produced by Autoconf require no manual user
+intervention when run; they do not normally even need an argument
+specifying the system type. Instead, they individually test for the
+presence of each feature that the software package they are for might need.
+(Before each check, they print a one-line message stating what they are
+checking for, so the user doesn't get too bored while waiting for the
+script to finish.) As a result, they deal well with systems that are
+hybrids or customized from the more common Posix variants. There is
+no need to maintain files that list the features supported by each
+release of each variant of Posix.
+
+For each software package that Autoconf is used with, it creates a
+configuration script from a template file that lists the system features
+that the package needs or can use. After the shell code to recognize
+and respond to a system feature has been written, Autoconf allows it to
+be shared by many software packages that can use (or need) that feature.
+If it later turns out that the shell code needs adjustment for some
+reason, it needs to be changed in only one place; all of the
+configuration scripts can be regenerated automatically to take advantage
+of the updated code.
+
+ at c "Those who do not understand Unix are condemned to reinvent it, poorly."
+ at c --Henry Spencer, 1987 (see http://en.wikipedia.org/wiki/Unix_philosophy)
+Those who do not understand Autoconf are condemned to reinvent it, poorly.
+The primary goal of Autoconf is making the @emph{user's} life easier;
+making the @emph{maintainer's} life easier is only a secondary goal.
+Put another way, the primary goal is not to make the generation of
+ at file{configure} automatic for package maintainers (although patches
+along that front are welcome, since package maintainers form the user
+base of Autoconf); rather, the goal is to make @file{configure}
+painless, portable, and predictable for the end user of each
+ at dfn{autoconfiscated} package. And to this degree, Autoconf is highly
+successful at its goal --- most complaints to the Autoconf list are
+about difficulties in writing Autoconf input, and not in the behavior of
+the resulting @file{configure}. Even packages that don't use Autoconf
+will generally provide a @file{configure} script, and the most common
+complaint about these alternative home-grown scripts is that they fail
+to meet one or more of the GNU Coding Standards (@pxref{Configuration, , ,
+standards, The GNU Coding Standards}) that users
+have come to expect from Autoconf-generated @file{configure} scripts.
+
+The Metaconfig package is similar in purpose to Autoconf, but the
+scripts it produces require manual user intervention, which is quite
+inconvenient when configuring large source trees. Unlike Metaconfig
+scripts, Autoconf scripts can support cross-compiling, if some care is
+taken in writing them.
+
+Autoconf does not solve all problems related to making portable
+software packages---for a more complete solution, it should be used in
+concert with other GNU build tools like Automake and
+Libtool. These other tools take on jobs like the creation of a
+portable, recursive makefile with all of the standard targets,
+linking of shared libraries, and so on. @xref{The GNU Build System},
+for more information.
+
+Autoconf imposes some restrictions on the names of macros used with
+ at code{#if} in C programs (@pxref{Preprocessor Symbol Index}).
+
+Autoconf requires GNU M4 version 1.4.6 or later in order to
+generate the scripts. It uses features that some versions of M4,
+including GNU M4 1.3, do not have. Autoconf works better
+with GNU M4 version 1.4.14 or later, though this is not
+required.
+
+ at xref{Autoconf 1}, for information about upgrading from version 1.
+ at xref{History}, for the story of Autoconf's development. @xref{FAQ},
+for answers to some common questions about Autoconf.
+
+See the @uref{http://@/www.gnu.org/@/software/@/autoconf/,
+Autoconf web page} for up-to-date information, details on the mailing
+lists, pointers to a list of known bugs, etc.
+
+Mail suggestions to @email{autoconf@@gnu.org, the Autoconf mailing
+list}. Past suggestions are
+ at uref{http://@/lists.gnu.org/@/archive/@/html/@/autoconf/, archived}.
+
+Mail bug reports to @email{bug-autoconf@@gnu.org, the
+Autoconf Bugs mailing list}. Past bug reports are
+ at uref{http://@/lists.gnu.org/@/archive/@/html/@/bug-autoconf/, archived}.
+
+If possible, first check that your bug is
+not already solved in current development versions, and that it has not
+been reported yet. Be sure to include all the needed information and a
+short @file{configure.ac} that demonstrates the problem.
+
+Autoconf's development tree is accessible via @command{git}; see the
+ at uref{http://@/savannah.gnu.org/@/projects/@/autoconf/, Autoconf
+Summary} for details, or view
+ at uref{http://@/git.sv.gnu.org/@/gitweb/@/?p=autoconf.git, the actual
+repository}. Anonymous CVS access is also available, see
+ at file{README} for more details. Patches relative to the
+current @command{git} version can be sent for review to the
+ at email{autoconf-patches@@gnu.org, Autoconf Patches mailing list}, with
+discussion on prior patches
+ at uref{http://@/lists.gnu.org/@/archive/@/html/@/autoconf-@/patches/,
+archived}; and all commits are posted in the read-only
+ at email{autoconf-commit@@gnu.org, Autoconf Commit mailing list}, which is
+also @uref{http://@/lists.gnu.org/@/archive/@/html/@/autoconf-commit/,
+archived}.
+
+Because of its mission, the Autoconf package itself
+includes only a set of often-used
+macros that have already demonstrated their usefulness. Nevertheless,
+if you wish to share your macros, or find existing ones, see the
+ at uref{http://@/www.gnu.org/@/software/@/autoconf-archive/, Autoconf Macro
+Archive}, which is kindly run by @email{simons@@cryp.to,
+Peter Simons}.
+
+
+ at c ================================================= The GNU Build System
+
+ at node The GNU Build System
+ at chapter The GNU Build System
+ at cindex GNU build system
+
+Autoconf solves an important problem---reliable discovery of
+system-specific build and runtime information---but this is only one
+piece of the puzzle for the development of portable software. To this
+end, the GNU project has developed a suite of integrated
+utilities to finish the job Autoconf started: the GNU build
+system, whose most important components are Autoconf, Automake, and
+Libtool. In this chapter, we introduce you to those tools, point you
+to sources of more information, and try to convince you to use the
+entire GNU build system for your software.
+
+ at menu
+* Automake:: Escaping makefile hell
+* Gnulib:: The GNU portability library
+* Libtool:: Building libraries portably
+* Pointers:: More info on the GNU build system
+ at end menu
+
+ at node Automake
+ at section Automake
+
+The ubiquity of @command{make} means that a makefile is almost the
+only viable way to distribute automatic build rules for software, but
+one quickly runs into its numerous limitations. Its lack of
+support for automatic dependency tracking, recursive builds in
+subdirectories, reliable timestamps (e.g., for network file systems), and
+so on, mean that developers must painfully (and often incorrectly)
+reinvent the wheel for each project. Portability is non-trivial, thanks
+to the quirks of @command{make} on many systems. On top of all this is the
+manual labor required to implement the many standard targets that users
+have come to expect (@code{make install}, @code{make distclean},
+ at code{make uninstall}, etc.). Since you are, of course, using Autoconf,
+you also have to insert repetitive code in your @file{Makefile.in} to
+recognize @code{@@CC@@}, @code{@@CFLAGS@@}, and other substitutions
+provided by @command{configure}. Into this mess steps @dfn{Automake}.
+ at cindex Automake
+
+Automake allows you to specify your build needs in a @file{Makefile.am}
+file with a vastly simpler and more powerful syntax than that of a plain
+makefile, and then generates a portable @file{Makefile.in} for
+use with Autoconf. For example, the @file{Makefile.am} to build and
+install a simple ``Hello world'' program might look like:
+
+ at example
+bin_PROGRAMS = hello
+hello_SOURCES = hello.c
+ at end example
+
+ at noindent
+The resulting @file{Makefile.in} (~400 lines) automatically supports all
+the standard targets, the substitutions provided by Autoconf, automatic
+dependency tracking, @code{VPATH} building, and so on. @command{make}
+builds the @code{hello} program, and @code{make install} installs it
+in @file{/usr/local/bin} (or whatever prefix was given to
+ at command{configure}, if not @file{/usr/local}).
+
+The benefits of Automake increase for larger packages (especially ones
+with subdirectories), but even for small programs the added convenience
+and portability can be substantial. And that's not all at enddots{}
+
+ at node Gnulib
+ at section Gnulib
+
+GNU software has a well-deserved reputation for running on
+many different types of systems. While our primary goal is to write
+software for the GNU system, many users and developers have
+been introduced to us through the systems that they were already using.
+
+ at cindex Gnulib
+Gnulib is a central location for common GNU code, intended to
+be shared among free software packages. Its components are typically
+shared at the source level, rather than being a library that gets built,
+installed, and linked against. The idea is to copy files from Gnulib
+into your own source tree. There is no distribution tarball; developers
+should just grab source modules from the repository. The source files
+are available online, under various licenses, mostly GNU
+GPL or GNU LGPL.
+
+Gnulib modules typically contain C source code along with Autoconf
+macros used to configure the source code. For example, the Gnulib
+ at code{stdbool} module implements a @file{stdbool.h} header that nearly
+conforms to C99, even on old-fashioned hosts that lack @file{stdbool.h}.
+This module contains a source file for the replacement header, along
+with an Autoconf macro that arranges to use the replacement header on
+old-fashioned systems.
+
+ at node Libtool
+ at section Libtool
+
+Often, one wants to build not only programs, but libraries, so that
+other programs can benefit from the fruits of your labor. Ideally, one
+would like to produce @emph{shared} (dynamically linked) libraries,
+which can be used by multiple programs without duplication on disk or in
+memory and can be updated independently of the linked programs.
+Producing shared libraries portably, however, is the stuff of
+nightmares---each system has its own incompatible tools, compiler flags,
+and magic incantations. Fortunately, GNU provides a solution:
+ at dfn{Libtool}.
+ at cindex Libtool
+
+Libtool handles all the requirements of building shared libraries for
+you, and at this time seems to be the @emph{only} way to do so with any
+portability. It also handles many other headaches, such as: the
+interaction of Make rules with the variable suffixes of
+shared libraries, linking reliably with shared libraries before they are
+installed by the superuser, and supplying a consistent versioning system
+(so that different versions of a library can be installed or upgraded
+without breaking binary compatibility). Although Libtool, like
+Autoconf, can be used without Automake, it is most simply utilized in
+conjunction with Automake---there, Libtool is used automatically
+whenever shared libraries are needed, and you need not know its syntax.
+
+ at node Pointers
+ at section Pointers
+
+Developers who are used to the simplicity of @command{make} for small
+projects on a single system might be daunted at the prospect of
+learning to use Automake and Autoconf. As your software is
+distributed to more and more users, however, you otherwise
+quickly find yourself putting lots of effort into reinventing the
+services that the GNU build tools provide, and making the
+same mistakes that they once made and overcame. (Besides, since
+you're already learning Autoconf, Automake is a piece of cake.)
+
+There are a number of places that you can go to for more information on
+the GNU build tools.
+
+ at itemize @minus
+
+ at item Web
+
+The project home pages for
+ at uref{http://@/www@/.gnu@/.org/@/software/@/autoconf/, Autoconf},
+ at uref{http://@/www@/.gnu@/.org/@/software/@/automake/, Automake},
+ at uref{http://@/www@/.gnu@/.org/@/software/@/gnulib/, Gnulib}, and
+ at uref{http://@/www@/.gnu@/.org/@/software/@/libtool/, Libtool}.
+
+ at item Automake Manual
+
+ at xref{Top, , Automake, automake, GNU Automake}, for more
+information on Automake.
+
+ at item Books
+
+The book @cite{GNU Autoconf, Automake and
+Libtool}@footnote{@cite{GNU Autoconf, Automake and Libtool},
+by G. V. Vaughan, B. Elliston, T. Tromey, and I. L. Taylor. SAMS (originally
+New Riders), 2000, ISBN 1578701902.} describes the complete GNU
+build environment. You can also find
+ at uref{http://@/sources.redhat.com/@/autobook/, the entire book on-line}.
+
+ at end itemize
+
+ at c ================================================= Making configure Scripts.
+
+ at node Making configure Scripts
+ at chapter Making @command{configure} Scripts
+ at cindex @file{aclocal.m4}
+ at cindex @command{configure}
+
+The configuration scripts that Autoconf produces are by convention
+called @command{configure}. When run, @command{configure} creates several
+files, replacing configuration parameters in them with appropriate
+values. The files that @command{configure} creates are:
+
+ at itemize @minus
+ at item
+one or more @file{Makefile} files, usually one in each subdirectory of the
+package (@pxref{Makefile Substitutions});
+
+ at item
+optionally, a C header file, the name of which is configurable,
+containing @code{#define} directives (@pxref{Configuration Headers});
+
+ at item
+a shell script called @file{config.status} that, when run, recreates
+the files listed above (@pxref{config.status Invocation});
+
+ at item
+an optional shell script normally called @file{config.cache}
+(created when using @samp{configure --config-cache}) that
+saves the results of running many of the tests (@pxref{Cache Files});
+
+ at item
+a file called @file{config.log} containing any messages produced by
+compilers, to help debugging if @command{configure} makes a mistake.
+ at end itemize
+
+ at cindex @file{configure.in}
+ at cindex @file{configure.ac}
+To create a @command{configure} script with Autoconf, you need to write an
+Autoconf input file @file{configure.ac} (or @file{configure.in}) and run
+ at command{autoconf} on it. If you write your own feature tests to
+supplement those that come with Autoconf, you might also write files
+called @file{aclocal.m4} and @file{acsite.m4}. If you use a C header
+file to contain @code{#define} directives, you might also run
+ at command{autoheader}, and you can distribute the generated file
+ at file{config.h.in} with the package.
+
+Here is a diagram showing how the files that can be used in
+configuration are produced. Programs that are executed are suffixed by
+ at samp{*}. Optional files are enclosed in square brackets (@samp{[]}).
+ at command{autoconf} and @command{autoheader} also read the installed Autoconf
+macro files (by reading @file{autoconf.m4}).
+
+ at noindent
+Files used in preparing a software package for distribution, when using
+just Autoconf:
+ at example
+your source files --> [autoscan*] --> [configure.scan] --> configure.ac
+
+ at group
+configure.ac --.
+ | .------> autoconf* -----> configure
+[aclocal.m4] --+---+
+ | `-----> [autoheader*] --> [config.h.in]
+[acsite.m4] ---'
+ at end group
+
+Makefile.in
+ at end example
+
+ at noindent
+Additionally, if you use Automake, the following additional productions
+come into play:
+
+ at example
+ at group
+[acinclude.m4] --.
+ |
+[local macros] --+--> aclocal* --> aclocal.m4
+ |
+configure.ac ----'
+ at end group
+
+ at group
+configure.ac --.
+ +--> automake* --> Makefile.in
+Makefile.am ---'
+ at end group
+ at end example
+
+ at noindent
+Files used in configuring a software package:
+ at example
+ at group
+ .-------------> [config.cache]
+configure* ------------+-------------> config.log
+ |
+[config.h.in] -. v .-> [config.h] -.
+ +--> config.status* -+ +--> make*
+Makefile.in ---' `-> Makefile ---'
+ at end group
+ at end example
+
+ at menu
+* Writing Autoconf Input:: What to put in an Autoconf input file
+* autoscan Invocation:: Semi-automatic @file{configure.ac} writing
+* ifnames Invocation:: Listing the conditionals in source code
+* autoconf Invocation:: How to create configuration scripts
+* autoreconf Invocation:: Remaking multiple @command{configure} scripts
+ at end menu
+
+ at node Writing Autoconf Input
+ at section Writing @file{configure.ac}
+
+To produce a @command{configure} script for a software package, create a
+file called @file{configure.ac} that contains invocations of the
+Autoconf macros that test the system features your package needs or can
+use. Autoconf macros already exist to check for many features; see
+ at ref{Existing Tests}, for their descriptions. For most other features,
+you can use Autoconf template macros to produce custom checks; see
+ at ref{Writing Tests}, for information about them. For especially tricky
+or specialized features, @file{configure.ac} might need to contain some
+hand-crafted shell commands; see @ref{Portable Shell, , Portable Shell
+Programming}. The @command{autoscan} program can give you a good start
+in writing @file{configure.ac} (@pxref{autoscan Invocation}, for more
+information).
+
+Previous versions of Autoconf promoted the name @file{configure.in},
+which is somewhat ambiguous (the tool needed to process this file is not
+described by its extension), and introduces a slight confusion with
+ at file{config.h.in} and so on (for which @samp{.in} means ``to be
+processed by @command{configure}''). Using @file{configure.ac} is now
+preferred.
+
+ at menu
+* Shell Script Compiler:: Autoconf as solution of a problem
+* Autoconf Language:: Programming in Autoconf
+* Autoconf Input Layout:: Standard organization of @file{configure.ac}
+ at end menu
+
+ at node Shell Script Compiler
+ at subsection A Shell Script Compiler
+
+Just as for any other computer language, in order to properly program
+ at file{configure.ac} in Autoconf you must understand @emph{what} problem
+the language tries to address and @emph{how} it does so.
+
+The problem Autoconf addresses is that the world is a mess. After all,
+you are using Autoconf in order to have your package compile easily on
+all sorts of different systems, some of them being extremely hostile.
+Autoconf itself bears the price for these differences: @command{configure}
+must run on all those systems, and thus @command{configure} must limit itself
+to their lowest common denominator of features.
+
+Naturally, you might then think of shell scripts; who needs
+ at command{autoconf}? A set of properly written shell functions is enough to
+make it easy to write @command{configure} scripts by hand. Sigh!
+Unfortunately, even in 2008, where shells without any function support are
+far and few between, there are pitfalls to avoid when making use of them.
+Also, finding a Bourne shell that accepts shell functions is not trivial,
+even though there is almost always one on interesting porting targets.
+
+So, what is really needed is some kind of compiler, @command{autoconf},
+that takes an Autoconf program, @file{configure.ac}, and transforms it
+into a portable shell script, @command{configure}.
+
+How does @command{autoconf} perform this task?
+
+There are two obvious possibilities: creating a brand new language or
+extending an existing one. The former option is attractive: all
+sorts of optimizations could easily be implemented in the compiler and
+many rigorous checks could be performed on the Autoconf program
+(e.g., rejecting any non-portable construct). Alternatively, you can
+extend an existing language, such as the @code{sh} (Bourne shell)
+language.
+
+Autoconf does the latter: it is a layer on top of @code{sh}. It was
+therefore most convenient to implement @command{autoconf} as a macro
+expander: a program that repeatedly performs @dfn{macro expansions} on
+text input, replacing macro calls with macro bodies and producing a pure
+ at code{sh} script in the end. Instead of implementing a dedicated
+Autoconf macro expander, it is natural to use an existing
+general-purpose macro language, such as M4, and implement the extensions
+as a set of M4 macros.
+
+
+ at node Autoconf Language
+ at subsection The Autoconf Language
+ at cindex quotation
+
+The Autoconf language differs from many other computer
+languages because it treats actual code the same as plain text. Whereas
+in C, for instance, data and instructions have different syntactic
+status, in Autoconf their status is rigorously the same. Therefore, we
+need a means to distinguish literal strings from text to be expanded:
+quotation.
+
+When calling macros that take arguments, there must not be any white
+space between the macro name and the open parenthesis.
+
+ at example
+AC_INIT ([oops], [1.0]) # incorrect
+AC_INIT([hello], [1.0]) # good
+ at end example
+
+Arguments should
+be enclosed within the quote characters @samp{[} and @samp{]}, and be
+separated by commas. Any leading blanks or newlines in arguments are ignored,
+unless they are quoted. You should always quote an argument that
+might contain a macro name, comma, parenthesis, or a leading blank or
+newline. This rule applies recursively for every macro
+call, including macros called from other macros. For more details on
+quoting rules, see @ref{Programming in M4}.
+
+For instance:
+
+ at example
+AC_CHECK_HEADER([stdio.h],
+ [AC_DEFINE([HAVE_STDIO_H], [1],
+ [Define to 1 if you have <stdio.h>.])],
+ [AC_MSG_ERROR([sorry, can't do anything for you])])
+ at end example
+
+ at noindent
+is quoted properly. You may safely simplify its quotation to:
+
+ at example
+AC_CHECK_HEADER([stdio.h],
+ [AC_DEFINE([HAVE_STDIO_H], 1,
+ [Define to 1 if you have <stdio.h>.])],
+ [AC_MSG_ERROR([sorry, can't do anything for you])])
+ at end example
+
+ at noindent
+because @samp{1} cannot contain a macro call. Here, the argument of
+ at code{AC_MSG_ERROR} must be quoted; otherwise, its comma would be
+interpreted as an argument separator. Also, the second and third arguments
+of @samp{AC_CHECK_HEADER} must be quoted, since they contain
+macro calls. The three arguments @samp{HAVE_STDIO_H}, @samp{stdio.h},
+and @samp{Define to 1 if you have <stdio.h>.} do not need quoting, but
+if you unwisely defined a macro with a name like @samp{Define} or
+ at samp{stdio} then they would need quoting. Cautious Autoconf users
+would keep the quotes, but many Autoconf users find such precautions
+annoying, and would rewrite the example as follows:
+
+ at example
+AC_CHECK_HEADER(stdio.h,
+ [AC_DEFINE(HAVE_STDIO_H, 1,
+ [Define to 1 if you have <stdio.h>.])],
+ [AC_MSG_ERROR([sorry, can't do anything for you])])
+ at end example
+
+ at noindent
+This is safe, so long as you adopt good naming conventions and do not
+define macros with names like @samp{HAVE_STDIO_H}, @samp{stdio}, or
+ at samp{h}. Though it is also safe here to omit the quotes around
+ at samp{Define to 1 if you have <stdio.h>.} this is not recommended, as
+message strings are more likely to inadvertently contain commas.
+
+The following example is wrong and dangerous, as it is underquoted:
+
+ at example
+AC_CHECK_HEADER(stdio.h,
+ AC_DEFINE(HAVE_STDIO_H, 1,
+ Define to 1 if you have <stdio.h>.),
+ AC_MSG_ERROR([sorry, can't do anything for you]))
+ at end example
+
+In other cases, you may have to use text that also resembles a macro
+call. You must quote that text even when it is not passed as a macro
+argument. For example, these two approaches in @file{configure.ac}
+(quoting just the potential problems, or quoting the entire line) will
+protect your script in case autoconf ever adds a macro @code{AC_DC}:
+
+ at example
+echo "Hard rock was here! --[AC_DC]"
+[echo "Hard rock was here! --AC_DC"]
+ at end example
+
+ at noindent
+which results in this text in @file{configure}:
+
+ at example
+echo "Hard rock was here! --AC_DC"
+echo "Hard rock was here! --AC_DC"
+ at end example
+
+ at noindent
+When you use the same text in a macro argument, you must therefore have
+an extra quotation level (since one is stripped away by the macro
+substitution). In general, then, it is a good idea to @emph{use double
+quoting for all literal string arguments}, either around just the
+problematic portions, or over the entire argument:
+
+ at example
+AC_MSG_WARN([[AC_DC] stinks --Iron Maiden])
+AC_MSG_WARN([[AC_DC stinks --Iron Maiden]])
+ at end example
+
+However, the above example triggers a warning about a possibly
+unexpanded macro when running @command{autoconf}, because it collides
+with the namespace of macros reserved for the Autoconf language. To be
+really safe, you can use additional escaping (either a quadrigraph, or
+creative shell constructs) to silence that particular warning:
+
+ at example
+echo "Hard rock was here! --AC""_DC"
+AC_MSG_WARN([[AC@@&t@@_DC stinks --Iron Maiden]])
+ at end example
+
+You are now able to understand one of the constructs of Autoconf that
+has been continually misunderstood at enddots{} The rule of thumb is that
+ at emph{whenever you expect macro expansion, expect quote expansion};
+i.e., expect one level of quotes to be lost. For instance:
+
+ at example
+AC_COMPILE_IFELSE(AC_LANG_SOURCE([char b[10];]), [],
+ [AC_MSG_ERROR([you lose])])
+ at end example
+
+ at noindent
+is incorrect: here, the first argument of @code{AC_LANG_SOURCE} is
+ at samp{char b[10];} and is expanded once, which results in
+ at samp{char b10;}; and the @code{AC_LANG_SOURCE} is also expanded prior
+to being passed to @code{AC_COMPILE_IFELSE}. (There was an idiom common
+in Autoconf's past to
+address this issue via the M4 @code{changequote} primitive, but do not
+use it!) Let's take a closer look: the author meant the first argument
+to be understood as a literal, and therefore it must be quoted twice;
+likewise, the intermediate @code{AC_LANG_SOURCE} macro should be quoted
+once so that it is only expanded after the rest of the body of
+ at code{AC_COMPILE_IFELSE} is in place:
+
+ at example
+AC_COMPILE_IFELSE([AC_LANG_SOURCE([[char b[10];]])], [],
+ [AC_MSG_ERROR([you lose])])
+ at end example
+
+ at noindent
+Voil@`a, you actually produce @samp{char b[10];} this time!
+
+On the other hand, descriptions (e.g., the last parameter of
+ at code{AC_DEFINE} or @code{AS_HELP_STRING}) are not literals---they
+are subject to line breaking, for example---and should not be double quoted.
+Even if these descriptions are short and are not actually broken, double
+quoting them yields weird results.
+
+Some macros take optional arguments, which this documentation represents
+as @ovar{arg} (not to be confused with the quote characters). You may
+just leave them empty, or use @samp{[]} to make the emptiness of the
+argument explicit, or you may simply omit the trailing commas. The
+three lines below are equivalent:
+
+ at example
+AC_CHECK_HEADERS([stdio.h], [], [], [])
+AC_CHECK_HEADERS([stdio.h],,,)
+AC_CHECK_HEADERS([stdio.h])
+ at end example
+
+It is best to put each macro call on its own line in
+ at file{configure.ac}. Most of the macros don't add extra newlines; they
+rely on the newline after the macro call to terminate the commands.
+This approach makes the generated @command{configure} script a little
+easier to read by not inserting lots of blank lines. It is generally
+safe to set shell variables on the same line as a macro call, because
+the shell allows assignments without intervening newlines.
+
+You can include comments in @file{configure.ac} files by starting them
+with the @samp{#}. For example, it is helpful to begin
+ at file{configure.ac} files with a line like this:
+
+ at example
+# Process this file with autoconf to produce a configure script.
+ at end example
+
+ at node Autoconf Input Layout
+ at subsection Standard @file{configure.ac} Layout
+
+The order in which @file{configure.ac} calls the Autoconf macros is not
+important, with a few exceptions. Every @file{configure.ac} must
+contain a call to @code{AC_INIT} before the checks, and a call to
+ at code{AC_OUTPUT} at the end (@pxref{Output}). Additionally, some macros
+rely on other macros having been called first, because they check
+previously set values of some variables to decide what to do. These
+macros are noted in the individual descriptions (@pxref{Existing
+Tests}), and they also warn you when @command{configure} is created if they
+are called out of order.
+
+To encourage consistency, here is a suggested order for calling the
+Autoconf macros. Generally speaking, the things near the end of this
+list are those that could depend on things earlier in it. For example,
+library functions could be affected by types and libraries.
+
+ at display
+ at group
+Autoconf requirements
+ at code{AC_INIT(@var{package}, @var{version}, @var{bug-report-address})}
+information on the package
+checks for programs
+checks for libraries
+checks for header files
+checks for types
+checks for structures
+checks for compiler characteristics
+checks for library functions
+checks for system services
+ at code{AC_CONFIG_FILES(@r{[}@var{file at dots{}}@r{]})}
+ at code{AC_OUTPUT}
+ at end group
+ at end display
+
+
+ at node autoscan Invocation
+ at section Using @command{autoscan} to Create @file{configure.ac}
+ at cindex @command{autoscan}
+
+The @command{autoscan} program can help you create and/or maintain a
+ at file{configure.ac} file for a software package. @command{autoscan}
+examines source files in the directory tree rooted at a directory given
+as a command line argument, or the current directory if none is given.
+It searches the source files for common portability problems and creates
+a file @file{configure.scan} which is a preliminary @file{configure.ac}
+for that package, and checks a possibly existing @file{configure.ac} for
+completeness.
+
+When using @command{autoscan} to create a @file{configure.ac}, you
+should manually examine @file{configure.scan} before renaming it to
+ at file{configure.ac}; it probably needs some adjustments.
+Occasionally, @command{autoscan} outputs a macro in the wrong order
+relative to another macro, so that @command{autoconf} produces a warning;
+you need to move such macros manually. Also, if you want the package to
+use a configuration header file, you must add a call to
+ at code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers}). You might
+also have to change or add some @code{#if} directives to your program in
+order to make it work with Autoconf (@pxref{ifnames Invocation}, for
+information about a program that can help with that job).
+
+When using @command{autoscan} to maintain a @file{configure.ac}, simply
+consider adding its suggestions. The file @file{autoscan.log}
+contains detailed information on why a macro is requested.
+
+ at command{autoscan} uses several data files (installed along with Autoconf)
+to determine which macros to output when it finds particular symbols in
+a package's source files. These data files all have the same format:
+each line consists of a symbol, one or more blanks, and the Autoconf macro to
+output if that symbol is encountered. Lines starting with @samp{#} are
+comments.
+
+ at command{autoscan} accepts the following options:
+
+ at table @option
+ at item --help
+ at itemx -h
+Print a summary of the command line options and exit.
+
+ at item --version
+ at itemx -V
+Print the version number of Autoconf and exit.
+
+ at item --verbose
+ at itemx -v
+Print the names of the files it examines and the potentially interesting
+symbols it finds in them. This output can be voluminous.
+
+ at item --debug
+ at itemx -d
+Don't remove temporary files.
+
+ at item --include=@var{dir}
+ at itemx -I @var{dir}
+Append @var{dir} to the include path. Multiple invocations accumulate.
+
+ at item --prepend-include=@var{dir}
+ at itemx -B @var{dir}
+Prepend @var{dir} to the include path. Multiple invocations accumulate.
+ at end table
+
+ at node ifnames Invocation
+ at section Using @command{ifnames} to List Conditionals
+ at cindex @command{ifnames}
+
+ at command{ifnames} can help you write @file{configure.ac} for a software
+package. It prints the identifiers that the package already uses in C
+preprocessor conditionals. If a package has already been set up to have
+some portability, @command{ifnames} can thus help you figure out what its
+ at command{configure} needs to check for. It may help fill in some gaps in a
+ at file{configure.ac} generated by @command{autoscan} (@pxref{autoscan
+Invocation}).
+
+ at command{ifnames} scans all of the C source files named on the command line
+(or the standard input, if none are given) and writes to the standard
+output a sorted list of all the identifiers that appear in those files
+in @code{#if}, @code{#elif}, @code{#ifdef}, or @code{#ifndef}
+directives. It prints each identifier on a line, followed by a
+space-separated list of the files in which that identifier occurs.
+
+ at noindent
+ at command{ifnames} accepts the following options:
+
+ at table @option
+ at item --help
+ at itemx -h
+Print a summary of the command line options and exit.
+
+ at item --version
+ at itemx -V
+Print the version number of Autoconf and exit.
+ at end table
+
+ at node autoconf Invocation
+ at section Using @command{autoconf} to Create @command{configure}
+ at cindex @command{autoconf}
+
+To create @command{configure} from @file{configure.ac}, run the
+ at command{autoconf} program with no arguments. @command{autoconf} processes
+ at file{configure.ac} with the M4 macro processor, using the
+Autoconf macros. If you give @command{autoconf} an argument, it reads that
+file instead of @file{configure.ac} and writes the configuration script
+to the standard output instead of to @command{configure}. If you give
+ at command{autoconf} the argument @option{-}, it reads from the standard
+input instead of @file{configure.ac} and writes the configuration script
+to the standard output.
+
+The Autoconf macros are defined in several files. Some of the files are
+distributed with Autoconf; @command{autoconf} reads them first. Then it
+looks for the optional file @file{acsite.m4} in the directory that
+contains the distributed Autoconf macro files, and for the optional file
+ at file{aclocal.m4} in the current directory. Those files can contain
+your site's or the package's own Autoconf macro definitions
+(@pxref{Writing Autoconf Macros}, for more information). If a macro is
+defined in more than one of the files that @command{autoconf} reads, the
+last definition it reads overrides the earlier ones.
+
+ at command{autoconf} accepts the following options:
+
+ at table @option
+ at item --help
+ at itemx -h
+Print a summary of the command line options and exit.
+
+ at item --version
+ at itemx -V
+Print the version number of Autoconf and exit.
+
+ at item --verbose
+ at itemx -v
+Report processing steps.
+
+ at item --debug
+ at itemx -d
+Don't remove the temporary files.
+
+ at item --force
+ at itemx -f
+Remake @file{configure} even if newer than its input files.
+
+ at item --include=@var{dir}
+ at itemx -I @var{dir}
+Append @var{dir} to the include path. Multiple invocations accumulate.
+
+ at item --prepend-include=@var{dir}
+ at itemx -B @var{dir}
+Prepend @var{dir} to the include path. Multiple invocations accumulate.
+
+ at item --output=@var{file}
+ at itemx -o @var{file}
+Save output (script or trace) to @var{file}. The file @option{-} stands
+for the standard output.
+
+ at item --warnings=@var{category}
+ at itemx -W @var{category}
+ at evindex WARNINGS
+Report the warnings related to @var{category} (which can actually be a
+comma separated list). @xref{Reporting Messages}, macro
+ at code{AC_DIAGNOSE}, for a comprehensive list of categories. Special
+values include:
+
+ at table @samp
+ at item all
+report all the warnings
+
+ at item none
+report none
+
+ at item error
+treats warnings as errors
+
+ at item no- at var{category}
+disable warnings falling into @var{category}
+ at end table
+
+Warnings about @samp{syntax} are enabled by default, and the environment
+variable @env{WARNINGS}, a comma separated list of categories, is
+honored as well. Passing @option{-W @var{category}} actually behaves as if
+you had passed @option{--warnings syntax,$WARNINGS, at var{category}}. To
+disable the defaults and @env{WARNINGS}, and then
+enable warnings about obsolete constructs, use @option{-W
+none,obsolete}.
+
+ at cindex Back trace
+ at cindex Macro invocation stack
+Because @command{autoconf} uses @command{autom4te} behind the scenes, it
+displays a back trace for errors, but not for warnings; if you want
+them, just pass @option{-W error}. @xref{autom4te Invocation}, for some
+examples.
+
+ at item --trace=@var{macro}[:@var{format}]
+ at itemx -t @var{macro}[:@var{format}]
+Do not create the @command{configure} script, but list the calls to
+ at var{macro} according to the @var{format}. Multiple @option{--trace}
+arguments can be used to list several macros. Multiple @option{--trace}
+arguments for a single macro are not cumulative; instead, you should
+just make @var{format} as long as needed.
+
+The @var{format} is a regular string, with newlines if desired, and
+several special escape codes. It defaults to @samp{$f:$l:$n:$%}; see
+ at ref{autom4te Invocation}, for details on the @var{format}.
+
+ at item --initialization
+ at itemx -i
+By default, @option{--trace} does not trace the initialization of the
+Autoconf macros (typically the @code{AC_DEFUN} definitions). This
+results in a noticeable speedup, but can be disabled by this option.
+ at end table
+
+
+It is often necessary to check the content of a @file{configure.ac}
+file, but parsing it yourself is extremely fragile and error-prone. It
+is suggested that you rely upon @option{--trace} to scan
+ at file{configure.ac}. For instance, to find the list of variables that
+are substituted, use:
+
+ at example
+ at group
+$ @kbd{autoconf -t AC_SUBST}
+configure.ac:2:AC_SUBST:ECHO_C
+configure.ac:2:AC_SUBST:ECHO_N
+configure.ac:2:AC_SUBST:ECHO_T
+ at i{More traces deleted}
+ at end group
+ at end example
+
+ at noindent
+The example below highlights the difference between @samp{$@@},
+ at samp{$*}, and @samp{$%}.
+
+ at example
+ at group
+$ @kbd{cat configure.ac}
+AC_DEFINE(This, is, [an
+[example]])
+$ @kbd{autoconf -t 'AC_DEFINE:@@: $@@}
+*: $*
+%: $%'
+@@: [This],[is],[an
+[example]]
+*: This,is,an
+[example]
+%: This:is:an [example]
+ at end group
+ at end example
+
+ at noindent
+The @var{format} gives you a lot of freedom:
+
+ at example
+ at group
+$ @kbd{autoconf -t 'AC_SUBST:$$ac_subst@{"$1"@} = "$f:$l";'}
+$ac_subst@{"ECHO_C"@} = "configure.ac:2";
+$ac_subst@{"ECHO_N"@} = "configure.ac:2";
+$ac_subst@{"ECHO_T"@} = "configure.ac:2";
+ at i{More traces deleted}
+ at end group
+ at end example
+
+ at noindent
+A long @var{separator} can be used to improve the readability of complex
+structures, and to ease their parsing (for instance when no single
+character is suitable as a separator):
+
+ at example
+ at group
+$ @kbd{autoconf -t 'AM_MISSING_PROG:$@{|:::::|@}*'}
+ACLOCAL|:::::|aclocal|:::::|$missing_dir
+AUTOCONF|:::::|autoconf|:::::|$missing_dir
+AUTOMAKE|:::::|automake|:::::|$missing_dir
+ at i{More traces deleted}
+ at end group
+ at end example
+
+ at node autoreconf Invocation
+ at section Using @command{autoreconf} to Update @command{configure} Scripts
+ at cindex @command{autoreconf}
+
+Installing the various components of the GNU Build System can be
+tedious: running @command{autopoint} for Gettext, @command{automake} for
+ at file{Makefile.in} etc.@: in each directory. It may be needed either
+because some tools such as @command{automake} have been updated on your
+system, or because some of the sources such as @file{configure.ac} have
+been updated, or finally, simply in order to install the GNU Build
+System in a fresh tree.
+
+ at command{autoreconf} runs @command{autoconf}, @command{autoheader},
+ at command{aclocal}, @command{automake}, @command{libtoolize}, and
+ at command{autopoint} (when appropriate) repeatedly to update the
+GNU Build System in the specified directories and their
+subdirectories (@pxref{Subdirectories}). By default, it only remakes
+those files that are older than their sources. The environment variables
+ at env{AUTOM4TE}, @env{AUTOCONF}, @env{AUTOHEADER}, @env{AUTOMAKE},
+ at env{ACLOCAL}, @env{AUTOPOINT}, @env{LIBTOOLIZE}, @env{M4}, and @env{MAKE}
+may be used to override the invocation of the respective tools.
+
+If you install a new version of some tool, you can make
+ at command{autoreconf} remake @emph{all} of the files by giving it the
+ at option{--force} option.
+
+ at xref{Automatic Remaking}, for Make rules to automatically
+rebuild @command{configure} scripts when their source files change. That
+method handles the timestamps of configuration header templates
+properly, but does not pass @option{--autoconf-dir=@var{dir}} or
+ at option{--localdir=@var{dir}}.
+
+ at cindex Gettext
+ at cindex @command{autopoint}
+Gettext supplies the @command{autopoint} command to add translation
+infrastructure to a source package. If you use @command{autopoint},
+your @file{configure.ac} should invoke both @code{AM_GNU_GETTEXT} and
+ at code{AM_GNU_GETTEXT_VERSION(@var{gettext-version})}. @xref{autopoint
+Invocation, , Invoking the @code{autopoint} Program, gettext,
+GNU @code{gettext} utilities}, for further details.
+
+ at noindent
+ at command{autoreconf} accepts the following options:
+
+ at table @option
+ at item --help
+ at itemx -h
+Print a summary of the command line options and exit.
+
+ at item --version
+ at itemx -V
+Print the version number of Autoconf and exit.
+
+ at item --verbose
+ at itemx -v
+Print the name of each directory @command{autoreconf} examines and the
+commands it runs. If given two or more times, pass @option{--verbose}
+to subordinate tools that support it.
+
+ at item --debug
+ at itemx -d
+Don't remove the temporary files.
+
+ at item --force
+ at itemx -f
+Remake even @file{configure} scripts and configuration headers that are
+newer than their input files (@file{configure.ac} and, if present,
+ at file{aclocal.m4}).
+
+ at item --install
+ at itemx -i
+Install the missing auxiliary files in the package. By default, files
+are copied; this can be changed with @option{--symlink}.
+
+If deemed appropriate, this option triggers calls to
+ at samp{automake --add-missing},
+ at samp{libtoolize}, @samp{autopoint}, etc.
+
+ at item --no-recursive
+Do not rebuild files in subdirectories to configure (see @ref{Subdirectories},
+macro @code{AC_CONFIG_SUBDIRS}).
+
+ at item --symlink
+ at itemx -s
+When used with @option{--install}, install symbolic links to the missing
+auxiliary files instead of copying them.
+
+ at item --make
+ at itemx -m
+When the directories were configured, update the configuration by
+running @samp{./config.status --recheck && ./config.status}, and then
+run @samp{make}.
+
+ at item --include=@var{dir}
+ at itemx -I @var{dir}
+Append @var{dir} to the include path. Multiple invocations accumulate.
+Passed on to @command{aclocal}, @command{autoconf} and
+ at command{autoheader} internally.
+
+ at item --prepend-include=@var{dir}
+ at itemx -B @var{dir}
+Prepend @var{dir} to the include path. Multiple invocations accumulate.
+Passed on to @command{autoconf} and @command{autoheader} internally.
+
+ at item --warnings=@var{category}
+ at itemx -W @var{category}
+ at evindex WARNINGS
+Report the warnings related to @var{category} (which can actually be a
+comma separated list).
+
+ at table @samp
+ at item cross
+related to cross compilation issues.
+
+ at item obsolete
+report the uses of obsolete constructs.
+
+ at item portability
+portability issues
+
+ at item syntax
+dubious syntactic constructs.
+
+ at item all
+report all the warnings
+
+ at item none
+report none
+
+ at item error
+treats warnings as errors
+
+ at item no- at var{category}
+disable warnings falling into @var{category}
+ at end table
+
+Warnings about @samp{syntax} are enabled by default, and the environment
+variable @env{WARNINGS}, a comma separated list of categories, is
+honored as well. Passing @option{-W @var{category}} actually behaves as if
+you had passed @option{--warnings syntax,$WARNINGS, at var{category}}. To
+disable the defaults and @env{WARNINGS}, and then
+enable warnings about obsolete constructs, use @option{-W
+none,obsolete}.
+ at end table
+
+If you want @command{autoreconf} to pass flags that are not listed here
+on to @command{aclocal}, set @code{ACLOCAL_AMFLAGS} in your @file{Makefile.am}.
+Due to a limitation in the Autoconf implementation these flags currently
+must be set on a single line in @file{Makefile.am}, without any
+backslash-newlines.
+
+ at c ========================================= Initialization and Output Files.
+
+ at node Setup
+ at chapter Initialization and Output Files
+
+Autoconf-generated @command{configure} scripts need some information about
+how to initialize, such as how to find the package's source files and
+about the output files to produce. The following sections describe the
+initialization and the creation of output files.
+
+ at menu
+* Initializing configure:: Option processing etc.
+* Versioning:: Dealing with Autoconf versions
+* Notices:: Copyright, version numbers in @command{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
+ at end menu
+
+ at node Initializing configure
+ at section Initializing @command{configure}
+
+Every @command{configure} script must call @code{AC_INIT} before doing
+anything else that produces output. Calls to silent macros, such as
+ at code{AC_DEFUN}, may also occur prior to @code{AC_INIT}, although these
+are generally used via @file{aclocal.m4}, since that is implicitly
+included before the start of @file{configure.ac}. The only other
+required macro is @code{AC_OUTPUT} (@pxref{Output}).
+
+ at anchor{AC_INIT}
+ at defmac AC_INIT (@var{package}, @var{version}, @ovar{bug-report}, @
+ @ovar{tarname}, @ovar{url})
+ at acindex{INIT}
+Process any command-line arguments and perform initialization
+and verification.
+
+Set the name of the @var{package} and its @var{version}. These are
+typically used in @option{--version} support, including that of
+ at command{configure}. The optional argument @var{bug-report} should be
+the email to which users should send bug reports. The package
+ at var{tarname} differs from @var{package}: the latter designates the full
+package name (e.g., @samp{GNU Autoconf}), while the former is meant for
+distribution tar ball names (e.g., @samp{autoconf}). It defaults to
+ at var{package} with @samp{GNU } stripped, lower-cased, and all characters
+other than alphanumerics and underscores are changed to @samp{-}. If
+provided, @var{url} should be the home page for the package.
+
+The arguments of @code{AC_INIT} must be static, i.e., there should not
+be any shell computation, quotes, or newlines, but they can be computed
+by M4. This is because the package information strings are expanded at
+M4 time into several contexts, and must give the same text at shell time
+whether used in single-quoted strings, double-quoted strings, quoted
+here-documents, or unquoted here-documents. It is permissible to use
+ at code{m4_esyscmd} or @code{m4_esyscmd_s} for computing a version string
+that changes with every commit to a version control system (in fact,
+Autoconf does just that, for all builds of the development tree made
+between releases).
+
+The following M4 macros (e.g., @code{AC_PACKAGE_NAME}), output variables
+(e.g., @code{PACKAGE_NAME}), and preprocessor symbols (e.g.,
+ at code{PACKAGE_NAME}), are defined by @code{AC_INIT}:
+
+ at table @asis
+ at item @code{AC_PACKAGE_NAME}, @code{PACKAGE_NAME}
+ at acindex{PACKAGE_NAME}
+ at ovindex PACKAGE_NAME
+ at cvindex PACKAGE_NAME
+Exactly @var{package}.
+
+ at item @code{AC_PACKAGE_TARNAME}, @code{PACKAGE_TARNAME}
+ at acindex{PACKAGE_TARNAME}
+ at ovindex PACKAGE_TARNAME
+ at cvindex PACKAGE_TARNAME
+Exactly @var{tarname}, possibly generated from @var{package}.
+
+ at item @code{AC_PACKAGE_VERSION}, @code{PACKAGE_VERSION}
+ at acindex{PACKAGE_VERSION}
+ at ovindex PACKAGE_VERSION
+ at cvindex PACKAGE_VERSION
+Exactly @var{version}.
+
+ at item @code{AC_PACKAGE_STRING}, @code{PACKAGE_STRING}
+ at acindex{PACKAGE_STRING}
+ at ovindex PACKAGE_STRING
+ at cvindex PACKAGE_STRING
+Exactly @samp{@var{package} @var{version}}.
+
+ at item @code{AC_PACKAGE_BUGREPORT}, @code{PACKAGE_BUGREPORT}
+ at acindex{PACKAGE_BUGREPORT}
+ at ovindex PACKAGE_BUGREPORT
+ at cvindex PACKAGE_BUGREPORT
+Exactly @var{bug-report}, if one was provided. Typically an email
+address, or URL to a bug management web page.
+
+ at item @code{AC_PACKAGE_URL}, @code{PACKAGE_URL}
+ at acindex{PACKAGE_URL}
+ at ovindex PACKAGE_URL
+ at cvindex PACKAGE_URL
+Exactly @var{url}, if one was provided. If @var{url} was empty, but
+ at var{package} begins with @samp{GNU }, then this defaults to
+ at samp{http://@/www.gnu.org/@/software/@/@var{tarname}/}, otherwise, no URL is
+assumed.
+ at end table
+ at end defmac
+
+If your @command{configure} script does its own option processing, it
+should inspect @samp{$@@} or @samp{$*} immediately after calling
+ at code{AC_INIT}, because other Autoconf macros liberally use the
+ at command{set} command to process strings, and this has the side effect
+of updating @samp{$@@} and @samp{$*}. However, we suggest that you use
+standard macros like @code{AC_ARG_ENABLE} instead of attempting to
+implement your own option processing. @xref{Site Configuration}.
+
+ at node Versioning
+ at section Dealing with Autoconf versions
+ at cindex Autoconf version
+ at cindex version, Autoconf
+
+The following optional macros can be used to help choose the minimum
+version of Autoconf that can successfully compile a given
+ at file{configure.ac}.
+
+ at defmac AC_PREREQ (@var{version})
+ at acindex{PREREQ}
+ at cindex Version
+Ensure that a recent enough version of Autoconf is being used. If the
+version of Autoconf being used to create @command{configure} is
+earlier than @var{version}, print an error message to the standard
+error output and exit with failure (exit status is 63). For example:
+
+ at example
+AC_PREREQ([@value{VERSION}])
+ at end example
+
+This macro may be used before @code{AC_INIT}.
+ at end defmac
+
+ at defmac AC_AUTOCONF_VERSION
+ at acindex{AUTOCONF_VERSION}
+This macro was introduced in Autoconf 2.62. It identifies the version
+of Autoconf that is currently parsing the input file, in a format
+suitable for @code{m4_version_compare} (@pxref{m4_version_compare}); in
+other words, for this release of Autoconf, its value is
+ at samp{@value{VERSION}}. One potential use of this macro is for writing
+conditional fallbacks based on when a feature was added to Autoconf,
+rather than using @code{AC_PREREQ} to require the newer version of
+Autoconf. However, remember that the Autoconf philosophy favors feature
+checks over version checks.
+
+You should not expand this macro directly; use
+ at samp{m4_defn([AC_AUTOCONF_VERSION])} instead. This is because some
+users might
+have a beta version of Autoconf installed, with arbitrary letters
+included in its version string. This means it is possible for the
+version string to contain the name of a defined macro, such that
+expanding @code{AC_AUTOCONF_VERSION} would trigger the expansion of that
+macro during rescanning, and change the version string to be different
+than what you intended to check.
+ at end defmac
+
+ at node Notices
+ at section Notices in @command{configure}
+ at cindex Notices in @command{configure}
+
+The following macros manage version numbers for @command{configure}
+scripts. Using them is optional.
+
+ at defmac AC_COPYRIGHT (@var{copyright-notice})
+ at acindex{COPYRIGHT}
+ at cindex Copyright Notice
+State that, in addition to the Free Software Foundation's copyright on
+the Autoconf macros, parts of your @command{configure} are covered by the
+ at var{copyright-notice}.
+
+The @var{copyright-notice} shows up in both the head of
+ at command{configure} and in @samp{configure --version}.
+ at end defmac
+
+
+ at defmac AC_REVISION (@var{revision-info})
+ at acindex{REVISION}
+ at cindex Revision
+Copy revision stamp @var{revision-info} into the @command{configure}
+script, with any dollar signs or double-quotes removed. This macro lets
+you put a revision stamp from @file{configure.ac} into @command{configure}
+without RCS or CVS changing it when you check in
+ at command{configure}. That way, you can determine easily which revision of
+ at file{configure.ac} a particular @command{configure} corresponds to.
+
+For example, this line in @file{configure.ac}:
+
+ at c The @w prevents RCS from changing the example in the manual.
+ at example
+AC_REVISION([@w{$}Revision: 1.30 $])
+ at end example
+
+ at noindent
+produces this in @command{configure}:
+
+ at example
+#!/bin/sh
+# From configure.ac Revision: 1.30
+ at end example
+ at end defmac
+
+
+ at node Input
+ at section Finding @command{configure} Input
+
+ at anchor{AC_CONFIG_SRCDIR}
+ at defmac AC_CONFIG_SRCDIR (@var{unique-file-in-source-dir})
+ at acindex{CONFIG_SRCDIR}
+ at var{unique-file-in-source-dir} is some file that is in the package's
+source directory; @command{configure} checks for this file's existence to
+make sure that the directory that it is told contains the source code in
+fact does. Occasionally people accidentally specify the wrong directory
+with @option{--srcdir}; this is a safety check. @xref{configure
+Invocation}, for more information.
+ at end defmac
+
+
+ at c FIXME: Remove definitively once --install explained.
+ at c
+ at c Small packages may store all their macros in @code{aclocal.m4}. As the
+ at c set of macros grows, or for maintenance reasons, a maintainer may prefer
+ at c to split the macros in several files. In this case, Autoconf must be
+ at c told which files to load, and in which order.
+ at c
+ at c @defmac AC_INCLUDE (@var{file}@dots{})
+ at c @acindex{INCLUDE}
+ at c @c FIXME: There is no longer shell globbing.
+ at c Read the macro definitions that appear in the listed files. A list of
+ at c space-separated file names or shell globbing patterns is expected. The
+ at c files are read in the order they're listed.
+ at c
+ at c Because the order of definition of macros is important (only the last
+ at c definition of a macro is used), beware that it is @code{AC_INIT} that
+ at c loads @file{acsite.m4} and @file{aclocal.m4}. Note that
+ at c @code{AC_INCLUDE}ing a file before @code{AC_INIT} or within
+ at c @file{aclocal.m4} is different from doing so after @code{AC_INIT}: in
+ at c the latter case, non-macro lines from included files may end up in the
+ at c @file{configure} script, whereas in the former case, they'd be discarded
+ at c just like any text that appear before @code{AC_INIT}.
+ at c @end defmac
+
+Packages that do manual configuration or use the @command{install} program
+might need to tell @command{configure} where to find some other shell
+scripts by calling @code{AC_CONFIG_AUX_DIR}, though the default places
+it looks are correct for most cases.
+
+ at defmac AC_CONFIG_AUX_DIR (@var{dir})
+ at acindex{CONFIG_AUX_DIR}
+Use the auxiliary build tools (e.g., @file{install-sh},
+ at file{config.sub}, @file{config.guess}, Cygnus @command{configure},
+Automake and Libtool scripts, etc.)@: that are in directory @var{dir}.
+These are auxiliary files used in configuration. @var{dir} can be
+either absolute or relative to @file{@var{srcdir}}. The default is
+ at file{@var{srcdir}} or @file{@var{srcdir}/..} or
+ at file{@var{srcdir}/../..}, whichever is the first that contains
+ at file{install-sh}. The other files are not checked for, so that using
+ at code{AC_PROG_INSTALL} does not automatically require distributing the
+other auxiliary files. It checks for @file{install.sh} also, but that
+name is obsolete because some @command{make} have a rule that creates
+ at file{install} from it if there is no makefile.
+
+The auxiliary directory is commonly named @file{build-aux}.
+If you need portability to DOS variants, do not name the
+auxiliary directory @file{aux}. @xref{File System Conventions}.
+ at end defmac
+
+ at defmac AC_REQUIRE_AUX_FILE (@var{file})
+ at acindex{REQUIRE_AUX_FILE}
+Declares that @var{file} is expected in the directory defined above. In
+Autoconf proper, this macro does nothing: its sole purpose is to be
+traced by third-party tools to produce a list of expected auxiliary
+files. For instance it is called by macros like @code{AC_PROG_INSTALL}
+(@pxref{Particular Programs}) or @code{AC_CANONICAL_BUILD}
+(@pxref{Canonicalizing}) to register the auxiliary files they need.
+ at end defmac
+
+Similarly, packages that use @command{aclocal} should declare where
+local macros can be found using @code{AC_CONFIG_MACRO_DIR}.
+
+ at defmac AC_CONFIG_MACRO_DIR (@var{dir})
+ at acindex{CONFIG_MACRO_DIR}
+Specify @var{dir} as the location of additional local Autoconf macros.
+This macro is intended for use by future versions of commands like
+ at command{autoreconf} that trace macro calls. It should be called
+directly from @file{configure.ac} so that tools that install macros for
+ at command{aclocal} can find the macros' declarations.
+
+Note that if you use @command{aclocal} from Automake to generate
+ at file{aclocal.m4}, you must also set @code{ACLOCAL_AMFLAGS = -I
+ at var{dir}} in your top-level @file{Makefile.am}. Due to a limitation in
+the Autoconf implementation of @command{autoreconf}, these include
+directives currently must be set on a single line in @file{Makefile.am},
+without any backslash-newlines.
+ at end defmac
+
+
+ at node Output
+ at section Outputting Files
+ at cindex Outputting files
+
+Every Autoconf script, e.g., @file{configure.ac}, should finish by
+calling @code{AC_OUTPUT}. That is the macro that generates and runs
+ at file{config.status}, which in turn creates the makefiles and any
+other files resulting from configuration. This is the only required
+macro besides @code{AC_INIT} (@pxref{Input}).
+
+ at anchor{AC_OUTPUT}
+ at defmac AC_OUTPUT
+ at acindex{OUTPUT}
+ at cindex Instantiation
+Generate @file{config.status} and launch it. Call this macro once, at
+the end of @file{configure.ac}.
+
+ at file{config.status} performs all the configuration actions: all the
+output files (see @ref{Configuration Files}, macro
+ at code{AC_CONFIG_FILES}), header files (see @ref{Configuration Headers},
+macro @code{AC_CONFIG_HEADERS}), commands (see @ref{Configuration
+Commands}, macro @code{AC_CONFIG_COMMANDS}), links (see
+ at ref{Configuration Links}, macro @code{AC_CONFIG_LINKS}), subdirectories
+to configure (see @ref{Subdirectories}, macro @code{AC_CONFIG_SUBDIRS})
+are honored.
+
+The location of your @code{AC_OUTPUT} invocation is the exact point
+where configuration actions are taken: any code afterwards is
+executed by @command{configure} once @command{config.status} was run. If
+you want to bind actions to @command{config.status} itself
+(independently of whether @command{configure} is being run), see
+ at ref{Configuration Commands, , Running Arbitrary Configuration
+Commands}.
+ at end defmac
+
+Historically, the usage of @code{AC_OUTPUT} was somewhat different.
+ at xref{Obsolete Macros}, for a description of the arguments that
+ at code{AC_OUTPUT} used to support.
+
+
+If you run @command{make} in subdirectories, you should run it using the
+ at command{make} variable @code{MAKE}. Most versions of @command{make} set
+ at code{MAKE} to the name of the @command{make} program plus any options it
+was given. (But many do not include in it the values of any variables
+set on the command line, so those are not passed on automatically.)
+Some old versions of @command{make} do not set this variable. The
+following macro allows you to use it even with those versions.
+
+ at anchor{AC_PROG_MAKE_SET}
+ at defmac AC_PROG_MAKE_SET
+ at acindex{PROG_MAKE_SET}
+ at ovindex SET_MAKE
+If the Make command, @code{$MAKE} if set or else @samp{make}, predefines
+ at code{$(MAKE)}, define output variable @code{SET_MAKE} to be empty.
+Otherwise, define @code{SET_MAKE} to a macro definition that sets
+ at code{$(MAKE)}, such as @samp{MAKE=make}. Calls @code{AC_SUBST} for
+ at code{SET_MAKE}.
+ at end defmac
+
+If you use this macro, place a line like this in each @file{Makefile.in}
+that runs @command{MAKE} on other directories:
+
+ at example
+@@SET_MAKE@@
+ at end example
+
+
+
+ at node Configuration Actions
+ at section Performing Configuration Actions
+ at cindex Configuration actions
+
+ at file{configure} is designed so that it appears to do everything itself,
+but there is actually a hidden slave: @file{config.status}.
+ at file{configure} is in charge of examining your system, but it is
+ at file{config.status} that actually takes the proper actions based on the
+results of @file{configure}. The most typical task of
+ at file{config.status} is to @emph{instantiate} files.
+
+ at acindex{CONFIG_ at var{ITEMS}}
+This section describes the common behavior of the four standard
+instantiating macros: @code{AC_CONFIG_FILES}, @code{AC_CONFIG_HEADERS},
+ at code{AC_CONFIG_COMMANDS} and @code{AC_CONFIG_LINKS}. They all
+have this prototype:
+
+ at c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
+ at c awful.
+ at example
+AC_CONFIG_ at var{ITEMS}(@var{tag}@dots{}, @r{[}@var{commands}@r{]}, @r{[}@var{init-cmds}@r{]})
+ at end example
+
+ at noindent
+where the arguments are:
+
+ at table @var
+ at item tag at dots{}
+A blank-or-newline-separated list of tags, which are typically the names of
+the files to instantiate.
+
+You are encouraged to use literals as @var{tags}. In particular, you
+should avoid
+
+ at example
+ at dots{} && my_foos="$my_foos fooo"
+ at dots{} && my_foos="$my_foos foooo"
+AC_CONFIG_ at var{ITEMS}([$my_foos])
+ at end example
+
+ at noindent
+and use this instead:
+
+ at example
+ at dots{} && AC_CONFIG_ at var{ITEMS}([fooo])
+ at dots{} && AC_CONFIG_ at var{ITEMS}([foooo])
+ at end example
+
+The macros @code{AC_CONFIG_FILES} and @code{AC_CONFIG_HEADERS} use
+special @var{tag} values: they may have the form @samp{@var{output}} or
+ at samp{@var{output}:@var{inputs}}. The file @var{output} is instantiated
+from its templates, @var{inputs} (defaulting to @samp{@var{output}.in}).
+
+ at samp{AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk])},
+for example, asks for
+the creation of the file @file{Makefile} that contains the expansion of the
+output variables in the concatenation of @file{boiler/top.mk} and
+ at file{boiler/bot.mk}.
+
+The special value @samp{-} might be used to denote the standard output
+when used in @var{output}, or the standard input when used in the
+ at var{inputs}. You most probably don't need to use this in
+ at file{configure.ac}, but it is convenient when using the command line
+interface of @file{./config.status}, see @ref{config.status Invocation},
+for more details.
+
+The @var{inputs} may be absolute or relative file names. In the latter
+case they are first looked for in the build tree, and then in the source
+tree. Input files should be text files, and a line length below 2000
+bytes should be safe.
+
+ at item commands
+Shell commands output literally into @file{config.status}, and
+associated with a tag that the user can use to tell @file{config.status}
+which commands to run. The commands are run each time a @var{tag}
+request is given to @file{config.status}, typically each time the file
+ at file{@var{tag}} is created.
+
+The variables set during the execution of @command{configure} are
+ at emph{not} available here: you first need to set them via the
+ at var{init-cmds}. Nonetheless the following variables are precomputed:
+
+ at table @code
+ at item srcdir
+ at vrindex srcdir
+The name of the top source directory, assuming that the working
+directory is the top build directory. This
+is what the @command{configure} option @option{--srcdir} sets.
+
+ at item ac_top_srcdir
+ at vrindex ac_top_srcdir
+The name of the top source directory, assuming that the working
+directory is the current build directory.
+
+ at item ac_top_build_prefix
+ at vrindex ac_top_build_prefix
+The name of the top build directory, assuming that the working
+directory is the current build directory.
+It can be empty, or else ends with a slash, so that you may concatenate
+it.
+
+ at item ac_srcdir
+ at vrindex ac_srcdir
+The name of the corresponding source directory, assuming that the
+working directory is the current build directory.
+
+ at item tmp
+ at vrindex tmp
+The name of a temporary directory within the build tree, which you
+can use if you need to create additional temporary files. The
+directory is cleaned up when @command{config.status} is done or
+interrupted. Please use package-specific file name prefixes to
+avoid clashing with files that @command{config.status} may use
+internally.
+ at end table
+
+ at noindent
+The @dfn{current} directory refers to the directory (or
+pseudo-directory) containing the input part of @var{tags}. For
+instance, running
+
+ at example
+AC_CONFIG_COMMANDS([deep/dir/out:in/in.in], [@dots{}], [@dots{}])
+ at end example
+
+ at noindent
+ with @option{--srcdir=../package} produces the following values:
+
+ at example
+# Argument of --srcdir
+srcdir='../package'
+# Reversing deep/dir
+ac_top_build_prefix='../../'
+# Concatenation of $ac_top_build_prefix and srcdir
+ac_top_srcdir='../../../package'
+# Concatenation of $ac_top_srcdir and deep/dir
+ac_srcdir='../../../package/deep/dir'
+ at end example
+
+ at noindent
+independently of @samp{in/in.in}.
+
+ at item init-cmds
+Shell commands output @emph{unquoted} near the beginning of
+ at file{config.status}, and executed each time @file{config.status} runs
+(regardless of the tag). Because they are unquoted, for example,
+ at samp{$var} is output as the value of @code{var}. @var{init-cmds}
+is typically used by @file{configure} to give @file{config.status} some
+variables it needs to run the @var{commands}.
+
+You should be extremely cautious in your variable names: all the
+ at var{init-cmds} share the same name space and may overwrite each other
+in unpredictable ways. Sorry at enddots{}
+ at end table
+
+All these macros can be called multiple times, with different
+ at var{tag} values, of course!
+
+
+ at node Configuration Files
+ at section Creating Configuration Files
+ at cindex Creating configuration files
+ at cindex Configuration file creation
+
+Be sure to read the previous section, @ref{Configuration Actions}.
+
+ at anchor{AC_CONFIG_FILES}
+ at defmac AC_CONFIG_FILES (@var{file}@dots{}, @ovar{cmds}, @ovar{init-cmds})
+ at acindex{CONFIG_FILES}
+Make @code{AC_OUTPUT} create each @file{@var{file}} by copying an input
+file (by default @file{@var{file}.in}), substituting the output variable
+values.
+ at c Before we used to have this feature, which was later rejected
+ at c because it complicates the writing of makefiles:
+ at c If the file would be unchanged, it is left untouched, to preserve
+ at c timestamp.
+This macro is one of the instantiating macros; see @ref{Configuration
+Actions}. @xref{Makefile Substitutions}, for more information on using
+output variables. @xref{Setting Output Variables}, for more information
+on creating them. This macro creates the directory that the file is in
+if it doesn't exist. Usually, makefiles are created this way,
+but other files, such as @file{.gdbinit}, can be specified as well.
+
+Typical calls to @code{AC_CONFIG_FILES} look like this:
+
+ at example
+AC_CONFIG_FILES([Makefile src/Makefile man/Makefile X/Imakefile])
+AC_CONFIG_FILES([autoconf], [chmod +x autoconf])
+ at end example
+
+You can override an input file name by appending to @var{file} a
+colon-separated list of input files. Examples:
+
+ at example
+AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk]
+ [lib/Makefile:boiler/lib.mk])
+ at end example
+
+ at noindent
+Doing this allows you to keep your file names acceptable to
+DOS variants, or
+to prepend and/or append boilerplate to the file.
+ at end defmac
+
+
+
+ at node Makefile Substitutions
+ at section Substitutions in Makefiles
+ at cindex Substitutions in makefiles
+ at cindex Makefile substitutions
+
+Each subdirectory in a distribution that contains something to be
+compiled or installed should come with a file @file{Makefile.in}, from
+which @command{configure} creates a file @file{Makefile} in that directory.
+To create @file{Makefile}, @command{configure} performs a simple variable
+substitution, replacing occurrences of @samp{@@@var{variable}@@} in
+ at file{Makefile.in} with the value that @command{configure} has determined
+for that variable. Variables that are substituted into output files in
+this way are called @dfn{output variables}. They are ordinary shell
+variables that are set in @command{configure}. To make @command{configure}
+substitute a particular variable into the output files, the macro
+ at code{AC_SUBST} must be called with that variable name as an argument.
+Any occurrences of @samp{@@@var{variable}@@} for other variables are
+left unchanged. @xref{Setting Output Variables}, for more information
+on creating output variables with @code{AC_SUBST}.
+
+A software package that uses a @command{configure} script should be
+distributed with a file @file{Makefile.in}, but no makefile; that
+way, the user has to properly configure the package for the local system
+before compiling it.
+
+ at xref{Makefile Conventions, , Makefile Conventions, standards, The
+GNU Coding Standards}, for more information on what to put in
+makefiles.
+
+ at menu
+* Preset Output Variables:: Output variables that are always set
+* Installation Directory Variables:: Other preset output variables
+* Changed Directory Variables:: Warnings about @file{datarootdir}
+* Build Directories:: Supporting multiple concurrent compiles
+* Automatic Remaking:: Makefile rules for configuring
+ at end menu
+
+ at node Preset Output Variables
+ at subsection Preset Output Variables
+ at cindex Output variables
+
+Some output variables are preset by the Autoconf macros. Some of the
+Autoconf macros set additional output variables, which are mentioned in
+the descriptions for those macros. @xref{Output Variable Index}, for a
+complete list of output variables. @xref{Installation Directory
+Variables}, for the list of the preset ones related to installation
+directories. Below are listed the other preset ones, many of which are
+precious variables (@pxref{Setting Output Variables},
+ at code{AC_ARG_VAR}).
+
+The preset variables which are available during @file{config.status}
+(@pxref{Configuration Actions}) may also be used during
+ at command{configure} tests. For example, it is permissible to reference
+ at samp{$srcdir} when constructing a list of directories to pass via
+option @option{-I} during a compiler feature check. When used in this
+manner, coupled with the fact that @command{configure} is always run
+from the top build directory, it is sufficient to use just
+ at samp{$srcdir} instead of @samp{$top_srcdir}.
+
+ at c Just say no to ASCII sorting! We're humans, not computers.
+ at c These variables are listed as they would be in a dictionary:
+ at c actor
+ at c Actress
+ at c actress
+
+ at defvar CFLAGS
+ at evindex CFLAGS
+ at ovindex CFLAGS
+Debugging and optimization options for the C compiler. If it is not set
+in the environment when @command{configure} runs, the default value is set
+when you call @code{AC_PROG_CC} (or empty if you don't). @command{configure}
+uses this variable when compiling or linking programs to test for C features.
+
+If a compiler option affects only the behavior of the preprocessor
+(e.g., @option{-D at var{name}}), it should be put into @code{CPPFLAGS}
+instead. If it affects only the linker (e.g., @option{-L at var{directory}}),
+it should be put into @code{LDFLAGS} instead. If it
+affects only the compiler proper, @code{CFLAGS} is the natural home for
+it. If an option affects multiple phases of the compiler, though,
+matters get tricky. One approach to put such options directly into
+ at code{CC}, e.g., @code{CC='gcc -m64'}. Another is to put them into both
+ at code{CPPFLAGS} and @code{LDFLAGS}, but not into @code{CFLAGS}.
+
+However, remember that some @file{Makefile} variables are reserved by
+the GNU Coding Standards for the use of the ``user''---the person
+building the package. For instance, @code{CFLAGS} is one such variable.
+
+Sometimes package developers are tempted to set user variables such as
+ at code{CFLAGS} because it appears to make their job easier. However, the
+package itself should never set a user variable, particularly not to
+include switches that are required for proper compilation of the
+package. Since these variables are documented as being for the package
+builder, that person rightfully expects to be able to override any of
+these variables at build time. If the package developer needs to add
+switches without interfering with the user, the proper way to do that is
+to introduce an additional variable. Automake makes this easy by
+introducing @code{AM_CFLAGS} (@pxref{Flag Variables Ordering, , ,
+automake, GNU Automake}), but the concept is the same even if
+Automake is not used.
+ at end defvar
+
+ at defvar configure_input
+ at ovindex configure_input
+A comment saying that the file was generated automatically by
+ at command{configure} and giving the name of the input file.
+ at code{AC_OUTPUT} adds a comment line containing this variable to the top
+of every makefile it creates. For other files, you should
+reference this variable in a comment at the top of each input file. For
+example, an input shell script should begin like this:
+
+ at example
+#!/bin/sh
+# @@configure_input@@
+ at end example
+
+ at noindent
+The presence of that line also reminds people editing the file that it
+needs to be processed by @command{configure} in order to be used.
+ at end defvar
+
+ at defvar CPPFLAGS
+ at evindex CPPFLAGS
+ at ovindex CPPFLAGS
+Preprocessor options for the C, C++, Objective C, and Objective C++
+preprocessors and compilers. If
+it is not set in the environment when @command{configure} runs, the default
+value is empty. @command{configure} uses this variable when preprocessing
+or compiling programs to test for C, C++, Objective C, and Objective C++
+features.
+
+This variable's contents should contain options like @option{-I},
+ at option{-D}, and @option{-U} that affect only the behavior of the
+preprocessor. Please see the explanation of @code{CFLAGS} for what you
+can do if an option affects other phases of the compiler as well.
+
+Currently, @command{configure} always links as part of a single
+invocation of the compiler that also preprocesses and compiles, so it
+uses this variable also when linking programs. However, it is unwise to
+depend on this behavior because the GNU Coding Standards do
+not require it and many packages do not use @code{CPPFLAGS} when linking
+programs.
+
+ at xref{Special Chars in Variables}, for limitations that @code{CPPFLAGS}
+might run into.
+ at end defvar
+
+ at defvar CXXFLAGS
+ at evindex CXXFLAGS
+ at ovindex CXXFLAGS
+Debugging and optimization options for the C++ compiler. It acts like
+ at code{CFLAGS}, but for C++ instead of C.
+ at end defvar
+
+ at defvar DEFS
+ at ovindex DEFS
+ at option{-D} options to pass to the C compiler. If @code{AC_CONFIG_HEADERS}
+is called, @command{configure} replaces @samp{@@DEFS@@} with
+ at option{-DHAVE_CONFIG_H} instead (@pxref{Configuration Headers}). This
+variable is not defined while @command{configure} is performing its tests,
+only when creating the output files. @xref{Setting Output Variables}, for
+how to check the results of previous tests.
+ at end defvar
+
+ at defvar ECHO_C
+ at defvarx ECHO_N
+ at defvarx ECHO_T
+ at ovindex ECHO_C
+ at ovindex ECHO_N
+ at ovindex ECHO_T
+How does one suppress the trailing newline from @command{echo} for
+question-answer message pairs? These variables provide a way:
+
+ at example
+echo $ECHO_N "And the winner is... $ECHO_C"
+sleep 100000000000
+echo "$@{ECHO_T@}dead."
+ at end example
+
+ at noindent
+Some old and uncommon @command{echo} implementations offer no means to
+achieve this, in which case @code{ECHO_T} is set to tab. You might not
+want to use it.
+ at end defvar
+
+ at defvar ERLCFLAGS
+ at evindex ERLCFLAGS
+ at ovindex ERLCFLAGS
+Debugging and optimization options for the Erlang compiler. If it is not set
+in the environment when @command{configure} runs, the default value is empty.
+ at command{configure} uses this variable when compiling
+programs to test for Erlang features.
+ at end defvar
+
+ at defvar FCFLAGS
+ at evindex FCFLAGS
+ at ovindex FCFLAGS
+Debugging and optimization options for the Fortran compiler. If it
+is not set in the environment when @command{configure} runs, the default
+value is set when you call @code{AC_PROG_FC} (or empty if you don't).
+ at command{configure} uses this variable when compiling or linking
+programs to test for Fortran features.
+ at end defvar
+
+ at defvar FFLAGS
+ at evindex FFLAGS
+ at ovindex FFLAGS
+Debugging and optimization options for the Fortran 77 compiler. If it
+is not set in the environment when @command{configure} runs, the default
+value is set when you call @code{AC_PROG_F77} (or empty if you don't).
+ at command{configure} uses this variable when compiling or linking
+programs to test for Fortran 77 features.
+ at end defvar
+
+ at defvar LDFLAGS
+ at evindex LDFLAGS
+ at ovindex LDFLAGS
+Options for the linker. If it is not set
+in the environment when @command{configure} runs, the default value is empty.
+ at command{configure} uses this variable when linking programs to test for
+C, C++, Objective C, Objective C++, Fortran, and Go features.
+
+This variable's contents should contain options like @option{-s} and
+ at option{-L} that affect only the behavior of the linker. Please see the
+explanation of @code{CFLAGS} for what you can do if an option also
+affects other phases of the compiler.
+
+Don't use this variable to pass library names
+(@option{-l}) to the linker; use @code{LIBS} instead.
+ at end defvar
+
+ at defvar LIBS
+ at evindex LIBS
+ at ovindex LIBS
+ at option{-l} options to pass to the linker. The default value is empty,
+but some Autoconf macros may prepend extra libraries to this variable if
+those libraries are found and provide necessary functions, see
+ at ref{Libraries}. @command{configure} uses this variable when linking
+programs to test for C, C++, Objective C, Objective C++, Fortran, and Go
+features.
+ at end defvar
+
+ at defvar OBJCFLAGS
+ at evindex OBJCFLAGS
+ at ovindex OBJCFLAGS
+Debugging and optimization options for the Objective C compiler. It
+acts like @code{CFLAGS}, but for Objective C instead of C.
+ at end defvar
+
+ at defvar OBJCXXFLAGS
+ at evindex OBJCXXFLAGS
+ at ovindex OBJCXXFLAGS
+Debugging and optimization options for the Objective C++ compiler. It
+acts like @code{CXXFLAGS}, but for Objective C++ instead of C++.
+ at end defvar
+
+ at defvar GOFLAGS
+ at evindex GOFLAGS
+ at ovindex GOFLAGS
+Debugging and optimization options for the Go compiler. It acts like
+ at code{CFLAGS}, but for Go instead of C.
+ at end defvar
+
+ at defvar builddir
+ at ovindex builddir
+Rigorously equal to @samp{.}. Added for symmetry only.
+ at end defvar
+
+ at defvar abs_builddir
+ at ovindex abs_builddir
+Absolute name of @code{builddir}.
+ at end defvar
+
+ at defvar top_builddir
+ at ovindex top_builddir
+The relative name of the top level of the current build tree. In the
+top-level directory, this is the same as @code{builddir}.
+ at end defvar
+
+ at defvar top_build_prefix
+ at ovindex top_build_prefix
+The relative name of the top level of the current build tree with final
+slash if nonempty. This is the same as @code{top_builddir}, except that
+it contains zero or more runs of @code{../}, so it should not be
+appended with a slash for concatenation. This helps for @command{make}
+implementations that otherwise do not treat @file{./file} and @file{file}
+as equal in the toplevel build directory.
+ at end defvar
+
+ at defvar abs_top_builddir
+ at ovindex abs_top_builddir
+Absolute name of @code{top_builddir}.
+ at end defvar
+
+ at defvar srcdir
+ at ovindex srcdir
+The name of the directory that contains the source code for
+that makefile.
+ at end defvar
+
+ at defvar abs_srcdir
+ at ovindex abs_srcdir
+Absolute name of @code{srcdir}.
+ at end defvar
+
+ at defvar top_srcdir
+ at ovindex top_srcdir
+The name of the top-level source code directory for the
+package. In the top-level directory, this is the same as @code{srcdir}.
+ at end defvar
+
+ at defvar abs_top_srcdir
+ at ovindex abs_top_srcdir
+Absolute name of @code{top_srcdir}.
+ at end defvar
+
+ at node Installation Directory Variables
+ at subsection Installation Directory Variables
+ at cindex Installation directories
+ at cindex Directories, installation
+
+The following variables specify the directories for
+package installation, see @ref{Directory Variables, , Variables for
+Installation Directories, standards, The GNU Coding
+Standards}, for more information. Each variable corresponds to an
+argument of @command{configure}; trailing slashes are stripped so that
+expressions such as @samp{$@{prefix@}/lib} expand with only one slash
+between directory names. See the end of this section for
+details on when and how to use these variables.
+
+ at defvar bindir
+ at ovindex bindir
+The directory for installing executables that users run.
+ at end defvar
+
+ at defvar datadir
+ at ovindex datadir
+The directory for installing idiosyncratic read-only
+architecture-independent data.
+ at end defvar
+
+ at defvar datarootdir
+ at ovindex datarootdir
+The root of the directory tree for read-only architecture-independent
+data files.
+ at end defvar
+
+ at defvar docdir
+ at ovindex docdir
+The directory for installing documentation files (other than Info and
+man).
+ at end defvar
+
+ at defvar dvidir
+ at ovindex dvidir
+The directory for installing documentation files in DVI format.
+ at end defvar
+
+ at defvar exec_prefix
+ at ovindex exec_prefix
+The installation prefix for architecture-dependent files. By default
+it's the same as @code{prefix}. You should avoid installing anything
+directly to @code{exec_prefix}. However, the default value for
+directories containing architecture-dependent files should be relative
+to @code{exec_prefix}.
+ at end defvar
+
+ at defvar htmldir
+ at ovindex htmldir
+The directory for installing HTML documentation.
+ at end defvar
+
+ at defvar includedir
+ at ovindex includedir
+The directory for installing C header files.
+ at end defvar
+
+ at defvar infodir
+ at ovindex infodir
+The directory for installing documentation in Info format.
+ at end defvar
+
+ at defvar libdir
+ at ovindex libdir
+The directory for installing object code libraries.
+ at end defvar
+
+ at defvar libexecdir
+ at ovindex libexecdir
+The directory for installing executables that other programs run.
+ at end defvar
+
+ at defvar localedir
+ at ovindex localedir
+The directory for installing locale-dependent but
+architecture-independent data, such as message catalogs. This directory
+usually has a subdirectory per locale.
+ at end defvar
+
+ at defvar localstatedir
+ at ovindex localstatedir
+The directory for installing modifiable single-machine data.
+ at end defvar
+
+ at defvar mandir
+ at ovindex mandir
+The top-level directory for installing documentation in man format.
+ at end defvar
+
+ at defvar oldincludedir
+ at ovindex oldincludedir
+The directory for installing C header files for non-GCC compilers.
+ at end defvar
+
+ at defvar pdfdir
+ at ovindex pdfdir
+The directory for installing PDF documentation.
+ at end defvar
+
+ at defvar prefix
+ at ovindex prefix
+The common installation prefix for all files. If @code{exec_prefix}
+is defined to a different value, @code{prefix} is used only for
+architecture-independent files.
+ at end defvar
+
+ at defvar psdir
+ at ovindex psdir
+The directory for installing PostScript documentation.
+ at end defvar
+
+ at defvar sbindir
+ at ovindex sbindir
+The directory for installing executables that system
+administrators run.
+ at end defvar
+
+ at defvar sharedstatedir
+ at ovindex sharedstatedir
+The directory for installing modifiable architecture-independent data.
+ at end defvar
+
+ at defvar sysconfdir
+ at ovindex sysconfdir
+The directory for installing read-only single-machine data.
+ at end defvar
+
+
+Most of these variables have values that rely on @code{prefix} or
+ at code{exec_prefix}. It is deliberate that the directory output
+variables keep them unexpanded: typically @samp{@@datarootdir@@} is
+replaced by @samp{$@{prefix@}/share}, not @samp{/usr/local/share}, and
+ at samp{@@datadir@@} is replaced by @samp{$@{datarootdir@}}.
+
+This behavior is mandated by the GNU Coding Standards, so that when
+the user runs:
+
+ at table @samp
+ at item make
+she can still specify a different prefix from the one specified to
+ at command{configure}, in which case, if needed, the package should hard
+code dependencies corresponding to the make-specified prefix.
+
+ at item make install
+she can specify a different installation location, in which case the
+package @emph{must} still depend on the location which was compiled in
+(i.e., never recompile when @samp{make install} is run). This is an
+extremely important feature, as many people may decide to install all
+the files of a package grouped together, and then install links from
+the final locations to there.
+ at end table
+
+In order to support these features, it is essential that
+ at code{datarootdir} remains defined as @samp{$@{prefix@}/share},
+so that its value can be expanded based
+on the current value of @code{prefix}.
+
+A corollary is that you should not use these variables except in
+makefiles. For instance, instead of trying to evaluate @code{datadir}
+in @file{configure} and hard-coding it in makefiles using
+e.g., @samp{AC_DEFINE_UNQUOTED([DATADIR], ["$datadir"], [Data directory.])},
+you should add
+ at option{-DDATADIR='$(datadir)'} to your makefile's definition of
+ at code{CPPFLAGS} (@code{AM_CPPFLAGS} if you are also using Automake).
+
+Similarly, you should not rely on @code{AC_CONFIG_FILES} to replace
+ at code{bindir} and friends in your shell scripts and other files; instead,
+let @command{make} manage their replacement. For instance Autoconf
+ships templates of its shell scripts ending with @samp{.in}, and uses a
+makefile snippet similar to the following to build scripts like
+ at command{autoheader} and @command{autom4te}:
+
+ at example
+ at group
+edit = sed \
+ -e 's|@@bindir[@@]|$(bindir)|g' \
+ -e 's|@@pkgdatadir[@@]|$(pkgdatadir)|g' \
+ -e 's|@@prefix[@@]|$(prefix)|g'
+ at end group
+
+ at group
+autoheader autom4te: Makefile
+ rm -f $@@ $@@.tmp
+ srcdir=''; \
+ test -f ./$@@.in || srcdir=$(srcdir)/; \
+ $(edit) $$@{srcdir@}$@@.in >$@@.tmp
+ at c $$ restore font-lock
+ chmod +x $@@.tmp
+ chmod a-w $@@.tmp
+ mv $@@.tmp $@@
+ at end group
+
+ at group
+autoheader: $(srcdir)/autoheader.in
+autom4te: $(srcdir)/autom4te.in
+ at end group
+ at end example
+
+Some details are noteworthy:
+
+ at table @asis
+ at item @samp{@@bindir[@@]}
+The brackets prevent @command{configure} from replacing
+ at samp{@@bindir@@} in the Sed expression itself.
+Brackets are preferable to a backslash here, since
+Posix says @samp{\@@} is not portable.
+
+ at item @samp{$(bindir)}
+Don't use @samp{@@bindir@@}! Use the matching makefile variable
+instead.
+
+ at item @samp{$(pkgdatadir)}
+The example takes advantage of the variable @samp{$(pkgdatadir)}
+provided by Automake; it is equivalent to @samp{$(datadir)/$(PACKAGE)}.
+
+ at item @samp{/}
+Don't use @samp{/} in the Sed expressions that replace file names since
+most likely the
+variables you use, such as @samp{$(bindir)}, contain @samp{/}.
+Use a shell metacharacter instead, such as @samp{|}.
+
+ at item special characters
+File names, file name components, and the value of @code{VPATH} should
+not contain shell metacharacters or white
+space. @xref{Special Chars in Variables}.
+
+ at item dependency on @file{Makefile}
+Since @code{edit} uses values that depend on the configuration specific
+values (@code{prefix}, etc.)@: and not only on @code{VERSION} and so forth,
+the output depends on @file{Makefile}, not @file{configure.ac}.
+
+ at item @samp{$@@}
+The main rule is generic, and uses @samp{$@@} extensively to
+avoid the need for multiple copies of the rule.
+
+ at item Separated dependencies and single suffix rules
+You can't use them! The above snippet cannot be (portably) rewritten
+as:
+
+ at example
+autoconf autoheader: Makefile
+ at group
+.in:
+ rm -f $@@ $@@.tmp
+ $(edit) $< >$@@.tmp
+ chmod +x $@@.tmp
+ mv $@@.tmp $@@
+ at end group
+ at end example
+
+ at xref{Single Suffix Rules}, for details.
+
+ at item @samp{$(srcdir)}
+Be sure to specify the name of the source directory,
+otherwise the package won't support separated builds.
+ at end table
+
+For the more specific installation of Erlang libraries, the following variables
+are defined:
+
+ at defvar ERLANG_INSTALL_LIB_DIR
+ at ovindex ERLANG_INSTALL_LIB_DIR
+ at acindex{ERLANG_SUBST_INSTALL_LIB_DIR}
+The common parent directory of Erlang library installation directories.
+This variable is set by calling the @code{AC_ERLANG_SUBST_INSTALL_LIB_DIR}
+macro in @file{configure.ac}.
+ at end defvar
+
+ at defvar ERLANG_INSTALL_LIB_DIR_ at var{library}
+ at ovindex ERLANG_INSTALL_LIB_DIR_ at var{library}
+ at acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR}
+The installation directory for Erlang library @var{library}.
+This variable is set by using the
+ at samp{AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR}
+macro in @file{configure.ac}.
+ at end defvar
+
+ at xref{Erlang Libraries}, for details.
+
+
+ at node Changed Directory Variables
+ at subsection Changed Directory Variables
+ at cindex @file{datarootdir}
+
+In Autoconf 2.60, the set of directory variables has changed, and the
+defaults of some variables have been adjusted
+(@pxref{Installation Directory Variables}) to changes in the
+GNU Coding Standards. Notably, @file{datadir}, @file{infodir}, and
+ at file{mandir} are now expressed in terms of @file{datarootdir}. If you are
+upgrading from an earlier Autoconf version, you may need to adjust your files
+to ensure that the directory variables are substituted correctly
+(@pxref{Defining Directories}), and that a definition of @file{datarootdir} is
+in place. For example, in a @file{Makefile.in}, adding
+
+ at example
+datarootdir = @@datarootdir@@
+ at end example
+
+ at noindent
+is usually sufficient. If you use Automake to create @file{Makefile.in},
+it will add this for you.
+
+To help with the transition, Autoconf warns about files that seem to use
+ at code{datarootdir} without defining it. In some cases, it then expands
+the value of @code{$datarootdir} in substitutions of the directory
+variables. The following example shows such a warning:
+
+ at example
+$ @kbd{cat configure.ac}
+AC_INIT
+AC_CONFIG_FILES([Makefile])
+AC_OUTPUT
+$ @kbd{cat Makefile.in}
+prefix = @@prefix@@
+datadir = @@datadir@@
+$ @kbd{autoconf}
+$ @kbd{configure}
+configure: creating ./config.status
+config.status: creating Makefile
+config.status: WARNING:
+ Makefile.in seems to ignore the --datarootdir setting
+$ @kbd{cat Makefile}
+prefix = /usr/local
+datadir = $@{prefix@}/share
+ at end example
+
+Usually one can easily change the file to accommodate both older and newer
+Autoconf releases:
+
+ at example
+$ @kbd{cat Makefile.in}
+prefix = @@prefix@@
+datarootdir = @@datarootdir@@
+datadir = @@datadir@@
+$ @kbd{configure}
+configure: creating ./config.status
+config.status: creating Makefile
+$ @kbd{cat Makefile}
+prefix = /usr/local
+datarootdir = $@{prefix@}/share
+datadir = $@{datarootdir@}
+ at end example
+
+ at acindex{DATAROOTDIR_CHECKED}
+In some cases, however, the checks may not be able to detect that a suitable
+initialization of @code{datarootdir} is in place, or they may fail to detect
+that such an initialization is necessary in the output file. If, after
+auditing your package, there are still spurious @file{configure} warnings about
+ at code{datarootdir}, you may add the line
+
+ at example
+AC_DEFUN([AC_DATAROOTDIR_CHECKED])
+ at end example
+
+ at noindent
+to your @file{configure.ac} to disable the warnings. This is an exception
+to the usual rule that you should not define a macro whose name begins with
+ at code{AC_} (@pxref{Macro Names}).
+
+
+
+ at node Build Directories
+ at subsection Build Directories
+ at cindex Build directories
+ at cindex Directories, build
+
+You can support compiling a software package for several architectures
+simultaneously from the same copy of the source code. The object files
+for each architecture are kept in their own directory.
+
+To support doing this, @command{make} uses the @code{VPATH} variable to
+find the files that are in the source directory. GNU Make
+can do this. Most other recent @command{make} programs can do this as
+well, though they may have difficulties and it is often simpler to
+recommend GNU @command{make} (@pxref{VPATH and Make}). Older
+ at command{make} programs do not support @code{VPATH}; when using them, the
+source code must be in the same directory as the object files.
+
+If you are using GNU Automake, the remaining details in this
+section are already covered for you, based on the contents of your
+ at file{Makefile.am}. But if you are using Autoconf in isolation, then
+supporting @code{VPATH} requires the following in your
+ at file{Makefile.in}:
+
+ at example
+srcdir = @@srcdir@@
+VPATH = @@srcdir@@
+ at end example
+
+Do not set @code{VPATH} to the value of another variable (@pxref{Variables
+listed in VPATH}.
+
+ at command{configure} substitutes the correct value for @code{srcdir} when
+it produces @file{Makefile}.
+
+Do not use the @command{make} variable @code{$<}, which expands to the
+file name of the file in the source directory (found with @code{VPATH}),
+except in implicit rules. (An implicit rule is one such as @samp{.c.o},
+which tells how to create a @file{.o} file from a @file{.c} file.) Some
+versions of @command{make} do not set @code{$<} in explicit rules; they
+expand it to an empty value.
+
+Instead, Make command lines should always refer to source
+files by prefixing them with @samp{$(srcdir)/}. For example:
+
+ at example
+time.info: time.texinfo
+ $(MAKEINFO) '$(srcdir)/time.texinfo'
+ at end example
+
+ at node Automatic Remaking
+ at subsection Automatic Remaking
+ at cindex Automatic remaking
+ at cindex Remaking automatically
+
+You can put rules like the following in the top-level @file{Makefile.in}
+for a package to automatically update the configuration information when
+you change the configuration files. This example includes all of the
+optional files, such as @file{aclocal.m4} and those related to
+configuration header files. Omit from the @file{Makefile.in} rules for
+any of these files that your package does not use.
+
+The @samp{$(srcdir)/} prefix is included because of limitations in the
+ at code{VPATH} mechanism.
+
+The @file{stamp-} files are necessary because the timestamps of
+ at file{config.h.in} and @file{config.h} are not changed if remaking
+them does not change their contents. This feature avoids unnecessary
+recompilation. You should include the file @file{stamp-h.in} in your
+package's distribution, so that @command{make} considers
+ at file{config.h.in} up to date. Don't use @command{touch}
+(@pxref{touch, , Limitations of Usual Tools}); instead, use
+ at command{echo} (using
+ at command{date} would cause needless differences, hence CVS
+conflicts, etc.).
+
+ at example
+ at group
+$(srcdir)/configure: configure.ac aclocal.m4
+ cd '$(srcdir)' && autoconf
+
+# autoheader might not change config.h.in, so touch a stamp file.
+$(srcdir)/config.h.in: stamp-h.in
+$(srcdir)/stamp-h.in: configure.ac aclocal.m4
+ cd '$(srcdir)' && autoheader
+ echo timestamp > '$(srcdir)/stamp-h.in'
+
+config.h: stamp-h
+stamp-h: config.h.in config.status
+ ./config.status
+
+Makefile: Makefile.in config.status
+ ./config.status
+
+config.status: configure
+ ./config.status --recheck
+ at end group
+ at end example
+
+ at noindent
+(Be careful if you copy these lines directly into your makefile, as you
+need to convert the indented lines to start with the tab character.)
+
+In addition, you should use
+
+ at example
+AC_CONFIG_FILES([stamp-h], [echo timestamp > stamp-h])
+ at end example
+
+ at noindent
+so @file{config.status} ensures that @file{config.h} is considered up to
+date. @xref{Output}, for more information about @code{AC_OUTPUT}.
+
+ at xref{config.status Invocation}, for more examples of handling
+configuration-related dependencies.
+
+ at node Configuration Headers
+ at section Configuration Header Files
+ at cindex Configuration Header
+ at cindex @file{config.h}
+
+When a package contains more than a few tests that define C preprocessor
+symbols, the command lines to pass @option{-D} options to the compiler
+can get quite long. This causes two problems. One is that the
+ at command{make} output is hard to visually scan for errors. More
+seriously, the command lines can exceed the length limits of some
+operating systems. As an alternative to passing @option{-D} options to
+the compiler, @command{configure} scripts can create a C header file
+containing @samp{#define} directives. The @code{AC_CONFIG_HEADERS}
+macro selects this kind of output. Though it can be called anywhere
+between @code{AC_INIT} and @code{AC_OUTPUT}, it is customary to call
+it right after @code{AC_INIT}.
+
+The package should @samp{#include} the configuration header file before
+any other header files, to prevent inconsistencies in declarations (for
+example, if it redefines @code{const}).
+
+To provide for VPATH builds, remember to pass the C compiler a @option{-I.}
+option (or @option{-I..}; whichever directory contains @file{config.h}).
+Even if you use @samp{#include "config.h"}, the preprocessor searches only
+the directory of the currently read file, i.e., the source directory, not
+the build directory.
+
+With the appropriate @option{-I} option, you can use
+ at samp{#include <config.h>}. Actually, it's a good habit to use it,
+because in the rare case when the source directory contains another
+ at file{config.h}, the build directory should be searched first.
+
+
+ at defmac AC_CONFIG_HEADERS (@var{header} @dots{}, @ovar{cmds}, @ovar{init-cmds})
+ at acindex{CONFIG_HEADERS}
+ at cvindex HAVE_CONFIG_H
+This macro is one of the instantiating macros; see @ref{Configuration
+Actions}. Make @code{AC_OUTPUT} create the file(s) in the
+blank-or-newline-separated list @var{header} containing C preprocessor
+ at code{#define} statements, and replace @samp{@@DEFS@@} in generated
+files with @option{-DHAVE_CONFIG_H} instead of the value of @code{DEFS}.
+The usual name for @var{header} is @file{config.h}.
+
+If @var{header} already exists and its contents are identical to what
+ at code{AC_OUTPUT} would put in it, it is left alone. Doing this allows
+making some changes in the configuration without needlessly causing
+object files that depend on the header file to be recompiled.
+
+Usually the input file is named @file{@var{header}.in}; however, you can
+override the input file name by appending to @var{header} a
+colon-separated list of input files. For example, you might need to make
+the input file name acceptable to DOS variants:
+
+ at example
+AC_CONFIG_HEADERS([config.h:config.hin])
+ at end example
+
+ at end defmac
+
+ at defmac AH_HEADER
+ at ahindex{HEADER}
+This macro is defined as the name of the first declared config header
+and undefined if no config headers have been declared up to this point.
+A third-party macro may, for example, require use of a config header
+without invoking AC_CONFIG_HEADERS twice, like this:
+
+ at example
+AC_CONFIG_COMMANDS_PRE(
+ [m4_ifndef([AH_HEADER], [AC_CONFIG_HEADERS([config.h])])])
+ at end example
+
+ at end defmac
+
+ at xref{Configuration Actions}, for more details on @var{header}.
+
+ at menu
+* Header Templates:: Input for the configuration headers
+* autoheader Invocation:: How to create configuration templates
+* Autoheader Macros:: How to specify CPP templates
+ at end menu
+
+ at node Header Templates
+ at subsection Configuration Header Templates
+ at cindex Configuration Header Template
+ at cindex Header templates
+ at cindex @file{config.h.in}
+
+Your distribution should contain a template file that looks as you want
+the final header file to look, including comments, with @code{#undef}
+statements which are used as hooks. For example, suppose your
+ at file{configure.ac} makes these calls:
+
+ at example
+AC_CONFIG_HEADERS([conf.h])
+AC_CHECK_HEADERS([unistd.h])
+ at end example
+
+ at noindent
+Then you could have code like the following in @file{conf.h.in}.
+The @file{conf.h} created by @command{configure} defines @samp{HAVE_UNISTD_H}
+to 1, if and only if the system has @file{unistd.h}.
+
+ at example
+ at group
+/* Define as 1 if you have unistd.h. */
+#undef HAVE_UNISTD_H
+ at end group
+ at end example
+
+The format of the template file is stricter than what the C preprocessor
+is required to accept. A directive line should contain only whitespace,
+ at samp{#undef}, and @samp{HAVE_UNISTD_H}. The use of @samp{#define}
+instead of @samp{#undef}, or of comments on the same line as
+ at samp{#undef}, is strongly discouraged. Each hook should only be listed
+once. Other preprocessor lines, such as @samp{#ifdef} or
+ at samp{#include}, are copied verbatim from the template into the
+generated header.
+
+Since it is a tedious task to keep a template header up to date, you may
+use @command{autoheader} to generate it, see @ref{autoheader Invocation}.
+
+During the instantiation of the header, each @samp{#undef} line in the
+template file for each symbol defined by @samp{AC_DEFINE} is changed to an
+appropriate @samp{#define}. If the corresponding @samp{AC_DEFINE} has not
+been executed during the @command{configure} run, the @samp{#undef} line is
+commented out. (This is important, e.g., for @samp{_POSIX_SOURCE}:
+on many systems, it can be implicitly defined by the compiler, and
+undefining it in the header would then break compilation of subsequent
+headers.)
+
+Currently, @emph{all} remaining @samp{#undef} lines in the header
+template are commented out, whether or not there was a corresponding
+ at samp{AC_DEFINE} for the macro name; but this behavior is not guaranteed
+for future releases of Autoconf.
+
+Generally speaking, since you should not use @samp{#define}, and you
+cannot guarantee whether a @samp{#undef} directive in the header
+template will be converted to a @samp{#define} or commented out in the
+generated header file, the template file cannot be used for conditional
+definition effects. Consequently, if you need to use the construct
+
+ at example
+ at group
+#ifdef THIS
+# define THAT
+#endif
+ at end group
+ at end example
+
+ at noindent
+you must place it outside of the template.
+If you absolutely need to hook it to the config header itself, please put
+the directives to a separate file, and @samp{#include} that file from the
+config header template. If you are using @command{autoheader}, you would
+probably use @samp{AH_BOTTOM} to append the @samp{#include} directive.
+
+
+ at node autoheader Invocation
+ at subsection Using @command{autoheader} to Create @file{config.h.in}
+ at cindex @command{autoheader}
+
+The @command{autoheader} program can create a template file of C
+ at samp{#define} statements for @command{configure} to use.
+It searches for the first invocation of @code{AC_CONFIG_HEADERS} in
+ at file{configure} sources to determine the name of the template.
+(If the first call of @code{AC_CONFIG_HEADERS} specifies more than one
+input file name, @command{autoheader} uses the first one.)
+
+It is recommended that only one input file is used. If you want to append
+a boilerplate code, it is preferable to use
+ at samp{AH_BOTTOM([#include <conf_post.h>])}.
+File @file{conf_post.h} is not processed during the configuration then,
+which make things clearer. Analogically, @code{AH_TOP} can be used to
+prepend a boilerplate code.
+
+In order to do its job, @command{autoheader} needs you to document all
+of the symbols that you might use. Typically this is done via an
+ at code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED} call whose first argument
+is a literal symbol and whose third argument describes the symbol
+(@pxref{Defining Symbols}). Alternatively, you can use
+ at code{AH_TEMPLATE} (@pxref{Autoheader Macros}), or you can supply a
+suitable input file for a subsequent configuration header file.
+Symbols defined by Autoconf's builtin tests are already documented properly;
+you need to document only those that you
+define yourself.
+
+You might wonder why @command{autoheader} is needed: after all, why
+would @command{configure} need to ``patch'' a @file{config.h.in} to
+produce a @file{config.h} instead of just creating @file{config.h} from
+scratch? Well, when everything rocks, the answer is just that we are
+wasting our time maintaining @command{autoheader}: generating
+ at file{config.h} directly is all that is needed. When things go wrong,
+however, you'll be thankful for the existence of @command{autoheader}.
+
+The fact that the symbols are documented is important in order to
+ at emph{check} that @file{config.h} makes sense. The fact that there is a
+well-defined list of symbols that should be defined (or not) is
+also important for people who are porting packages to environments where
+ at command{configure} cannot be run: they just have to @emph{fill in the
+blanks}.
+
+But let's come back to the point: the invocation of @command{autoheader}@dots{}
+
+If you give @command{autoheader} an argument, it uses that file instead
+of @file{configure.ac} and writes the header file to the standard output
+instead of to @file{config.h.in}. If you give @command{autoheader} an
+argument of @option{-}, it reads the standard input instead of
+ at file{configure.ac} and writes the header file to the standard output.
+
+ at command{autoheader} accepts the following options:
+
+ at table @option
+ at item --help
+ at itemx -h
+Print a summary of the command line options and exit.
+
+ at item --version
+ at itemx -V
+Print the version number of Autoconf and exit.
+
+ at item --verbose
+ at itemx -v
+Report processing steps.
+
+ at item --debug
+ at itemx -d
+Don't remove the temporary files.
+
+ at item --force
+ at itemx -f
+Remake the template file even if newer than its input files.
+
+ at item --include=@var{dir}
+ at itemx -I @var{dir}
+Append @var{dir} to the include path. Multiple invocations accumulate.
+
+ at item --prepend-include=@var{dir}
+ at itemx -B @var{dir}
+Prepend @var{dir} to the include path. Multiple invocations accumulate.
+
+ at item --warnings=@var{category}
+ at itemx -W @var{category}
+ at evindex WARNINGS
+Report the warnings related to @var{category} (which can actually be a
+comma separated list). Current categories include:
+
+ at table @samp
+ at item obsolete
+report the uses of obsolete constructs
+
+ at item all
+report all the warnings
+
+ at item none
+report none
+
+ at item error
+treats warnings as errors
+
+ at item no- at var{category}
+disable warnings falling into @var{category}
+ at end table
+
+ at end table
+
+
+
+ at node Autoheader Macros
+ at subsection Autoheader Macros
+ at cindex Autoheader macros
+
+ at command{autoheader} scans @file{configure.ac} and figures out which C
+preprocessor symbols it might define. It knows how to generate
+templates for symbols defined by @code{AC_CHECK_HEADERS},
+ at code{AC_CHECK_FUNCS} etc., but if you @code{AC_DEFINE} any additional
+symbol, you must define a template for it. If there are missing
+templates, @command{autoheader} fails with an error message.
+
+The template for a @var{symbol} is created
+by @command{autoheader} from
+the @var{description} argument to an @code{AC_DEFINE};
+see @ref{Defining Symbols}.
+
+For special needs, you can use the following macros.
+
+
+ at defmac AH_TEMPLATE (@var{key}, @var{description})
+ at ahindex{TEMPLATE}
+Tell @command{autoheader} to generate a template for @var{key}. This macro
+generates standard templates just like @code{AC_DEFINE} when a
+ at var{description} is given.
+
+For example:
+
+ at example
+AH_TEMPLATE([CRAY_STACKSEG_END],
+ [Define to one of _getb67, GETB67, getb67
+ for Cray-2 and Cray-YMP systems. This
+ function is required for alloca.c support
+ on those systems.])
+ at end example
+
+ at noindent
+generates the following template, with the description properly
+justified.
+
+ at example
+/* Define to one of _getb67, GETB67, getb67 for Cray-2 and
+ Cray-YMP systems. This function is required for alloca.c
+ support on those systems. */
+#undef CRAY_STACKSEG_END
+ at end example
+ at end defmac
+
+
+ at defmac AH_VERBATIM (@var{key}, @var{template})
+ at ahindex{VERBATIM}
+Tell @command{autoheader} to include the @var{template} as-is in the header
+template file. This @var{template} is associated with the @var{key},
+which is used to sort all the different templates and guarantee their
+uniqueness. It should be a symbol that can be defined via @code{AC_DEFINE}.
+ at end defmac
+
+
+ at defmac AH_TOP (@var{text})
+ at ahindex{TOP}
+Include @var{text} at the top of the header template file.
+ at end defmac
+
+
+ at defmac AH_BOTTOM (@var{text})
+ at ahindex{BOTTOM}
+Include @var{text} at the bottom of the header template file.
+ at end defmac
+
+
+Please note that @var{text} gets included ``verbatim'' to the template file,
+not to the resulting config header, so it can easily get mangled when the
+template is processed. There is rarely a need for something other than
+
+ at example
+AH_BOTTOM([#include <custom.h>])
+ at end example
+
+
+
+ at node Configuration Commands
+ at section Running Arbitrary Configuration Commands
+ at cindex Configuration commands
+ at cindex Commands for configuration
+
+You can execute arbitrary commands before, during, and after
+ at file{config.status} is run. The three following macros accumulate the
+commands to run when they are called multiple times.
+ at code{AC_CONFIG_COMMANDS} replaces the obsolete macro
+ at code{AC_OUTPUT_COMMANDS}; see @ref{Obsolete Macros}, for details.
+
+ at anchor{AC_CONFIG_COMMANDS}
+ at defmac AC_CONFIG_COMMANDS (@var{tag}@dots{}, @ovar{cmds}, @ovar{init-cmds})
+ at acindex{CONFIG_COMMANDS}
+Specify additional shell commands to run at the end of
+ at file{config.status}, and shell commands to initialize any variables
+from @command{configure}. Associate the commands with @var{tag}.
+Since typically the @var{cmds} create a file, @var{tag} should
+naturally be the name of that file. If needed, the directory hosting
+ at var{tag} is created. This macro is one of the instantiating macros;
+see @ref{Configuration Actions}.
+
+Here is an unrealistic example:
+ at example
+fubar=42
+AC_CONFIG_COMMANDS([fubar],
+ [echo this is extra $fubar, and so on.],
+ [fubar=$fubar])
+ at end example
+
+Here is a better one:
+ at example
+AC_CONFIG_COMMANDS([timestamp], [date >timestamp])
+ at end example
+ at end defmac
+
+The following two macros look similar, but in fact they are not of the same
+breed: they are executed directly by @file{configure}, so you cannot use
+ at file{config.status} to rerun them.
+
+ at c Yet it is good to leave them here. The user sees them together and
+ at c decides which best fits their needs.
+
+ at defmac AC_CONFIG_COMMANDS_PRE (@var{cmds})
+ at acindex{CONFIG_COMMANDS_PRE}
+Execute the @var{cmds} right before creating @file{config.status}.
+
+This macro presents the last opportunity to call @code{AC_SUBST},
+ at code{AC_DEFINE}, or @code{AC_CONFIG_ at var{ITEMS}} macros.
+ at end defmac
+
+ at defmac AC_CONFIG_COMMANDS_POST (@var{cmds})
+ at acindex{CONFIG_COMMANDS_POST}
+Execute the @var{cmds} right after creating @file{config.status}.
+ at end defmac
+
+
+
+
+ at node Configuration Links
+ at section Creating Configuration Links
+ at cindex Configuration links
+ at cindex Links for configuration
+
+You may find it convenient to create links whose destinations depend upon
+results of tests. One can use @code{AC_CONFIG_COMMANDS} but the
+creation of relative symbolic links can be delicate when the package is
+built in a directory different from the source directory.
+
+ at anchor{AC_CONFIG_LINKS}
+ at defmac AC_CONFIG_LINKS (@var{dest}:@var{source}@dots{}, @ovar{cmds}, @
+ @ovar{init-cmds})
+ at acindex{CONFIG_LINKS}
+ at cindex Links
+Make @code{AC_OUTPUT} link each of the existing files @var{source} to
+the corresponding link name @var{dest}. Makes a symbolic link if
+possible, otherwise a hard link if possible, otherwise a copy. The
+ at var{dest} and @var{source} names should be relative to the top level
+source or build directory. This macro is one of the instantiating
+macros; see @ref{Configuration Actions}.
+
+For example, this call:
+
+ at example
+AC_CONFIG_LINKS([host.h:config/$machine.h
+ object.h:config/$obj_format.h])
+ at end example
+
+ at noindent
+creates in the current directory @file{host.h} as a link to
+ at file{@var{srcdir}/config/$machine.h}, and @file{object.h} as a
+link to @file{@var{srcdir}/config/$obj_format.h}.
+
+The tempting value @samp{.} for @var{dest} is invalid: it makes it
+impossible for @samp{config.status} to guess the links to establish.
+
+One can then run:
+ at example
+./config.status host.h object.h
+ at end example
+ at noindent
+to create the links.
+ at end defmac
+
+
+
+ at node Subdirectories
+ at section Configuring Other Packages in Subdirectories
+ at cindex Configure subdirectories
+ at cindex Subdirectory configure
+
+In most situations, calling @code{AC_OUTPUT} is sufficient to produce
+makefiles in subdirectories. However, @command{configure} scripts
+that control more than one independent package can use
+ at code{AC_CONFIG_SUBDIRS} to run @command{configure} scripts for other
+packages in subdirectories.
+
+ at defmac AC_CONFIG_SUBDIRS (@var{dir} @dots{})
+ at acindex{CONFIG_SUBDIRS}
+ at ovindex subdirs
+Make @code{AC_OUTPUT} run @command{configure} in each subdirectory
+ at var{dir} in the given blank-or-newline-separated list. Each @var{dir} should
+be a literal, i.e., please do not use:
+
+ at example
+ at c If you change this example, adjust tests/torture.at:Non-literal AC_CONFIG_SUBDIRS.
+if test "x$package_foo_enabled" = xyes; then
+ my_subdirs="$my_subdirs foo"
+fi
+AC_CONFIG_SUBDIRS([$my_subdirs])
+ at end example
+
+ at noindent
+because this prevents @samp{./configure --help=recursive} from
+displaying the options of the package @code{foo}. Instead, you should
+write:
+
+ at example
+if test "x$package_foo_enabled" = xyes; then
+ AC_CONFIG_SUBDIRS([foo])
+fi
+ at end example
+
+If a given @var{dir} is not found at @command{configure} run time, a
+warning is reported; if the subdirectory is optional, write:
+
+ at example
+if test -d "$srcdir/foo"; then
+ AC_CONFIG_SUBDIRS([foo])
+fi
+ at end example
+
+ at c NB: Yes, below we mean configure.in, not configure.ac.
+If a given @var{dir} contains @command{configure.gnu}, it is run instead
+of @command{configure}. This is for packages that might use a
+non-Autoconf script @command{Configure}, which can't be called through a
+wrapper @command{configure} since it would be the same file on
+case-insensitive file systems. Likewise, if a @var{dir} contains
+ at file{configure.in} but no @command{configure}, the Cygnus
+ at command{configure} script found by @code{AC_CONFIG_AUX_DIR} is used.
+
+The subdirectory @command{configure} scripts are given the same command
+line options that were given to this @command{configure} script, with minor
+changes if needed, which include:
+
+ at itemize @minus
+ at item
+adjusting a relative name for the cache file;
+
+ at item
+adjusting a relative name for the source directory;
+
+ at item
+propagating the current value of @code{$prefix}, including if it was
+defaulted, and if the default values of the top level and of the subdirectory
+ at file{configure} differ.
+ at end itemize
+
+This macro also sets the output variable @code{subdirs} to the list of
+directories @samp{@var{dir} @dots{}}. Make rules can use
+this variable to determine which subdirectories to recurse into.
+
+This macro may be called multiple times.
+ at end defmac
+
+ at node Default Prefix
+ at section Default Prefix
+ at cindex Install prefix
+ at cindex Prefix for install
+
+By default, @command{configure} sets the prefix for files it installs to
+ at file{/usr/local}. The user of @command{configure} can select a different
+prefix using the @option{--prefix} and @option{--exec-prefix} options.
+There are two ways to change the default: when creating
+ at command{configure}, and when running it.
+
+Some software packages might want to install in a directory other than
+ at file{/usr/local} by default. To accomplish that, use the
+ at code{AC_PREFIX_DEFAULT} macro.
+
+ at defmac AC_PREFIX_DEFAULT (@var{prefix})
+ at acindex{PREFIX_DEFAULT}
+Set the default installation prefix to @var{prefix} instead of
+ at file{/usr/local}.
+ at end defmac
+
+It may be convenient for users to have @command{configure} guess the
+installation prefix from the location of a related program that they
+have already installed. If you wish to do that, you can call
+ at code{AC_PREFIX_PROGRAM}.
+
+ at anchor{AC_PREFIX_PROGRAM}
+ at defmac AC_PREFIX_PROGRAM (@var{program})
+ at acindex{PREFIX_PROGRAM}
+If the user did not specify an installation prefix (using the
+ at option{--prefix} option), guess a value for it by looking for
+ at var{program} in @env{PATH}, the way the shell does. If @var{program}
+is found, set the prefix to the parent of the directory containing
+ at var{program}, else default the prefix as described above
+(@file{/usr/local} or @code{AC_PREFIX_DEFAULT}). For example, if
+ at var{program} is @code{gcc} and the @env{PATH} contains
+ at file{/usr/local/gnu/bin/gcc}, set the prefix to @file{/usr/local/gnu}.
+ at end defmac
+
+
+
+ at c ======================================================== Existing tests
+
+ at node Existing Tests
+ at chapter Existing Tests
+
+These macros test for particular system features that packages might
+need or want to use. If you need to test for a kind of feature that
+none of these macros check for, you can probably do it by calling
+primitive test macros with appropriate arguments (@pxref{Writing
+Tests}).
+
+These tests print messages telling the user which feature they're
+checking for, and what they find. They cache their results for future
+ at command{configure} runs (@pxref{Caching Results}).
+
+Some of these macros set output variables. @xref{Makefile
+Substitutions}, for how to get their values. The phrase ``define
+ at var{name}'' is used below as a shorthand to mean ``define the C
+preprocessor symbol @var{name} to the value 1''. @xref{Defining
+Symbols}, for how to get those symbol definitions into your program.
+
+ at menu
+* 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
+ at end menu
+
+ at node Common Behavior
+ at section Common Behavior
+ at cindex Common autoconf behavior
+
+Much effort has been expended to make Autoconf easy to learn. The most
+obvious way to reach this goal is simply to enforce standard interfaces
+and behaviors, avoiding exceptions as much as possible. Because of
+history and inertia, unfortunately, there are still too many exceptions
+in Autoconf; nevertheless, this section describes some of the common
+rules.
+
+ at menu
+* Standard Symbols:: Symbols defined by the macros
+* Default Includes:: Includes used by the generic macros
+ at end menu
+
+ at node Standard Symbols
+ at subsection Standard Symbols
+ at cindex Standard symbols
+
+All the generic macros that @code{AC_DEFINE} a symbol as a result of
+their test transform their @var{argument} values to a standard alphabet.
+First, @var{argument} is converted to upper case and any asterisks
+(@samp{*}) are each converted to @samp{P}. Any remaining characters
+that are not alphanumeric are converted to underscores.
+
+For instance,
+
+ at example
+AC_CHECK_TYPES([struct $Expensive*])
+ at end example
+
+ at noindent
+defines the symbol @samp{HAVE_STRUCT__EXPENSIVEP} if the check
+succeeds.
+
+
+ at node Default Includes
+ at subsection Default Includes
+ at cindex Default includes
+ at cindex Includes, default
+
+Several tests depend upon a set of header files. Since these headers
+are not universally available, tests actually have to provide a set of
+protected includes, such as:
+
+ at example
+ at group
+#ifdef TIME_WITH_SYS_TIME
+# include <sys/time.h>
+# include <time.h>
+#else
+# ifdef HAVE_SYS_TIME_H
+# include <sys/time.h>
+# else
+# include <time.h>
+# endif
+#endif
+ at end group
+ at end example
+
+ at noindent
+Unless you know exactly what you are doing, you should avoid using
+unconditional includes, and check the existence of the headers you
+include beforehand (@pxref{Header Files}).
+
+Most generic macros use the following macro to provide the default set
+of includes:
+
+ at defmac AC_INCLUDES_DEFAULT (@ovar{include-directives})
+ at acindex{INCLUDES_DEFAULT}
+Expand to @var{include-directives} if defined, otherwise to:
+
+ at example
+ at group
+#include <stdio.h>
+#ifdef HAVE_SYS_TYPES_H
+# include <sys/types.h>
+#endif
+#ifdef HAVE_SYS_STAT_H
+# include <sys/stat.h>
+#endif
+#ifdef STDC_HEADERS
+# include <stdlib.h>
+# include <stddef.h>
+#else
+# ifdef HAVE_STDLIB_H
+# include <stdlib.h>
+# endif
+#endif
+#ifdef HAVE_STRING_H
+# if !defined STDC_HEADERS && defined HAVE_MEMORY_H
+# include <memory.h>
+# endif
+# include <string.h>
+#endif
+#ifdef HAVE_STRINGS_H
+# include <strings.h>
+#endif
+#ifdef HAVE_INTTYPES_H
+# include <inttypes.h>
+#endif
+#ifdef HAVE_STDINT_H
+# include <stdint.h>
+#endif
+#ifdef HAVE_UNISTD_H
+# include <unistd.h>
+#endif
+ at end group
+ at end example
+
+If the default includes are used, then check for the presence of these
+headers and their compatibility, i.e., you don't need to run
+ at code{AC_HEADER_STDC}, nor check for @file{stdlib.h} etc.
+
+These headers are checked for in the same order as they are included.
+For instance, on some systems @file{string.h} and @file{strings.h} both
+exist, but conflict. Then @code{HAVE_STRING_H} is defined, not
+ at code{HAVE_STRINGS_H}.
+ at end defmac
+
+ at node Alternative Programs
+ at section Alternative Programs
+ at cindex Programs, checking
+
+These macros check for the presence or behavior of particular programs.
+They are used to choose between several alternative programs and to
+decide what to do once one has been chosen. If there is no macro
+specifically defined to check for a program you need, and you don't need
+to check for any special properties of it, then you can use one of the
+general program-check macros.
+
+ at menu
+* Particular Programs:: Special handling to find certain programs
+* Generic Programs:: How to find other programs
+ at end menu
+
+ at node Particular Programs
+ at subsection Particular Program Checks
+
+These macros check for particular programs---whether they exist, and
+in some cases whether they support certain features.
+
+ at defmac AC_PROG_AWK
+ at acindex{PROG_AWK}
+ at ovindex AWK
+ at caindex prog_AWK
+Check for @code{gawk}, @code{mawk}, @code{nawk}, and @code{awk}, in that
+order, and set output variable @code{AWK} to the first one that is found.
+It tries @code{gawk} first because that is reported to be the
+best implementation. The result can be overridden by setting the
+variable @code{AWK} or the cache variable @code{ac_cv_prog_AWK}.
+
+Using this macro is sufficient to avoid the pitfalls of traditional
+ at command{awk} (@pxref{awk, , Limitations of Usual Tools}).
+ at end defmac
+
+ at defmac AC_PROG_GREP
+ at acindex{PROG_GREP}
+ at ovindex GREP
+ at caindex prog_GREP
+Look for the best available @code{grep} or @code{ggrep} that accepts the
+longest input lines possible, and that supports multiple @option{-e} options.
+Set the output variable @code{GREP} to whatever is chosen.
+ at xref{grep, , Limitations of Usual Tools}, for more information about
+portability problems with the @command{grep} command family. The result
+can be overridden by setting the @code{GREP} variable and is cached in the
+ at code{ac_cv_path_GREP} variable.
+ at end defmac
+
+ at defmac AC_PROG_EGREP
+ at acindex{PROG_EGREP}
+ at ovindex EGREP
+ at caindex prog_EGREP
+Check whether @code{$GREP -E} works, or else look for the best available
+ at code{egrep} or @code{gegrep} that accepts the longest input lines possible.
+Set the output variable @code{EGREP} to whatever is chosen. The result
+can be overridden by setting the @code{EGREP} variable and is cached in the
+ at code{ac_cv_path_EGREP} variable.
+ at end defmac
+
+ at defmac AC_PROG_FGREP
+ at acindex{PROG_FGREP}
+ at ovindex FGREP
+ at caindex prog_FGREP
+Check whether @code{$GREP -F} works, or else look for the best available
+ at code{fgrep} or @code{gfgrep} that accepts the longest input lines possible.
+Set the output variable @code{FGREP} to whatever is chosen. The result
+can be overridden by setting the @code{FGREP} variable and is cached in the
+ at code{ac_cv_path_FGREP} variable.
+ at end defmac
+
+ at defmac AC_PROG_INSTALL
+ at acindex{PROG_INSTALL}
+ at ovindex INSTALL
+ at ovindex INSTALL_PROGRAM
+ at ovindex INSTALL_DATA
+ at ovindex INSTALL_SCRIPT
+ at caindex path_install
+Set output variable @code{INSTALL} to the name of a BSD-compatible
+ at command{install} program, if one is found in the current @env{PATH}.
+Otherwise, set @code{INSTALL} to @samp{@var{dir}/install-sh -c},
+checking the directories specified to @code{AC_CONFIG_AUX_DIR} (or its
+default directories) to determine @var{dir} (@pxref{Output}). Also set
+the variables @code{INSTALL_PROGRAM} and @code{INSTALL_SCRIPT} to
+ at samp{$@{INSTALL@}} and @code{INSTALL_DATA} to @samp{$@{INSTALL@} -m 644}.
+
+ at samp{@@INSTALL@@} is special, as its value may vary for different
+configuration files.
+
+This macro screens out various instances of @command{install} known not to
+work. It prefers to find a C program rather than a shell script, for
+speed. Instead of @file{install-sh}, it can also use @file{install.sh},
+but that name is obsolete because some @command{make} programs have a rule
+that creates @file{install} from it if there is no makefile. Further, this
+macro requires @command{install} to be able to install multiple files into a
+target directory in a single invocation.
+
+Autoconf comes with a copy of @file{install-sh} that you can use. If
+you use @code{AC_PROG_INSTALL}, you must include either
+ at file{install-sh} or @file{install.sh} in your distribution; otherwise
+ at command{configure} produces an error message saying it can't find
+them---even if the system you're on has a good @command{install} program.
+This check is a safety measure to prevent you from accidentally leaving
+that file out, which would prevent your package from installing on
+systems that don't have a BSD-compatible @command{install} program.
+
+If you need to use your own installation program because it has features
+not found in standard @command{install} programs, there is no reason to use
+ at code{AC_PROG_INSTALL}; just put the file name of your program into your
+ at file{Makefile.in} files.
+
+The result of the test can be overridden by setting the variable
+ at code{INSTALL} or the cache variable @code{ac_cv_path_install}.
+ at end defmac
+
+ at defmac AC_PROG_MKDIR_P
+ at acindex{PROG_MKDIR_P}
+ at ovindex MKDIR_P
+ at caindex path_mkdir
+Set output variable @code{MKDIR_P} to a program that ensures that for
+each argument, a directory named by this argument exists, creating it
+and its parent directories if needed, and without race conditions when
+two instances of the program attempt to make the same directory at
+nearly the same time.
+
+This macro uses the @samp{mkdir -p} command if possible. Otherwise, it
+falls back on invoking @command{install-sh} with the @option{-d} option,
+so your package should
+contain @file{install-sh} as described under @code{AC_PROG_INSTALL}.
+An @file{install-sh} file that predates Autoconf 2.60 or Automake 1.10
+is vulnerable to race conditions, so if you want to support parallel
+installs from
+different packages into the same directory you need to make sure you
+have an up-to-date @file{install-sh}. In particular, be careful about
+using @samp{autoreconf -if} if your Automake predates Automake 1.10.
+
+This macro is related to the @code{AS_MKDIR_P} macro (@pxref{Programming
+in M4sh}), but it sets an output variable intended for use in other
+files, whereas @code{AS_MKDIR_P} is intended for use in scripts like
+ at command{configure}. Also, @code{AS_MKDIR_P} does not accept options,
+but @code{MKDIR_P} supports the @option{-m} option, e.g., a makefile
+might invoke @code{$(MKDIR_P) -m 0 dir} to create an inaccessible
+directory, and conversely a makefile should use @code{$(MKDIR_P) --
+$(FOO)} if @var{FOO} might yield a value that begins with @samp{-}.
+Finally, @code{AS_MKDIR_P} does not check for race condition
+vulnerability, whereas @code{AC_PROG_MKDIR_P} does.
+
+ at samp{@@MKDIR_P@@} is special, as its value may vary for different
+configuration files.
+
+The result of the test can be overridden by setting the variable
+ at code{MKDIR_P} or the cache variable @code{ac_cv_path_mkdir}.
+ at end defmac
+
+ at anchor{AC_PROG_LEX}
+ at defmac AC_PROG_LEX
+ at acindex{PROG_LEX}
+ at ovindex LEX
+ at ovindex LEXLIB
+ at cvindex YYTEXT_POINTER
+ at ovindex LEX_OUTPUT_ROOT
+ at caindex prog_LEX
+If @code{flex} is found, set output variable @code{LEX} to @samp{flex}
+and @code{LEXLIB} to @option{-lfl}, if that library is in a standard
+place. Otherwise set @code{LEX} to @samp{lex} and @code{LEXLIB} to
+ at option{-ll}, if found. If neither variant is available, set @code{LEX}
+to @samp{:}; for packages that ship the generated @file{file.yy.c}
+alongside the source @file{file.l}, this default allows users without a
+lexer generator to still build the package even if the timestamp for
+ at file{file.l} is inadvertently changed.
+
+Define @code{YYTEXT_POINTER} if @code{yytext} defaults to @samp{char *} instead
+of to @samp{char []}. Also set output variable @code{LEX_OUTPUT_ROOT} to
+the base of the file name that the lexer generates; usually
+ at file{lex.yy}, but sometimes something else. These results vary
+according to whether @code{lex} or @code{flex} is being used.
+
+You are encouraged to use Flex in your sources, since it is both more
+pleasant to use than plain Lex and the C source it produces is portable.
+In order to ensure portability, however, you must either provide a
+function @code{yywrap} or, if you don't use it (e.g., your scanner has
+no @samp{#include}-like feature), simply include a @samp{%noyywrap}
+statement in the scanner's source. Once this done, the scanner is
+portable (unless @emph{you} felt free to use nonportable constructs) and
+does not depend on any library. In this case, and in this case only, it
+is suggested that you use this Autoconf snippet:
+
+ at example
+AC_PROG_LEX
+if test "x$LEX" != xflex; then
+ LEX="$SHELL $missing_dir/missing flex"
+ AC_SUBST([LEX_OUTPUT_ROOT], [lex.yy])
+ AC_SUBST([LEXLIB], [''])
+fi
+ at end example
+
+The shell script @command{missing} can be found in the Automake
+distribution.
+
+Remember that the user may have supplied an alternate location in
+ at env{LEX}, so if Flex is required, it is better to check that the user
+provided something sufficient by parsing the output of @samp{$LEX
+--version} than by simply relying on @code{test "x$LEX" = xflex}.
+
+To ensure backward compatibility, Automake's @code{AM_PROG_LEX} invokes
+(indirectly) this macro twice, which causes an annoying but benign
+``@code{AC_PROG_LEX} invoked multiple times'' warning. Future versions
+of Automake will fix this issue; meanwhile, just ignore this message.
+
+As part of running the test, this macro may delete any file in the
+configuration directory named @file{lex.yy.c} or @file{lexyy.c}.
+
+The result of this test can be influenced by setting the variable
+ at code{LEX} or the cache variable @code{ac_cv_prog_LEX}.
+ at end defmac
+
+ at anchor{AC_PROG_LN_S}
+ at defmac AC_PROG_LN_S
+ at acindex{PROG_LN_S}
+ at ovindex LN_S
+If @samp{ln -s} works on the current file system (the operating system
+and file system support symbolic links), set the output variable
+ at code{LN_S} to @samp{ln -s}; otherwise, if @samp{ln} works, set
+ at code{LN_S} to @samp{ln}, and otherwise set it to @samp{cp -pR}.
+
+If you make a link in a directory other than the current directory, its
+meaning depends on whether @samp{ln} or @samp{ln -s} is used. To safely
+create links using @samp{$(LN_S)}, either find out which form is used
+and adjust the arguments, or always invoke @code{ln} in the directory
+where the link is to be created.
+
+In other words, it does not work to do:
+ at example
+$(LN_S) foo /x/bar
+ at end example
+
+Instead, do:
+
+ at example
+(cd /x && $(LN_S) foo bar)
+ at end example
+ at end defmac
+
+ at defmac AC_PROG_RANLIB
+ at acindex{PROG_RANLIB}
+ at ovindex RANLIB
+ at c @caindex prog_RANLIB
+ at c @caindex prog_ac_ct_RANLIB
+Set output variable @code{RANLIB} to @samp{ranlib} if @code{ranlib}
+is found, and otherwise to @samp{:} (do nothing).
+ at end defmac
+
+ at defmac AC_PROG_SED
+ at acindex{PROG_SED}
+ at ovindex SED
+ at caindex path_SED
+Set output variable @code{SED} to a Sed implementation that conforms to
+Posix and does not have arbitrary length limits. Report an error if no
+acceptable Sed is found. @xref{sed, , Limitations of Usual Tools}, for more
+information about portability problems with Sed.
+
+The result of this test can be overridden by setting the @code{SED} variable
+and is cached in the @code{ac_cv_path_SED} variable.
+ at end defmac
+
+ at defmac AC_PROG_YACC
+ at acindex{PROG_YACC}
+ at evindex YACC
+ at evindex YFLAGS
+ at ovindex YACC
+ at caindex prog_YACC
+If @code{bison} is found, set output variable @code{YACC} to @samp{bison
+-y}. Otherwise, if @code{byacc} is found, set @code{YACC} to
+ at samp{byacc}. Otherwise set @code{YACC} to @samp{yacc}.
+The result of this test can be influenced by setting the variable
+ at code{YACC} or the cache variable @code{ac_cv_prog_YACC}.
+ at end defmac
+
+ at node Generic Programs
+ at subsection Generic Program and File Checks
+
+These macros are used to find programs not covered by the ``particular''
+test macros. If you need to check the behavior of a program as well as
+find out whether it is present, you have to write your own test for it
+(@pxref{Writing Tests}). By default, these macros use the environment
+variable @env{PATH}. If you need to check for a program that might not
+be in the user's @env{PATH}, you can pass a modified path to use
+instead, like this:
+
+ at example
+AC_PATH_PROG([INETD], [inetd], [/usr/libexec/inetd],
+ [$PATH$PATH_SEPARATOR/usr/libexec$PATH_SEPARATOR]dnl
+[/usr/sbin$PATH_SEPARATOR/usr/etc$PATH_SEPARATOR/etc])
+ at end example
+
+You are strongly encouraged to declare the @var{variable} passed to
+ at code{AC_CHECK_PROG} etc.@: as precious. @xref{Setting Output Variables},
+ at code{AC_ARG_VAR}, for more details.
+
+ at anchor{AC_CHECK_PROG}
+ at defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @
+ @var{value-if-found}, @ovar{value-if-not-found}, @dvar{path, $PATH}, @
+ @ovar{reject})
+ at acindex{CHECK_PROG}
+ at caindex prog_ at var{variable}
+Check whether program @var{prog-to-check-for} exists in @var{path}. If
+it is found, set @var{variable} to @var{value-if-found}, otherwise to
+ at var{value-if-not-found}, if given. Always pass over @var{reject} (an
+absolute file name) even if it is the first found in the search path; in
+that case, set @var{variable} using the absolute file name of the
+ at var{prog-to-check-for} found that is not @var{reject}. If
+ at var{variable} was already set, do nothing. Calls @code{AC_SUBST} for
+ at var{variable}. The result of this test can be overridden by setting the
+ at var{variable} variable or the cache variable
+ at code{ac_cv_prog_ at var{variable}}.
+ at end defmac
+
+ at anchor{AC_CHECK_PROGS}
+ at defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for}, @
+ @ovar{value-if-not-found}, @dvar{path, $PATH})
+ at acindex{CHECK_PROGS}
+ at caindex prog_ at var{variable}
+Check for each program in the blank-separated list
+ at var{progs-to-check-for} existing in the @var{path}. If one is found, set
+ at var{variable} to the name of that program. Otherwise, continue
+checking the next program in the list. If none of the programs in the
+list are found, set @var{variable} to @var{value-if-not-found}; if
+ at var{value-if-not-found} is not specified, the value of @var{variable}
+is not changed. Calls @code{AC_SUBST} for @var{variable}. The result of
+this test can be overridden by setting the @var{variable} variable or the
+cache variable @code{ac_cv_prog_ at var{variable}}.
+ at end defmac
+
+ at defmac AC_CHECK_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @
+ @ovar{value-if-not-found}, @dvar{path, $PATH})
+ at acindex{CHECK_TARGET_TOOL}
+Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
+with a prefix of the target type as determined by
+ at code{AC_CANONICAL_TARGET}, followed by a dash (@pxref{Canonicalizing}).
+If the tool cannot be found with a prefix, and if the build and target
+types are equal, then it is also searched for without a prefix.
+
+As noted in @ref{Specifying Target Triplets}, the
+target is rarely specified, because most of the time it is the same
+as the host: it is the type of system for which any compiler tool in
+the package produces code. What this macro looks for is,
+for example, @emph{a tool @r{(assembler, linker, etc.)}@: that the
+compiler driver @r{(@command{gcc} for the GNU C Compiler)}
+uses to produce objects, archives or executables}.
+ at end defmac
+
+ at defmac AC_CHECK_TOOL (@var{variable}, @var{prog-to-check-for}, @
+ @ovar{value-if-not-found}, @dvar{path, $PATH})
+ at acindex{CHECK_TOOL}
+ at c @caindex prog_ at var{VARIABLE}
+ at c @caindex prog_ac_ct_ at var{VARIABLE}
+Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
+with a prefix of the host type as specified by @option{--host}, followed by a
+dash. For example, if the user runs
+ at samp{configure --build=x86_64-gnu --host=i386-gnu}, then this call:
+ at example
+AC_CHECK_TOOL([RANLIB], [ranlib], [:])
+ at end example
+ at noindent
+sets @code{RANLIB} to @file{i386-gnu-ranlib} if that program exists in
+ at var{path}, or otherwise to @samp{ranlib} if that program exists in
+ at var{path}, or to @samp{:} if neither program exists.
+
+When cross-compiling, this macro will issue a warning if no program
+prefixed with the host type could be found.
+For more information, see @ref{Specifying Target Triplets}.
+ at end defmac
+
+ at defmac AC_CHECK_TARGET_TOOLS (@var{variable}, @var{progs-to-check-for}, @
+ @ovar{value-if-not-found}, @dvar{path, $PATH})
+ at acindex{CHECK_TARGET_TOOLS}
+Like @code{AC_CHECK_TARGET_TOOL}, each of the tools in the list
+ at var{progs-to-check-for} are checked with a prefix of the target type as
+determined by @code{AC_CANONICAL_TARGET}, followed by a dash
+(@pxref{Canonicalizing}). If none of the tools can be found with a
+prefix, and if the build and target types are equal, then the first one
+without a prefix is used. If a tool is found, set @var{variable} to
+the name of that program. If none of the tools in the list are found,
+set @var{variable} to @var{value-if-not-found}; if @var{value-if-not-found}
+is not specified, the value of @var{variable} is not changed. Calls
+ at code{AC_SUBST} for @var{variable}.
+ at end defmac
+
+ at defmac AC_CHECK_TOOLS (@var{variable}, @var{progs-to-check-for}, @
+ @ovar{value-if-not-found}, @dvar{path, $PATH})
+ at acindex{CHECK_TOOLS}
+Like @code{AC_CHECK_TOOL}, each of the tools in the list
+ at var{progs-to-check-for} are checked with a prefix of the host type as
+determined by @code{AC_CANONICAL_HOST}, followed by a dash
+(@pxref{Canonicalizing}). If none of the tools can be found with a
+prefix, then the first one without a prefix is used. If a tool is found,
+set @var{variable} to the name of that program. If none of the tools in
+the list are found, set @var{variable} to @var{value-if-not-found}; if
+ at var{value-if-not-found} is not specified, the value of @var{variable}
+is not changed. Calls @code{AC_SUBST} for @var{variable}.
+
+When cross-compiling, this macro will issue a warning if no program
+prefixed with the host type could be found.
+For more information, see @ref{Specifying Target Triplets}.
+ at end defmac
+
+ at anchor{AC_PATH_PROG}
+ at defmac AC_PATH_PROG (@var{variable}, @var{prog-to-check-for}, @
+ @ovar{value-if-not-found}, @dvar{path, $PATH})
+ at acindex{PATH_PROG}
+ at caindex path_ at var{variable}
+Like @code{AC_CHECK_PROG}, but set @var{variable} to the absolute
+name of @var{prog-to-check-for} if found. The result of this test
+can be overridden by setting the @var{variable} variable. A positive
+result of this test is cached in the @code{ac_cv_path_ at var{variable}}
+variable.
+ at end defmac
+
+ at anchor{AC_PATH_PROGS}
+ at defmac AC_PATH_PROGS (@var{variable}, @var{progs-to-check-for}, @
+ @ovar{value-if-not-found}, @dvar{path, $PATH})
+ at acindex{PATH_PROGS}
+ at caindex path_ at var{variable}
+Like @code{AC_CHECK_PROGS}, but if any of @var{progs-to-check-for}
+are found, set @var{variable} to the absolute name of the program
+found. The result of this test can be overridden by setting the
+ at var{variable} variable. A positive result of this test is cached in
+the @code{ac_cv_path_ at var{variable}} variable.
+ at end defmac
+
+ at defmac AC_PATH_PROGS_FEATURE_CHECK (@var{variable}, @
+ @var{progs-to-check-for}, @var{feature-test}, @
+ @ovar{action-if-not-found}, @dvar{path, $PATH})
+ at acindex{PATH_PROGS_FEATURE_CHECK}
+ at caindex path_ at var{variable}
+ at vrindex ac_path_ at var{variable}
+ at vrindex ac_path_ at var{variable}_found
+This macro was introduced in Autoconf 2.62. If @var{variable} is not
+empty, then set the cache variable @code{ac_cv_path_ at var{variable}} to
+its value. Otherwise, check for each program in the blank-separated
+list @var{progs-to-check-for} existing in @var{path}. For each program
+found, execute @var{feature-test} with @code{ac_path_ at var{variable}}
+set to the absolute name of the candidate program. If no invocation of
+ at var{feature-test} sets the shell variable
+ at code{ac_cv_path_ at var{variable}}, then @var{action-if-not-found} is
+executed. @var{feature-test} will be run even when
+ at code{ac_cv_path_ at var{variable}} is set, to provide the ability to
+choose a better candidate found later in @var{path}; to accept the
+current setting and bypass all further checks, @var{feature-test} can
+execute @code{ac_path_ at var{variable}_found=:}.
+
+Note that this macro has some subtle differences from
+ at code{AC_CHECK_PROGS}. It is designed to be run inside
+ at code{AC_CACHE_VAL}, therefore, it should have no side effects. In
+particular, @var{variable} is not set to the final value of
+ at code{ac_cv_path_ at var{variable}}, nor is @code{AC_SUBST} automatically
+run. Also, on failure, any action can be performed, whereas
+ at code{AC_CHECK_PROGS} only performs
+ at code{@var{variable}=@var{value-if-not-found}}.
+
+Here is an example, similar to what Autoconf uses in its own configure
+script. It will search for an implementation of @command{m4} that
+supports the @code{indir} builtin, even if it goes by the name
+ at command{gm4} or is not the first implementation on @env{PATH}.
+
+ at example
+AC_CACHE_CHECK([for m4 that supports indir], [ac_cv_path_M4],
+ [AC_PATH_PROGS_FEATURE_CHECK([M4], [m4 gm4],
+ [[m4out=`echo 'changequote([,])indir([divnum])' | $ac_path_M4`
+ test "x$m4out" = x0 \
+ && ac_cv_path_M4=$ac_path_M4 ac_path_M4_found=:]],
+ [AC_MSG_ERROR([could not find m4 that supports indir])])])
+AC_SUBST([M4], [$ac_cv_path_M4])
+ at end example
+ at end defmac
+
+ at defmac AC_PATH_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @
+ @ovar{value-if-not-found}, @dvar{path, $PATH})
+ at acindex{PATH_TARGET_TOOL}
+Like @code{AC_CHECK_TARGET_TOOL}, but set @var{variable} to the absolute
+name of the program if it is found.
+ at end defmac
+
+ at defmac AC_PATH_TOOL (@var{variable}, @var{prog-to-check-for}, @
+ @ovar{value-if-not-found}, @dvar{path, $PATH})
+ at acindex{PATH_TOOL}
+Like @code{AC_CHECK_TOOL}, but set @var{variable} to the absolute
+name of the program if it is found.
+
+When cross-compiling, this macro will issue a warning if no program
+prefixed with the host type could be found.
+For more information, see @ref{Specifying Target Triplets}.
+ at end defmac
+
+
+ at node Files
+ at section Files
+ at cindex File, checking
+
+You might also need to check for the existence of files. Before using
+these macros, ask yourself whether a runtime test might not be a better
+solution. Be aware that, like most Autoconf macros, they test a feature
+of the host machine, and therefore, they die when cross-compiling.
+
+ at defmac AC_CHECK_FILE (@var{file}, @ovar{action-if-found}, @
+ @ovar{action-if-not-found})
+ at acindex{CHECK_FILE}
+ at caindex file_ at var{file}
+Check whether file @var{file} exists on the native system. If it is
+found, execute @var{action-if-found}, otherwise do
+ at var{action-if-not-found}, if given. The result of this test is cached
+in the @code{ac_cv_file_ at var{file}} variable, with characters not
+suitable for a variable name mapped to underscores.
+ at end defmac
+
+ at defmac AC_CHECK_FILES (@var{files}, @ovar{action-if-found}, @
+ @ovar{action-if-not-found})
+ at acindex{CHECK_FILES}
+ at caindex file_ at var{file}
+Executes @code{AC_CHECK_FILE} once for each file listed in @var{files}.
+Additionally, defines @samp{HAVE_ at var{file}} (@pxref{Standard Symbols})
+for each file found. The results of each test are cached in the
+ at code{ac_cv_file_ at var{file}} variable, with characters not suitable for
+a variable name mapped to underscores.
+ at end defmac
+
+
+ at node Libraries
+ at section Library Files
+ at cindex Library, checking
+
+The following macros check for the presence of certain C, C++, Fortran,
+or Go library archive files.
+
+ at anchor{AC_CHECK_LIB}
+ at defmac AC_CHECK_LIB (@var{library}, @var{function}, @
+ @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
+ at acindex{CHECK_LIB}
+ at caindex lib_ at var{library}_ at var{function}
+Test whether the library @var{library} is available by trying to link
+a test program that calls function @var{function} with the library.
+ at var{function} should be a function provided by the library.
+Use the base
+name of the library; e.g., to check for @option{-lmp}, use @samp{mp} as
+the @var{library} argument.
+
+ at var{action-if-found} is a list of shell commands to run if the link
+with the library succeeds; @var{action-if-not-found} is a list of shell
+commands to run if the link fails. If @var{action-if-found} is not
+specified, the default action prepends @option{-l at var{library}} to
+ at code{LIBS} and defines @samp{HAVE_LIB at var{library}} (in all
+capitals). This macro is intended to support building @code{LIBS} in
+a right-to-left (least-dependent to most-dependent) fashion such that
+library dependencies are satisfied as a natural side effect of
+consecutive tests. Linkers are sensitive to library ordering
+so the order in which @code{LIBS} is generated is important to reliable
+detection of libraries.
+
+If linking with @var{library} results in unresolved symbols that would
+be resolved by linking with additional libraries, give those libraries
+as the @var{other-libraries} argument, separated by spaces:
+e.g., @option{-lXt -lX11}. Otherwise, this macro may fail to detect
+that @var{library} is present, because linking the test program can
+fail with unresolved symbols. The @var{other-libraries} argument
+should be limited to cases where it is desirable to test for one library
+in the presence of another that is not already in @code{LIBS}.
+
+ at code{AC_CHECK_LIB} requires some care in usage, and should be avoided
+in some common cases. Many standard functions like @code{gethostbyname}
+appear in the standard C library on some hosts, and in special libraries
+like @code{nsl} on other hosts. On some hosts the special libraries
+contain variant implementations that you may not want to use. These
+days it is normally better to use @code{AC_SEARCH_LIBS([gethostbyname],
+[nsl])} instead of @code{AC_CHECK_LIB([nsl], [gethostbyname])}.
+
+The result of this test is cached in the
+ at code{ac_cv_lib_ at var{library}_ at var{function}} variable.
+ at end defmac
+
+ at anchor{AC_SEARCH_LIBS}
+ at defmac AC_SEARCH_LIBS (@var{function}, @var{search-libs}, @
+ @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
+ at acindex{SEARCH_LIBS}
+ at caindex search_ at var{function}
+Search for a library defining @var{function} if it's not already
+available. This equates to calling
+ at samp{AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])])} first with
+no libraries, then for each library listed in @var{search-libs}.
+
+Prepend @option{-l at var{library}} to @code{LIBS} for the first library found
+to contain @var{function}, and run @var{action-if-found}. If the
+function is not found, run @var{action-if-not-found}.
+
+If linking with @var{library} results in unresolved symbols that would
+be resolved by linking with additional libraries, give those libraries
+as the @var{other-libraries} argument, separated by spaces:
+e.g., @option{-lXt -lX11}. Otherwise, this macro fails to detect
+that @var{function} is present, because linking the test program
+always fails with unresolved symbols.
+
+The result of this test is cached in the
+ at code{ac_cv_search_ at var{function}} variable as @samp{none required} if
+ at var{function} is already available, as @samp{no} if no library
+containing @var{function} was found, otherwise as the
+ at option{-l at var{library}} option that needs to be prepended to @code{LIBS}.
+ at end defmac
+
+
+
+ at node Library Functions
+ at section Library Functions
+
+The following macros check for particular C library functions.
+If there is no macro specifically defined to check for a function you need,
+and you don't need to check for any special properties of
+it, then you can use one of the general function-check macros.
+
+ at menu
+* Function Portability:: Pitfalls with usual functions
+* Particular Functions:: Special handling to find certain functions
+* Generic Functions:: How to find other functions
+ at end menu
+
+ at node Function Portability
+ at subsection Portability of C Functions
+ at cindex Portability of C functions
+ at cindex C function portability
+
+Most usual functions can either be missing, or be buggy, or be limited
+on some architectures. This section tries to make an inventory of these
+portability issues. By definition, this list always requires
+additions. A much more complete list is maintained by the Gnulib
+project (@pxref{Gnulib}), covering @ref{Function Substitutes, ,
+Current Posix Functions, gnulib, GNU gnulib}, @ref{Legacy Function
+Substitutes, , Legacy Functions, gnulib, GNU gnulib}, and @ref{Glibc
+Function Substitutes, , Glibc Functions, gnulib, GNU gnulib}. Please
+help us keep the gnulib list as complete as possible.
+
+ at table @asis
+ at item @code{exit}
+ at c @fuindex exit
+ at prindex @code{exit}
+On ancient hosts, @code{exit} returned @code{int}.
+This is because @code{exit} predates @code{void}, and there was a long
+tradition of it returning @code{int}.
+
+On current hosts, the problem more likely is that @code{exit} is not
+declared, due to C++ problems of some sort or another. For this reason
+we suggest that test programs not invoke @code{exit}, but return from
+ at code{main} instead.
+
+ at item @code{free}
+ at c @fuindex free
+ at prindex @code{free}
+The C standard says a call @code{free (NULL)} does nothing, but
+some old systems don't support this (e.g., NextStep).
+
+ at item @code{isinf}
+ at itemx @code{isnan}
+ at c @fuindex isinf
+ at c @fuindex isnan
+ at prindex @code{isinf}
+ at prindex @code{isnan}
+The C99 standard says that @code{isinf} and @code{isnan} are
+macros. On some systems just macros are available
+(e.g., HP-UX and Solaris 10), on
+some systems both macros and functions (e.g., glibc 2.3.2), and on some
+systems only functions (e.g., IRIX 6 and Solaris 9). In some cases
+these functions are declared in nonstandard headers like
+ at code{<sunmath.h>} and defined in non-default libraries like
+ at option{-lm} or @option{-lsunmath}.
+
+The C99 @code{isinf} and @code{isnan} macros work correctly with
+ at code{long double} arguments, but pre-C99 systems that use functions
+typically assume @code{double} arguments. On such a system,
+ at code{isinf} incorrectly returns true for a finite @code{long double}
+argument that is outside the range of @code{double}.
+
+The best workaround for these issues is to use gnulib modules
+ at code{isinf} and @code{isnan} (@pxref{Gnulib}). But a lighter weight
+solution involves code like the following.
+
+ at smallexample
+#include <math.h>
+
+#ifndef isnan
+# define isnan(x) \
+ (sizeof (x) == sizeof (long double) ? isnan_ld (x) \
+ : sizeof (x) == sizeof (double) ? isnan_d (x) \
+ : isnan_f (x))
+static inline int isnan_f (float x) @{ return x != x; @}
+static inline int isnan_d (double x) @{ return x != x; @}
+static inline int isnan_ld (long double x) @{ return x != x; @}
+#endif
+
+#ifndef isinf
+# define isinf(x) \
+ (sizeof (x) == sizeof (long double) ? isinf_ld (x) \
+ : sizeof (x) == sizeof (double) ? isinf_d (x) \
+ : isinf_f (x))
+static inline int isinf_f (float x)
+@{ return !isnan (x) && isnan (x - x); @}
+static inline int isinf_d (double x)
+@{ return !isnan (x) && isnan (x - x); @}
+static inline int isinf_ld (long double x)
+@{ return !isnan (x) && isnan (x - x); @}
+#endif
+ at end smallexample
+
+Use @code{AC_C_INLINE} (@pxref{C Compiler}) so that this code works on
+compilers that lack the @code{inline} keyword. Some optimizing
+compilers mishandle these definitions, but systems with that bug
+typically have many other floating point corner-case compliance problems
+anyway, so it's probably not worth worrying about.
+
+ at item @code{malloc}
+ at c @fuindex malloc
+ at prindex @code{malloc}
+The C standard says a call @code{malloc (0)} is implementation
+dependent. It can return either @code{NULL} or a new non-null pointer.
+The latter is more common (e.g., the GNU C Library) but is by
+no means universal. @code{AC_FUNC_MALLOC}
+can be used to insist on non- at code{NULL} (@pxref{Particular Functions}).
+
+ at item @code{putenv}
+ at c @fuindex putenv
+ at prindex @code{putenv}
+Posix prefers @code{setenv} to @code{putenv}; among other things,
+ at code{putenv} is not required of all Posix implementations, but
+ at code{setenv} is.
+
+Posix specifies that @code{putenv} puts the given string directly in
+ at code{environ}, but some systems make a copy of it instead (e.g.,
+glibc 2.0, or BSD). And when a copy is made, @code{unsetenv} might
+not free it, causing a memory leak (e.g., FreeBSD 4).
+
+On some systems @code{putenv ("FOO")} removes @samp{FOO} from the
+environment, but this is not standard usage and it dumps core
+on some systems (e.g., AIX).
+
+On MinGW, a call @code{putenv ("FOO=")} removes @samp{FOO} from the
+environment, rather than inserting it with an empty value.
+
+ at item @code{realloc}
+ at c @fuindex realloc
+ at prindex @code{realloc}
+The C standard says a call @code{realloc (NULL, size)} is equivalent
+to @code{malloc (size)}, but some old systems don't support this (e.g.,
+NextStep).
+
+ at item @code{signal} handler
+ at c @fuindex signal
+ at prindex @code{signal}
+ at prindex @code{sigaction}
+Normally @code{signal} takes a handler function with a return type of
+ at code{void}, but some old systems required @code{int} instead. Any
+actual @code{int} value returned is not used; this is only a
+difference in the function prototype demanded.
+
+All systems we know of in current use return @code{void}. The
+ at code{int} was to support K&R C, where of course @code{void} is not
+available. The obsolete macro @code{AC_TYPE_SIGNAL}
+(@pxref{AC_TYPE_SIGNAL}) can be used to establish the correct type in
+all cases.
+
+In most cases, it is more robust to use @code{sigaction} when it is
+available, rather than @code{signal}.
+
+ at item @code{snprintf}
+ at c @fuindex snprintf
+ at prindex @code{snprintf}
+ at c @fuindex vsnprintf
+ at prindex @code{vsnprintf}
+The C99 standard says that if the output array isn't big enough
+and if no other errors occur, @code{snprintf} and @code{vsnprintf}
+truncate the output and return the number of bytes that ought to have
+been produced. Some older systems return the truncated length (e.g.,
+GNU C Library 2.0.x or IRIX 6.5), some a negative value
+(e.g., earlier GNU C Library versions), and some the buffer
+length without truncation (e.g., 32-bit Solaris 7). Also, some buggy
+older systems ignore the length and overrun the buffer (e.g., 64-bit
+Solaris 7).
+
+ at item @code{sprintf}
+ at c @fuindex sprintf
+ at prindex @code{sprintf}
+ at c @fuindex vsprintf
+ at prindex @code{vsprintf}
+The C standard says @code{sprintf} and @code{vsprintf} return the
+number of bytes written. On some ancient systems (SunOS 4 for
+instance) they return the buffer pointer instead, but these no
+longer need to be worried about.
+
+ at item @code{sscanf}
+ at c @fuindex sscanf
+ at prindex @code{sscanf}
+On various old systems, e.g., HP-UX 9, @code{sscanf} requires
+that its
+input string be writable (though it doesn't actually change it). This
+can be a problem when using @command{gcc} since it normally puts
+constant strings in read-only memory (@pxref{Incompatibilities,
+Incompatibilities of GCC, , gcc, Using and
+Porting the GNU Compiler Collection}). Apparently in some cases even
+having format strings read-only can be a problem.
+
+ at item @code{strerror_r}
+ at c @fuindex strerror_r
+ at prindex @code{strerror_r}
+Posix specifies that @code{strerror_r} returns an @code{int}, but many
+systems (e.g., GNU C Library version 2.2.4) provide a
+different version returning a @code{char *}. @code{AC_FUNC_STRERROR_R}
+can detect which is in use (@pxref{Particular Functions}).
+
+ at item @code{strnlen}
+ at c @fuindex strnlen
+ at prindex @code{strnlen}
+AIX 4.3 provides a broken version which produces the
+following results:
+
+ at example
+strnlen ("foobar", 0) = 0
+strnlen ("foobar", 1) = 3
+strnlen ("foobar", 2) = 2
+strnlen ("foobar", 3) = 1
+strnlen ("foobar", 4) = 0
+strnlen ("foobar", 5) = 6
+strnlen ("foobar", 6) = 6
+strnlen ("foobar", 7) = 6
+strnlen ("foobar", 8) = 6
+strnlen ("foobar", 9) = 6
+ at end example
+
+ at item @code{sysconf}
+ at c @fuindex sysconf
+ at prindex @code{sysconf}
+ at code{_SC_PAGESIZE} is standard, but some older systems (e.g., HP-UX
+9) have @code{_SC_PAGE_SIZE} instead. This can be tested with
+ at code{#ifdef}.
+
+ at item @code{unlink}
+ at c @fuindex unlink
+ at prindex @code{unlink}
+The Posix spec says that @code{unlink} causes the given file to be
+removed only after there are no more open file handles for it. Some
+non-Posix hosts have trouble with this requirement, though,
+and some DOS variants even corrupt the file system.
+
+ at item @code{unsetenv}
+ at c @fuindex unsetenv
+ at prindex @code{unsetenv}
+On MinGW, @code{unsetenv} is not available, but a variable @samp{FOO}
+can be removed with a call @code{putenv ("FOO=")}, as described under
+ at code{putenv} above.
+
+ at item @code{va_copy}
+ at c @fuindex va_copy
+ at prindex @code{va_copy}
+The C99 standard provides @code{va_copy} for copying
+ at code{va_list} variables. It may be available in older environments
+too, though possibly as @code{__va_copy} (e.g., @command{gcc} in strict
+pre-C99 mode). These can be tested with @code{#ifdef}. A fallback to
+ at code{memcpy (&dst, &src, sizeof (va_list))} gives maximum
+portability.
+
+ at item @code{va_list}
+ at c @fuindex va_list
+ at prindex @code{va_list}
+ at code{va_list} is not necessarily just a pointer. It can be a
+ at code{struct} (e.g., @command{gcc} on Alpha), which means @code{NULL} is
+not portable. Or it can be an array (e.g., @command{gcc} in some
+PowerPC configurations), which means as a function parameter it can be
+effectively call-by-reference and library routines might modify the
+value back in the caller (e.g., @code{vsnprintf} in the GNU C Library
+2.1).
+
+ at item Signed @code{>>}
+Normally the C @code{>>} right shift of a signed type replicates the
+high bit, giving a so-called ``arithmetic'' shift. But care should be
+taken since Standard C doesn't require that behavior. On those
+few processors without a native arithmetic shift (for instance Cray
+vector systems) zero bits may be shifted in, the same as a shift of an
+unsigned type.
+
+ at item Integer @code{/}
+C divides signed integers by truncating their quotient toward zero,
+yielding the same result as Fortran. However, before C99 the standard
+allowed C implementations to take the floor or ceiling of the quotient
+in some cases. Hardly any implementations took advantage of this
+freedom, though, and it's probably not worth worrying about this issue
+nowadays.
+ at end table
+
+
+ at node Particular Functions
+ at subsection Particular Function Checks
+ at cindex Function, checking
+
+These macros check for particular C functions---whether they exist, and
+in some cases how they respond when given certain arguments.
+
+ at anchor{AC_FUNC_ALLOCA}
+ at defmac AC_FUNC_ALLOCA
+ at acindex{FUNC_ALLOCA}
+ at cvindex C_ALLOCA
+ at cvindex HAVE_ALLOCA_H
+ at ovindex ALLOCA
+ at c @fuindex alloca
+ at prindex @code{alloca}
+ at hdrindex{alloca.h}
+ at c @caindex working_alloca_h
+Check how to get @code{alloca}. Tries to get a builtin version by
+checking for @file{alloca.h} or the predefined C preprocessor macros
+ at code{__GNUC__} and @code{_AIX}. If this macro finds @file{alloca.h},
+it defines @code{HAVE_ALLOCA_H}.
+
+If those attempts fail, it looks for the function in the standard C
+library. If any of those methods succeed, it defines
+ at code{HAVE_ALLOCA}. Otherwise, it sets the output variable
+ at code{ALLOCA} to @samp{$@{LIBOBJDIR@}alloca.o} and defines
+ at code{C_ALLOCA} (so programs can periodically call @samp{alloca (0)} to
+garbage collect). This variable is separate from @code{LIBOBJS} so
+multiple programs can share the value of @code{ALLOCA} without needing
+to create an actual library, in case only some of them use the code in
+ at code{LIBOBJS}. The @samp{$@{LIBOBJDIR@}} prefix serves the same
+purpose as in @code{LIBOBJS} (@pxref{AC_LIBOBJ vs LIBOBJS}).
+
+This macro does not try to get @code{alloca} from the System V R3
+ at file{libPW} or the System V R4 @file{libucb} because those libraries
+contain some incompatible functions that cause trouble. Some versions
+do not even contain @code{alloca} or contain a buggy version. If you
+still want to use their @code{alloca}, use @code{ar} to extract
+ at file{alloca.o} from them instead of compiling @file{alloca.c}.
+
+Source files that use @code{alloca} should start with a piece of code
+like the following, to declare it properly.
+
+ at example
+ at group
+#ifdef STDC_HEADERS
+# include <stdlib.h>
+# include <stddef.h>
+#else
+# ifdef HAVE_STDLIB_H
+# include <stdlib.h>
+# endif
+#endif
+#ifdef HAVE_ALLOCA_H
+# include <alloca.h>
+#elif !defined alloca
+# ifdef __GNUC__
+# define alloca __builtin_alloca
+# elif defined _AIX
+# define alloca __alloca
+# elif defined _MSC_VER
+# include <malloc.h>
+# define alloca _alloca
+# elif !defined HAVE_ALLOCA
+# ifdef __cplusplus
+extern "C"
+# endif
+void *alloca (size_t);
+# endif
+#endif
+ at end group
+ at end example
+ at end defmac
+
+ at defmac AC_FUNC_CHOWN
+ at acindex{FUNC_CHOWN}
+ at cvindex HAVE_CHOWN
+ at c @fuindex chown
+ at prindex @code{chown}
+ at caindex func_chown_works
+If the @code{chown} function is available and works (in particular, it
+should accept @option{-1} for @code{uid} and @code{gid}), define
+ at code{HAVE_CHOWN}. The result of this macro is cached in the
+ at code{ac_cv_func_chown_works} variable.
+ at end defmac
+
+ at anchor{AC_FUNC_CLOSEDIR_VOID}
+ at defmac AC_FUNC_CLOSEDIR_VOID
+ at acindex{FUNC_CLOSEDIR_VOID}
+ at cvindex CLOSEDIR_VOID
+ at c @fuindex closedir
+ at prindex @code{closedir}
+ at caindex func_closedir_void
+If the @code{closedir} function does not return a meaningful value,
+define @code{CLOSEDIR_VOID}. Otherwise, callers ought to check its
+return value for an error indicator.
+
+Currently this test is implemented by running a test program. When
+cross compiling the pessimistic assumption that @code{closedir} does not
+return a meaningful value is made.
+
+The result of this macro is cached in the @code{ac_cv_func_closedir_void}
+variable.
+
+This macro is obsolescent, as @code{closedir} returns a meaningful value
+on current systems. New programs need not use this macro.
+ at end defmac
+
+ at defmac AC_FUNC_ERROR_AT_LINE
+ at acindex{FUNC_ERROR_AT_LINE}
+ at c @fuindex error_at_line
+ at prindex @code{error_at_line}
+ at caindex lib_error_at_line
+If the @code{error_at_line} function is not found, require an
+ at code{AC_LIBOBJ} replacement of @samp{error}.
+
+The result of this macro is cached in the @code{ac_cv_lib_error_at_line}
+variable.
+
+The @code{AC_FUNC_ERROR_AT_LINE} macro is obsolescent. New programs
+should use Gnulib's @code{error} module. @xref{Gnulib}.
+ at end defmac
+
+ at defmac AC_FUNC_FNMATCH
+ at acindex{FUNC_FNMATCH}
+ at c @fuindex fnmatch
+ at prindex @code{fnmatch}
+ at caindex func_fnmatch_works
+If the @code{fnmatch} function conforms to Posix, define
+ at code{HAVE_FNMATCH}. Detect common implementation bugs, for example,
+the bugs in Solaris 2.4.
+
+Unlike the other specific
+ at code{AC_FUNC} macros, @code{AC_FUNC_FNMATCH} does not replace a
+broken/missing @code{fnmatch}. This is for historical reasons.
+See @code{AC_REPLACE_FNMATCH} below.
+
+The result of this macro is cached in the @code{ac_cv_func_fnmatch_works}
+variable.
+
+This macro is obsolescent. New programs should use Gnulib's
+ at code{fnmatch-posix} module. @xref{Gnulib}.
+ at end defmac
+
+ at defmac AC_FUNC_FNMATCH_GNU
+ at acindex{FUNC_FNMATCH_GNU}
+ at c @fuindex fnmatch
+ at prindex @code{fnmatch}
+ at caindex func_fnmatch_gnu
+Behave like @code{AC_REPLACE_FNMATCH} (@emph{replace}) but also test
+whether @code{fnmatch} supports GNU extensions. Detect common
+implementation bugs, for example, the bugs in the GNU C
+Library 2.1.
+
+The result of this macro is cached in the @code{ac_cv_func_fnmatch_gnu}
+variable.
+
+This macro is obsolescent. New programs should use Gnulib's
+ at code{fnmatch-gnu} module. @xref{Gnulib}.
+ at end defmac
+
+ at anchor{AC_FUNC_FORK}
+ at defmac AC_FUNC_FORK
+ at acindex{FUNC_FORK}
+ at cvindex HAVE_VFORK_H
+ at cvindex HAVE_WORKING_FORK
+ at cvindex HAVE_WORKING_VFORK
+ at cvindex vfork
+ at c @fuindex fork
+ at prindex @code{fork}
+ at c @fuindex vfork
+ at prindex @code{vfork}
+ at hdrindex{vfork.h}
+ at c @caindex func_fork
+ at c @caindex func_fork_works
+This macro checks for the @code{fork} and @code{vfork} functions. If a
+working @code{fork} is found, define @code{HAVE_WORKING_FORK}. This macro
+checks whether @code{fork} is just a stub by trying to run it.
+
+If @file{vfork.h} is found, define @code{HAVE_VFORK_H}. If a working
+ at code{vfork} is found, define @code{HAVE_WORKING_VFORK}. Otherwise,
+define @code{vfork} to be @code{fork} for backward compatibility with
+previous versions of @command{autoconf}. This macro checks for several known
+errors in implementations of @code{vfork} and considers the system to not
+have a working @code{vfork} if it detects any of them. It is not considered
+to be an implementation error if a child's invocation of @code{signal}
+modifies the parent's signal handler, since child processes rarely change
+their signal handlers.
+
+Since this macro defines @code{vfork} only for backward compatibility with
+previous versions of @command{autoconf} you're encouraged to define it
+yourself in new code:
+ at example
+ at group
+#ifndef HAVE_WORKING_VFORK
+# define vfork fork
+#endif
+ at end group
+ at end example
+
+The results of this macro are cached in the @code{ac_cv_func_fork_works}
+and @code{ac_cv_func_vfork_works} variables. In order to override the
+test, you also need to set the @code{ac_cv_func_fork} and
+ at code{ac_cv_func_vfork} variables.
+ at end defmac
+
+ at defmac AC_FUNC_FSEEKO
+ at acindex{FUNC_FSEEKO}
+ at cvindex _LARGEFILE_SOURCE
+ at cvindex HAVE_FSEEKO
+ at c @fuindex fseeko
+ at prindex @code{fseeko}
+ at c @fuindex ftello
+ at prindex @code{ftello}
+ at c @caindex sys_largefile_source
+If the @code{fseeko} function is available, define @code{HAVE_FSEEKO}.
+Define @code{_LARGEFILE_SOURCE} if necessary to make the prototype
+visible on some systems (e.g., glibc 2.2). Otherwise linkage problems
+may occur when compiling with @code{AC_SYS_LARGEFILE} on
+largefile-sensitive systems where @code{off_t} does not default to a
+64bit entity. All systems with @code{fseeko} also supply @code{ftello}.
+ at end defmac
+
+ at defmac AC_FUNC_GETGROUPS
+ at acindex{FUNC_GETGROUPS}
+ at cvindex HAVE_GETGROUPS
+ at ovindex GETGROUPS_LIBS
+ at c @fuindex getgroups
+ at prindex @code{getgroups}
+ at caindex func_getgroups_works
+If the @code{getgroups} function is available and works (unlike on
+Ultrix 4.3, where @samp{getgroups (0, 0)} always fails), define
+ at code{HAVE_GETGROUPS}. Set @code{GETGROUPS_LIBS} to any libraries
+needed to get that function. This macro runs @code{AC_TYPE_GETGROUPS}.
+ at end defmac
+
+ at anchor{AC_FUNC_GETLOADAVG}
+ at defmac AC_FUNC_GETLOADAVG
+ at acindex{FUNC_GETLOADAVG}
+ at cvindex SVR4
+ at cvindex DGUX
+ at cvindex UMAX
+ at cvindex UMAX4_3
+ at cvindex HAVE_NLIST_H
+ at cvindex NLIST_NAME_UNION
+ at cvindex GETLOADAVG_PRIVILEGED
+ at cvindex NEED_SETGID
+ at cvindex C_GETLOADAVG
+ at ovindex LIBOBJS
+ at ovindex NEED_SETGID
+ at ovindex KMEM_GROUP
+ at ovindex GETLOADAVG_LIBS
+ at c @fuindex getloadavg
+ at prindex @code{getloadavg}
+Check how to get the system load averages. To perform its tests
+properly, this macro needs the file @file{getloadavg.c}; therefore, be
+sure to set the @code{AC_LIBOBJ} replacement directory properly (see
+ at ref{Generic Functions}, @code{AC_CONFIG_LIBOBJ_DIR}).
+
+If the system has the @code{getloadavg} function, define
+ at code{HAVE_GETLOADAVG}, and set @code{GETLOADAVG_LIBS} to any libraries
+necessary to get that function. Also add @code{GETLOADAVG_LIBS} to
+ at code{LIBS}. Otherwise, require an @code{AC_LIBOBJ} replacement for
+ at samp{getloadavg} with source code in @file{@var{dir}/getloadavg.c}, and
+possibly define several other C preprocessor macros and output
+variables:
+
+ at enumerate
+ at item
+Define @code{C_GETLOADAVG}.
+
+ at item
+Define @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if on
+those systems.
+
+ at item
+ at hdrindex{nlist.h}
+If @file{nlist.h} is found, define @code{HAVE_NLIST_H}.
+
+ at item
+If @samp{struct nlist} has an @samp{n_un.n_name} member, define
+ at code{HAVE_STRUCT_NLIST_N_UN_N_NAME}. The obsolete symbol
+ at code{NLIST_NAME_UNION} is still defined, but do not depend upon it.
+
+ at item
+Programs may need to be installed set-group-ID (or set-user-ID) for
+ at code{getloadavg} to work. In this case, define
+ at code{GETLOADAVG_PRIVILEGED}, set the output variable @code{NEED_SETGID}
+to @samp{true} (and otherwise to @samp{false}), and set
+ at code{KMEM_GROUP} to the name of the group that should own the installed
+program.
+ at end enumerate
+
+The @code{AC_FUNC_GETLOADAVG} macro is obsolescent. New programs should
+use Gnulib's @code{getloadavg} module. @xref{Gnulib}.
+ at end defmac
+
+ at anchor{AC_FUNC_GETMNTENT}
+ at defmac AC_FUNC_GETMNTENT
+ at acindex{FUNC_GETMNTENT}
+ at cvindex HAVE_GETMNTENT
+ at c @fuindex getmntent
+ at prindex @code{getmntent}
+ at caindex search_getmntent
+Check for @code{getmntent} in the standard C library, and then in the
+ at file{sun}, @file{seq}, and @file{gen} libraries, for UNICOS,
+IRIX 4, PTX, and UnixWare, respectively. Then, if
+ at code{getmntent} is available, define @code{HAVE_GETMNTENT} and set
+ at code{ac_cv_func_getmntent} to @code{yes}. Otherwise set
+ at code{ac_cv_func_getmntent} to @code{no}.
+
+The result of this macro can be overridden by setting the cache variable
+ at code{ac_cv_search_getmntent}.
+ at end defmac
+
+ at defmac AC_FUNC_GETPGRP
+ at acindex{FUNC_GETPGRP}
+ at cvindex GETPGRP_VOID
+ at c @fuindex getpgid
+ at c @fuindex getpgrp
+ at prindex @code{getpgid}
+ at prindex @code{getpgrp}
+ at caindex func_getpgrp_void
+Define @code{GETPGRP_VOID} if it is an error to pass 0 to
+ at code{getpgrp}; this is the Posix behavior. On older BSD
+systems, you must pass 0 to @code{getpgrp}, as it takes an argument and
+behaves like Posix's @code{getpgid}.
+
+ at example
+#ifdef GETPGRP_VOID
+ pid = getpgrp ();
+#else
+ pid = getpgrp (0);
+#endif
+ at end example
+
+This macro does not check whether
+ at code{getpgrp} exists at all; if you need to work in that situation,
+first call @code{AC_CHECK_FUNC} for @code{getpgrp}.
+
+The result of this macro is cached in the @code{ac_cv_func_getpgrp_void}
+variable.
+
+This macro is obsolescent, as current systems have a @code{getpgrp}
+whose signature conforms to Posix. New programs need not use this macro.
+ at end defmac
+
+ at defmac AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK
+ at acindex{FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK}
+ at cvindex LSTAT_FOLLOWS_SLASHED_SYMLINK
+ at c @fuindex lstat
+ at prindex @code{lstat}
+ at caindex func_lstat_dereferences_slashed_symlink
+If @file{link} is a symbolic link, then @code{lstat} should treat
+ at file{link/} the same as @file{link/.}. However, many older
+ at code{lstat} implementations incorrectly ignore trailing slashes.
+
+It is safe to assume that if @code{lstat} incorrectly ignores
+trailing slashes, then other symbolic-link-aware functions like
+ at code{unlink} also incorrectly ignore trailing slashes.
+
+If @code{lstat} behaves properly, define
+ at code{LSTAT_FOLLOWS_SLASHED_SYMLINK}, otherwise require an
+ at code{AC_LIBOBJ} replacement of @code{lstat}.
+
+The result of this macro is cached in the
+ at code{ac_cv_func_lstat_dereferences_slashed_symlink} variable.
+
+The @code{AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK} macro is obsolescent.
+New programs should use Gnulib's @code{lstat} module. @xref{Gnulib}.
+ at end defmac
+
+ at defmac AC_FUNC_MALLOC
+ at acindex{FUNC_MALLOC}
+ at cvindex HAVE_MALLOC
+ at cvindex malloc
+ at c @fuindex malloc
+ at prindex @code{malloc}
+ at caindex func_malloc_0_nonnull
+If the @code{malloc} function is compatible with the GNU C
+library @code{malloc} (i.e., @samp{malloc (0)} returns a valid
+pointer), define @code{HAVE_MALLOC} to 1. Otherwise define
+ at code{HAVE_MALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
+ at samp{malloc}, and define @code{malloc} to @code{rpl_malloc} so that the
+native @code{malloc} is not used in the main project.
+
+Typically, the replacement file @file{malloc.c} should look like (note
+the @samp{#undef malloc}):
+
+ at verbatim
+#include <config.h>
+#undef malloc
+
+#include <sys/types.h>
+
+void *malloc ();
+
+/* Allocate an N-byte block of memory from the heap.
+ If N is zero, allocate a 1-byte block. */
+
+void *
+rpl_malloc (size_t n)
+{
+ if (n == 0)
+ n = 1;
+ return malloc (n);
+}
+ at end verbatim
+
+The result of this macro is cached in the
+ at code{ac_cv_func_malloc_0_nonnull} variable.
+ at end defmac
+
+ at defmac AC_FUNC_MBRTOWC
+ at acindex{FUNC_MBRTOWC}
+ at cvindex HAVE_MBRTOWC
+ at c @fuindex mbrtowc
+ at prindex @code{mbrtowc}
+ at caindex func_mbrtowc
+Define @code{HAVE_MBRTOWC} to 1 if the function @code{mbrtowc} and the
+type @code{mbstate_t} are properly declared.
+
+The result of this macro is cached in the @code{ac_cv_func_mbrtowc}
+variable.
+ at end defmac
+
+ at defmac AC_FUNC_MEMCMP
+ at acindex{FUNC_MEMCMP}
+ at ovindex LIBOBJS
+ at c @fuindex memcmp
+ at prindex @code{memcmp}
+ at caindex func_memcmp_working
+If the @code{memcmp} function is not available, or does not work on
+8-bit data (like the one on SunOS 4.1.3), or fails when comparing 16
+bytes or more and with at least one buffer not starting on a 4-byte
+boundary (such as the one on NeXT x86 OpenStep), require an
+ at code{AC_LIBOBJ} replacement for @samp{memcmp}.
+
+The result of this macro is cached in the
+ at code{ac_cv_func_memcmp_working} variable.
+
+This macro is obsolescent, as current systems have a working
+ at code{memcmp}. New programs need not use this macro.
+ at end defmac
+
+ at defmac AC_FUNC_MKTIME
+ at acindex{FUNC_MKTIME}
+ at ovindex LIBOBJS
+ at c @fuindex mktime
+ at prindex @code{mktime}
+ at caindex func_working_mktime
+If the @code{mktime} function is not available, or does not work
+correctly, require an @code{AC_LIBOBJ} replacement for @samp{mktime}.
+For the purposes of this test, @code{mktime} should conform to the
+Posix standard and should be the inverse of
+ at code{localtime}.
+
+The result of this macro is cached in the
+ at code{ac_cv_func_working_mktime} variable.
+
+The @code{AC_FUNC_MKTIME} macro is obsolescent. New programs should
+use Gnulib's @code{mktime} module. @xref{Gnulib}.
+ at end defmac
+
+ at anchor{AC_FUNC_MMAP}
+ at defmac AC_FUNC_MMAP
+ at acindex{FUNC_MMAP}
+ at cvindex HAVE_MMAP
+ at c @fuindex mmap
+ at prindex @code{mmap}
+ at caindex func_mmap_fixed_mapped
+If the @code{mmap} function exists and works correctly, define
+ at code{HAVE_MMAP}. This checks only private fixed mapping of already-mapped
+memory.
+
+The result of this macro is cached in the
+ at code{ac_cv_func_mmap_fixed_mapped} variable.
+ at end defmac
+
+ at defmac AC_FUNC_OBSTACK
+ at acindex{FUNC_OBSTACK}
+ at cvindex HAVE_OBSTACK
+ at cindex obstack
+ at caindex func_obstack
+If the obstacks are found, define @code{HAVE_OBSTACK}, else require an
+ at code{AC_LIBOBJ} replacement for @samp{obstack}.
+
+The result of this macro is cached in the @code{ac_cv_func_obstack}
+variable.
+ at end defmac
+
+ at defmac AC_FUNC_REALLOC
+ at acindex{FUNC_REALLOC}
+ at cvindex HAVE_REALLOC
+ at cvindex realloc
+ at c @fuindex realloc
+ at prindex @code{realloc}
+ at caindex func_realloc_0_nonnull
+If the @code{realloc} function is compatible with the GNU C
+library @code{realloc} (i.e., @samp{realloc (NULL, 0)} returns a
+valid pointer), define @code{HAVE_REALLOC} to 1. Otherwise define
+ at code{HAVE_REALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
+ at samp{realloc}, and define @code{realloc} to @code{rpl_realloc} so that
+the native @code{realloc} is not used in the main project. See
+ at code{AC_FUNC_MALLOC} for details.
+
+The result of this macro is cached in the
+ at code{ac_cv_func_realloc_0_nonnull} variable.
+ at end defmac
+
+ at defmac AC_FUNC_SELECT_ARGTYPES
+ at acindex{FUNC_SELECT_ARGTYPES}
+ at cvindex SELECT_TYPE_ARG1
+ at cvindex SELECT_TYPE_ARG234
+ at cvindex SELECT_TYPE_ARG5
+ at c @fuindex select
+ at prindex @code{select}
+ at c @caindex func_select_args
+Determines the correct type to be passed for each of the
+ at code{select} function's arguments, and defines those types
+in @code{SELECT_TYPE_ARG1}, @code{SELECT_TYPE_ARG234}, and
+ at code{SELECT_TYPE_ARG5} respectively. @code{SELECT_TYPE_ARG1} defaults
+to @samp{int}, @code{SELECT_TYPE_ARG234} defaults to @samp{int *},
+and @code{SELECT_TYPE_ARG5} defaults to @samp{struct timeval *}.
+
+This macro is obsolescent, as current systems have a @code{select} whose
+signature conforms to Posix. New programs need not use this macro.
+ at end defmac
+
+ at defmac AC_FUNC_SETPGRP
+ at acindex{FUNC_SETPGRP}
+ at cvindex SETPGRP_VOID
+ at c @fuindex setpgrp
+ at prindex @code{setpgrp}
+ at caindex func_setpgrp_void
+If @code{setpgrp} takes no argument (the Posix version), define
+ at code{SETPGRP_VOID}. Otherwise, it is the BSD version, which takes
+two process IDs as arguments. This macro does not check whether
+ at code{setpgrp} exists at all; if you need to work in that situation,
+first call @code{AC_CHECK_FUNC} for @code{setpgrp}.
+
+The result of this macro is cached in the @code{ac_cv_func_setpgrp_void}
+variable.
+
+This macro is obsolescent, as current systems have a @code{setpgrp}
+whose signature conforms to Posix. New programs need not use this macro.
+ at end defmac
+
+ at defmac AC_FUNC_STAT
+ at defmacx AC_FUNC_LSTAT
+ at acindex{FUNC_STAT}
+ at acindex{FUNC_LSTAT}
+ at cvindex HAVE_STAT_EMPTY_STRING_BUG
+ at cvindex HAVE_LSTAT_EMPTY_STRING_BUG
+ at c @fuindex stat
+ at prindex @code{stat}
+ at c @fuindex lstat
+ at prindex @code{lstat}
+ at caindex func_stat_empty_string_bug
+ at caindex func_lstat_empty_string_bug
+Determine whether @code{stat} or @code{lstat} have the bug that it
+succeeds when given the zero-length file name as argument. The @code{stat}
+and @code{lstat} from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do
+this.
+
+If it does, then define @code{HAVE_STAT_EMPTY_STRING_BUG} (or
+ at code{HAVE_LSTAT_EMPTY_STRING_BUG}) and ask for an @code{AC_LIBOBJ}
+replacement of it.
+
+The results of these macros are cached in the
+ at code{ac_cv_func_stat_empty_string_bug} and the
+ at code{ac_cv_func_lstat_empty_string_bug} variables, respectively.
+
+These macros are obsolescent, as no current systems have the bug.
+New programs need not use these macros.
+ at end defmac
+
+ at anchor{AC_FUNC_STRCOLL}
+ at defmac AC_FUNC_STRCOLL
+ at acindex{FUNC_STRCOLL}
+ at cvindex HAVE_STRCOLL
+ at c @fuindex strcoll
+ at prindex @code{strcoll}
+ at caindex func_strcoll_works
+If the @code{strcoll} function exists and works correctly, define
+ at code{HAVE_STRCOLL}. This does a bit more than
+ at samp{AC_CHECK_FUNCS(strcoll)}, because some systems have incorrect
+definitions of @code{strcoll} that should not be used.
+
+The result of this macro is cached in the @code{ac_cv_func_strcoll_works}
+variable.
+ at end defmac
+
+ at defmac AC_FUNC_STRERROR_R
+ at acindex{FUNC_STRERROR_R}
+ at cvindex HAVE_STRERROR_R
+ at cvindex HAVE_DECL_STRERROR_R
+ at cvindex STRERROR_R_CHAR_P
+ at c @fuindex strerror_r
+ at caindex func_strerror_r_char_p
+ at prindex @code{strerror_r}
+If @code{strerror_r} is available, define @code{HAVE_STRERROR_R}, and if
+it is declared, define @code{HAVE_DECL_STRERROR_R}. If it returns a
+ at code{char *} message, define @code{STRERROR_R_CHAR_P}; otherwise it
+returns an @code{int} error number. The Thread-Safe Functions option of
+Posix requires @code{strerror_r} to return @code{int}, but
+many systems (including, for example, version 2.2.4 of the GNU C
+Library) return a @code{char *} value that is not necessarily equal to
+the buffer argument.
+
+The result of this macro is cached in the
+ at code{ac_cv_func_strerror_r_char_p} variable.
+ at end defmac
+
+ at anchor{AC_FUNC_STRFTIME}
+ at defmac AC_FUNC_STRFTIME
+ at acindex{FUNC_STRFTIME}
+ at cvindex HAVE_STRFTIME
+ at c @fuindex strftime
+ at prindex @code{strftime}
+Check for @code{strftime} in the @file{intl} library, for SCO Unix.
+Then, if @code{strftime} is available, define @code{HAVE_STRFTIME}.
+
+This macro is obsolescent, as no current systems require the @file{intl}
+library for @code{strftime}. New programs need not use this macro.
+ at end defmac
+
+ at defmac AC_FUNC_STRTOD
+ at acindex{FUNC_STRTOD}
+ at ovindex POW_LIB
+ at c @fuindex strtod
+ at prindex @code{strtod}
+ at caindex func_strtod
+ at caindex func_pow
+If the @code{strtod} function does not exist or doesn't work correctly,
+ask for an @code{AC_LIBOBJ} replacement of @samp{strtod}. In this case,
+because @file{strtod.c} is likely to need @samp{pow}, set the output
+variable @code{POW_LIB} to the extra library needed.
+
+This macro caches its result in the @code{ac_cv_func_strtod} variable
+and depends upon the result in the @code{ac_cv_func_pow} variable.
+
+The @code{AC_FUNC_STRTOD} macro is obsolescent. New programs should
+use Gnulib's @code{strtod} module. @xref{Gnulib}.
+ at end defmac
+
+ at defmac AC_FUNC_STRTOLD
+ at acindex{FUNC_STRTOLD}
+ at cvindex HAVE_STRTOLD
+ at prindex @code{strtold}
+ at caindex func_strtold
+If the @code{strtold} function exists and conforms to C99, define
+ at code{HAVE_STRTOLD}.
+
+This macro caches its result in the @code{ac_cv_func_strtold} variable.
+ at end defmac
+
+ at defmac AC_FUNC_STRNLEN
+ at acindex{FUNC_STRNLEN}
+ at cvindex HAVE_STRNLEN
+ at c @fuindex strnlen
+ at prindex @code{strnlen}
+ at caindex func_strnlen_working
+If the @code{strnlen} function is not available, or is buggy (like the one
+from AIX 4.3), require an @code{AC_LIBOBJ} replacement for it.
+
+This macro caches its result in the @code{ac_cv_func_strnlen_working}
+variable.
+ at end defmac
+
+ at anchor{AC_FUNC_UTIME_NULL}
+ at defmac AC_FUNC_UTIME_NULL
+ at acindex{FUNC_UTIME_NULL}
+ at cvindex HAVE_UTIME_NULL
+ at c @fuindex utime
+ at prindex @code{utime}
+ at caindex func_utime_null
+If @samp{utime (@var{file}, NULL)} sets @var{file}'s timestamp to
+the present, define @code{HAVE_UTIME_NULL}.
+
+This macro caches its result in the @code{ac_cv_func_utime_null}
+variable.
+
+This macro is obsolescent, as all current systems have a @code{utime}
+that behaves this way. New programs need not use this macro.
+ at end defmac
+
+ at anchor{AC_FUNC_VPRINTF}
+ at defmac AC_FUNC_VPRINTF
+ at acindex{FUNC_VPRINTF}
+ at cvindex HAVE_VPRINTF
+ at cvindex HAVE_DOPRNT
+ at c @fuindex vprintf
+ at prindex @code{vprintf}
+ at c @fuindex vsprintf
+ at prindex @code{vsprintf}
+If @code{vprintf} is found, define @code{HAVE_VPRINTF}. Otherwise, if
+ at code{_doprnt} is found, define @code{HAVE_DOPRNT}. (If @code{vprintf}
+is available, you may assume that @code{vfprintf} and @code{vsprintf}
+are also available.)
+
+This macro is obsolescent, as all current systems have @code{vprintf}.
+New programs need not use this macro.
+ at end defmac
+
+ at defmac AC_REPLACE_FNMATCH
+ at acindex{REPLACE_FNMATCH}
+ at c @fuindex fnmatch
+ at prindex @code{fnmatch}
+ at hdrindex{fnmatch.h}
+ at caindex func_fnmatch_works
+If the @code{fnmatch} function does not conform to Posix (see
+ at code{AC_FUNC_FNMATCH}), ask for its @code{AC_LIBOBJ} replacement.
+
+The files @file{fnmatch.c}, @file{fnmatch_loop.c}, and @file{fnmatch_.h}
+in the @code{AC_LIBOBJ} replacement directory are assumed to contain a
+copy of the source code of GNU @code{fnmatch}. If necessary,
+this source code is compiled as an @code{AC_LIBOBJ} replacement, and the
+ at file{fnmatch_.h} file is linked to @file{fnmatch.h} so that it can be
+included in place of the system @code{<fnmatch.h>}.
+
+This macro caches its result in the @code{ac_cv_func_fnmatch_works}
+variable.
+
+This macro is obsolescent, as it assumes the use of particular source
+files. New programs should use Gnulib's @code{fnmatch-posix} module,
+which provides this macro along with the source files. @xref{Gnulib}.
+ at end defmac
+
+
+
+ at node Generic Functions
+ at subsection Generic Function Checks
+
+These macros are used to find functions not covered by the ``particular''
+test macros. If the functions might be in libraries other than the
+default C library, first call @code{AC_CHECK_LIB} for those libraries.
+If you need to check the behavior of a function as well as find out
+whether it is present, you have to write your own test for
+it (@pxref{Writing Tests}).
+
+ at anchor{AC_CHECK_FUNC}
+ at defmac AC_CHECK_FUNC (@var{function}, @ovar{action-if-found}, @
+ @ovar{action-if-not-found})
+ at acindex{CHECK_FUNC}
+ at caindex func_ at var{function}
+If C function @var{function} is available, run shell commands
+ at var{action-if-found}, otherwise @var{action-if-not-found}. If you just
+want to define a symbol if the function is available, consider using
+ at code{AC_CHECK_FUNCS} instead. This macro checks for functions with C
+linkage even when @code{AC_LANG(C++)} has been called, since C is more
+standardized than C++. (@pxref{Language Choice}, for more information
+about selecting the language for checks.)
+
+This macro caches its result in the @code{ac_cv_func_ at var{function}}
+variable.
+ at end defmac
+
+ at anchor{AC_CHECK_FUNCS}
+ at defmac AC_CHECK_FUNCS (@var{function}@dots{}, @ovar{action-if-found}, @
+ @ovar{action-if-not-found})
+ at acindex{CHECK_FUNCS}
+ at cvindex HAVE_ at var{function}
+For each @var{function} enumerated in the blank-or-newline-separated argument
+list, define @code{HAVE_ at var{function}} (in all capitals) if it is available.
+If @var{action-if-found} is given, it is additional shell code to
+execute when one of the functions is found. You can give it a value of
+ at samp{break} to break out of the loop on the first match. If
+ at var{action-if-not-found} is given, it is executed when one of the
+functions is not found.
+
+Results are cached for each @var{function} as in @code{AC_CHECK_FUNC}.
+ at end defmac
+
+ at defmac AC_CHECK_FUNCS_ONCE (@var{function}@dots{})
+ at acindex{CHECK_FUNCS_ONCE}
+ at cvindex HAVE_ at var{function}
+For each @var{function} enumerated in the blank-or-newline-separated argument
+list, define @code{HAVE_ at var{function}} (in all capitals) if it is available.
+This is a once-only variant of @code{AC_CHECK_FUNCS}. It generates the
+checking code at most once, so that @command{configure} is smaller and
+faster; but the checks cannot be conditionalized and are always done once,
+early during the @command{configure} run.
+ at end defmac
+
+ at sp 1
+
+Autoconf follows a philosophy that was formed over the years by those
+who have struggled for portability: isolate the portability issues in
+specific files, and then program as if you were in a Posix
+environment. Some functions may be missing or unfixable, and your
+package must be ready to replace them.
+
+Suitable replacements for many such problem functions are available from
+Gnulib (@pxref{Gnulib}).
+
+ at defmac AC_LIBOBJ (@var{function})
+ at acindex{LIBOBJ}
+ at ovindex LIBOBJS
+Specify that @samp{@var{function}.c} must be included in the executables
+to replace a missing or broken implementation of @var{function}.
+
+ at vrindex ac_objext
+Technically, it adds @samp{@var{function}.$ac_objext} to the output
+variable @code{LIBOBJS} if it is not already in, and calls
+ at code{AC_LIBSOURCE} for @samp{@var{function}.c}. You should not
+directly change @code{LIBOBJS}, since this is not traceable.
+ at end defmac
+
+ at defmac AC_LIBSOURCE (@var{file})
+ at acindex{LIBSOURCE}
+Specify that @var{file} might be needed to compile the project. If you
+need to know what files might be needed by a @file{configure.ac}, you
+should trace @code{AC_LIBSOURCE}. @var{file} must be a literal.
+
+This macro is called automatically from @code{AC_LIBOBJ}, but you must
+call it explicitly if you pass a shell variable to @code{AC_LIBOBJ}. In
+that case, since shell variables cannot be traced statically, you must
+pass to @code{AC_LIBSOURCE} any possible files that the shell variable
+might cause @code{AC_LIBOBJ} to need. For example, if you want to pass
+a variable @code{$foo_or_bar} to @code{AC_LIBOBJ} that holds either
+ at code{"foo"} or @code{"bar"}, you should do:
+
+ at example
+AC_LIBSOURCE([foo.c])
+AC_LIBSOURCE([bar.c])
+AC_LIBOBJ([$foo_or_bar])
+ at end example
+
+ at noindent
+There is usually a way to avoid this, however, and you are encouraged to
+simply call @code{AC_LIBOBJ} with literal arguments.
+
+Note that this macro replaces the obsolete @code{AC_LIBOBJ_DECL}, with
+slightly different semantics: the old macro took the function name,
+e.g., @code{foo}, as its argument rather than the file name.
+ at end defmac
+
+ at defmac AC_LIBSOURCES (@var{files})
+ at acindex{LIBSOURCES}
+Like @code{AC_LIBSOURCE}, but accepts one or more @var{files} in a
+comma-separated M4 list. Thus, the above example might be rewritten:
+
+ at example
+AC_LIBSOURCES([foo.c, bar.c])
+AC_LIBOBJ([$foo_or_bar])
+ at end example
+ at end defmac
+
+ at defmac AC_CONFIG_LIBOBJ_DIR (@var{directory})
+ at acindex{CONFIG_LIBOBJ_DIR}
+Specify that @code{AC_LIBOBJ} replacement files are to be found in
+ at var{directory}, a name relative to the top level of the
+source tree. The replacement directory defaults to @file{.}, the top
+level directory, and the most typical value is @file{lib}, corresponding
+to @samp{AC_CONFIG_LIBOBJ_DIR([lib])}.
+
+ at command{configure} might need to know the replacement directory for the
+following reasons: (i) some checks use the replacement files, (ii) some
+macros bypass broken system headers by installing links to the
+replacement headers (iii) when used in conjunction with Automake,
+within each makefile, @var{directory} is used as a relative path
+from @code{$(top_srcdir)} to each object named in @code{LIBOBJS} and
+ at code{LTLIBOBJS}, etc.
+ at end defmac
+
+ at sp 1
+
+It is common to merely check for the existence of a function, and ask
+for its @code{AC_LIBOBJ} replacement if missing. The following macro is
+a convenient shorthand.
+
+ at defmac AC_REPLACE_FUNCS (@var{function}@dots{})
+ at acindex{REPLACE_FUNCS}
+ at cvindex HAVE_ at var{function}
+ at ovindex LIBOBJS
+Like @code{AC_CHECK_FUNCS}, but uses @samp{AC_LIBOBJ(@var{function})} as
+ at var{action-if-not-found}. You can declare your replacement function by
+enclosing the prototype in @samp{#ifndef HAVE_ at var{function}}. If the
+system has the function, it probably declares it in a header file you
+should be including, so you shouldn't redeclare it lest your declaration
+conflict.
+ at end defmac
+
+ at node Header Files
+ at section Header Files
+ at cindex Header, checking
+
+The following macros check for the presence of certain C header files.
+If there is no macro specifically defined to check for a header file you need,
+and you don't need to check for any special properties of
+it, then you can use one of the general header-file check macros.
+
+ at menu
+* Header Portability:: Collected knowledge on common headers
+* Particular Headers:: Special handling to find certain headers
+* Generic Headers:: How to find other headers
+ at end menu
+
+ at node Header Portability
+ at subsection Portability of Headers
+ at cindex Portability of headers
+ at cindex Header portability
+
+This section documents some collected knowledge about common headers,
+and the problems they cause. By definition, this list always requires
+additions. A much more complete list is maintained by the Gnulib
+project (@pxref{Gnulib}), covering @ref{Header File Substitutes, ,
+Posix Headers, gnulib, GNU gnulib} and @ref{Glibc Header File
+Substitutes, , Glibc Headers, gnulib, GNU gnulib}. Please help us keep
+the gnulib list as complete as possible.
+
+ at table @asis
+
+ at item @file{limits.h}
+C99 says that @file{limits.h} defines @code{LLONG_MIN},
+ at code{LLONG_MAX}, and @code{ULLONG_MAX}, but many almost-C99
+environments (e.g., default GCC 4.0.2 + glibc 2.4) do not
+define them.
+
+ at item @file{inttypes.h} vs.@: @file{stdint.h}
+ at hdrindex{inttypes.h}
+ at hdrindex{stdint.h}
+The C99 standard says that @file{inttypes.h} includes
+ at file{stdint.h}, so there's no need to include @file{stdint.h}
+separately in a standard environment. Some implementations have
+ at file{inttypes.h} but not @file{stdint.h} (e.g., Solaris 7), but we don't
+know of any implementation that has @file{stdint.h} but not
+ at file{inttypes.h}.
+
+ at item @file{linux/irda.h}
+ at hdrindex{linux/irda.h}
+It requires @file{linux/types.h} and @file{sys/socket.h}.
+
+ at item @file{linux/random.h}
+ at hdrindex{linux/random.h}
+It requires @file{linux/types.h}.
+
+ at item @file{net/if.h}
+ at hdrindex{net/if.h}
+On Darwin, this file requires that @file{sys/socket.h} be included
+beforehand. One should run:
+
+ at example
+AC_CHECK_HEADERS([sys/socket.h])
+AC_CHECK_HEADERS([net/if.h], [], [],
+[#include <stdio.h>
+#ifdef STDC_HEADERS
+# include <stdlib.h>
+# include <stddef.h>
+#else
+# ifdef HAVE_STDLIB_H
+# include <stdlib.h>
+# endif
+#endif
+#ifdef HAVE_SYS_SOCKET_H
+# include <sys/socket.h>
+#endif
+])
+ at end example
+
+ at item @file{netinet/if_ether.h}
+ at hdrindex{netinet/if_ether.h}
+On Darwin, this file requires that @file{stdio.h} and
+ at file{sys/socket.h} be included beforehand. One should run:
+
+ at example
+AC_CHECK_HEADERS([sys/socket.h])
+AC_CHECK_HEADERS([netinet/if_ether.h], [], [],
+[#include <stdio.h>
+#ifdef STDC_HEADERS
+# include <stdlib.h>
+# include <stddef.h>
+#else
+# ifdef HAVE_STDLIB_H
+# include <stdlib.h>
+# endif
+#endif
+#ifdef HAVE_SYS_SOCKET_H
+# include <sys/socket.h>
+#endif
+])
+ at end example
+
+ at item @file{stdint.h}
+See above, item @file{inttypes.h} vs.@: @file{stdint.h}.
+
+ at item @file{stdlib.h}
+ at hdrindex{stdlib.h}
+On many systems (e.g., Darwin), @file{stdio.h} is a prerequisite.
+
+ at item @file{sys/mount.h}
+ at hdrindex{sys/mount.h}
+On FreeBSD 4.8 on ia32 and using gcc version 2.95.4,
+ at file{sys/params.h} is a prerequisite.
+
+ at item @file{sys/ptem.h}
+ at hdrindex{sys/ptem.h}
+On Solaris 8, @file{sys/stream.h} is a prerequisite.
+
+ at item @file{sys/socket.h}
+ at hdrindex{sys/socket.h}
+On Darwin, @file{stdlib.h} is a prerequisite.
+
+ at item @file{sys/ucred.h}
+ at hdrindex{sys/ucred.h}
+On Tru64 5.1, @file{sys/types.h} is a prerequisite.
+
+ at item @file{X11/extensions/scrnsaver.h}
+ at hdrindex{X11/extensions/scrnsaver.h}
+Using XFree86, this header requires @file{X11/Xlib.h}, which is probably
+so required that you might not even consider looking for it.
+
+ at example
+AC_CHECK_HEADERS([X11/extensions/scrnsaver.h], [], [],
+[[#include <X11/Xlib.h>
+]])
+ at end example
+ at end table
+
+
+ at node Particular Headers
+ at subsection Particular Header Checks
+
+These macros check for particular system header files---whether they
+exist, and in some cases whether they declare certain symbols.
+
+ at defmac AC_CHECK_HEADER_STDBOOL
+ at acindex{CHECK_HEADER_STDBOOL}
+ at cvindex HAVE__BOOL
+ at hdrindex{stdbool.h}
+ at caindex header_stdbool_h
+Check whether @file{stdbool.h} exists and conforms to C99, and cache the
+result in the @code{ac_cv_header_stdbool_h} variable. If the type
+ at code{_Bool} is defined, define @code{HAVE__BOOL} to 1.
+
+This macro is intended for use by Gnulib (@pxref{Gnulib}) and other
+packages that supply a substitute @file{stdbool.h} on platforms lacking
+a conforming one. The @code{AC_HEADER_STDBOOL} macro is better for code
+that explicitly checks for @file{stdbool.h}.
+ at end defmac
+
+ at defmac AC_HEADER_ASSERT
+ at acindex{HEADER_ASSERT}
+ at cvindex NDEBUG
+ at hdrindex{assert.h}
+Check whether to enable assertions in the style of @file{assert.h}.
+Assertions are enabled by default, but the user can override this by
+invoking @command{configure} with the @option{--disable-assert} option.
+ at end defmac
+
+ at anchor{AC_HEADER_DIRENT}
+ at defmac AC_HEADER_DIRENT
+ at acindex{HEADER_DIRENT}
+ at cvindex HAVE_DIRENT_H
+ at cvindex HAVE_NDIR_H
+ at cvindex HAVE_SYS_DIR_H
+ at cvindex HAVE_SYS_NDIR_H
+ at hdrindex{dirent.h}
+ at hdrindex{sys/ndir.h}
+ at hdrindex{sys/dir.h}
+ at hdrindex{ndir.h}
+Check for the following header files. For the first one that is
+found and defines @samp{DIR}, define the listed C preprocessor macro:
+
+ at multitable {@file{sys/ndir.h}} {@code{HAVE_SYS_NDIR_H}}
+ at item @file{dirent.h} @tab @code{HAVE_DIRENT_H}
+ at item @file{sys/ndir.h} @tab @code{HAVE_SYS_NDIR_H}
+ at item @file{sys/dir.h} @tab @code{HAVE_SYS_DIR_H}
+ at item @file{ndir.h} @tab @code{HAVE_NDIR_H}
+ at end multitable
+
+The directory-library declarations in your source code should look
+something like the following:
+
+ at example
+ at group
+#include <sys/types.h>
+#ifdef HAVE_DIRENT_H
+# include <dirent.h>
+# define NAMLEN(dirent) strlen ((dirent)->d_name)
+#else
+# define dirent direct
+# define NAMLEN(dirent) ((dirent)->d_namlen)
+# ifdef HAVE_SYS_NDIR_H
+# include <sys/ndir.h>
+# endif
+# ifdef HAVE_SYS_DIR_H
+# include <sys/dir.h>
+# endif
+# ifdef HAVE_NDIR_H
+# include <ndir.h>
+# endif
+#endif
+ at end group
+ at end example
+
+Using the above declarations, the program would declare variables to be
+of type @code{struct dirent}, not @code{struct direct}, and would access
+the length of a directory entry name by passing a pointer to a
+ at code{struct dirent} to the @code{NAMLEN} macro.
+
+This macro also checks for the SCO Xenix @file{dir} and @file{x} libraries.
+
+This macro is obsolescent, as all current systems with directory
+libraries have @code{<dirent.h>}. New programs need not use this macro.
+
+Also see @code{AC_STRUCT_DIRENT_D_INO} and
+ at code{AC_STRUCT_DIRENT_D_TYPE} (@pxref{Particular Structures}).
+ at end defmac
+
+ at anchor{AC_HEADER_MAJOR}
+ at defmac AC_HEADER_MAJOR
+ at acindex{HEADER_MAJOR}
+ at cvindex MAJOR_IN_MKDEV
+ at cvindex MAJOR_IN_SYSMACROS
+ at hdrindex{sys/mkdev.h}
+ at hdrindex{sys/sysmacros.h}
+If @file{sys/types.h} does not define @code{major}, @code{minor}, and
+ at code{makedev}, but @file{sys/mkdev.h} does, define
+ at code{MAJOR_IN_MKDEV}; otherwise, if @file{sys/sysmacros.h} does, define
+ at code{MAJOR_IN_SYSMACROS}.
+ at end defmac
+
+ at defmac AC_HEADER_RESOLV
+ at acindex{HEADER_RESOLV}
+ at cvindex HAVE_RESOLV_H
+ at hdrindex{resolv.h}
+Checks for header @file{resolv.h}, checking for prerequisites first.
+To properly use @file{resolv.h}, your code should contain something like
+the following:
+
+ at verbatim
+#ifdef HAVE_SYS_TYPES_H
+# include <sys/types.h>
+#endif
+#ifdef HAVE_NETINET_IN_H
+# include <netinet/in.h> /* inet_ functions / structs */
+#endif
+#ifdef HAVE_ARPA_NAMESER_H
+# include <arpa/nameser.h> /* DNS HEADER struct */
+#endif
+#ifdef HAVE_NETDB_H
+# include <netdb.h>
+#endif
+#include <resolv.h>
+ at end verbatim
+ at end defmac
+
+ at anchor{AC_HEADER_STAT}
+ at defmac AC_HEADER_STAT
+ at acindex{HEADER_STAT}
+ at cvindex STAT_MACROS_BROKEN
+ at hdrindex{sys/stat.h}
+If the macros @code{S_ISDIR}, @code{S_ISREG}, etc.@: defined in
+ at file{sys/stat.h} do not work properly (returning false positives),
+define @code{STAT_MACROS_BROKEN}. This is the case on Tektronix UTekV,
+Amdahl UTS and Motorola System V/88.
+
+This macro is obsolescent, as no current systems have the bug.
+New programs need not use this macro.
+ at end defmac
+
+ at defmac AC_HEADER_STDBOOL
+ at acindex{HEADER_STDBOOL}
+ at cvindex HAVE_STDBOOL_H
+ at cvindex HAVE__BOOL
+ at hdrindex{stdbool.h}
+ at caindex header_stdbool_h
+If @file{stdbool.h} exists and conforms to C99, define
+ at code{HAVE_STDBOOL_H} to 1; if the type @code{_Bool} is defined, define
+ at code{HAVE__BOOL} to 1. To fulfill the C99 requirements, your
+program could contain the following code:
+
+ at example
+ at group
+#ifdef HAVE_STDBOOL_H
+# include <stdbool.h>
+#else
+# ifndef HAVE__BOOL
+# ifdef __cplusplus
+typedef bool _Bool;
+# else
+# define _Bool signed char
+# endif
+# endif
+# define bool _Bool
+# define false 0
+# define true 1
+# define __bool_true_false_are_defined 1
+#endif
+ at end group
+ at end example
+
+Alternatively you can use the @samp{stdbool} package of Gnulib
+(@pxref{Gnulib}). It simplifies your code so that it can say just
+ at code{#include <stdbool.h>}, and it adds support for less-common
+platforms.
+
+This macro caches its result in the @code{ac_cv_header_stdbool_h}
+variable.
+
+This macro differs from @code{AC_CHECK_HEADER_STDBOOL} only in that it
+defines @code{HAVE_STDBOOL_H} whereas @code{AC_CHECK_HEADER_STDBOOL}
+does not.
+ at end defmac
+
+ at anchor{AC_HEADER_STDC}
+ at defmac AC_HEADER_STDC
+ at acindex{HEADER_STDC}
+ at cvindex STDC_HEADERS
+ at hdrindex{stdlib.h}
+ at hdrindex{stdarg.h}
+ at hdrindex{string.h}
+ at hdrindex{float.h}
+ at hdrindex{ctype.h}
+ at caindex header_stdc
+Define @code{STDC_HEADERS} if the system has C header files
+conforming to ANSI C89 (ISO C90).
+Specifically, this macro checks for @file{stdlib.h}, @file{stdarg.h},
+ at file{string.h}, and @file{float.h}; if the system has those, it
+probably has the rest of the C89 header files. This macro also
+checks whether @file{string.h} declares @code{memchr} (and thus
+presumably the other @code{mem} functions), whether @file{stdlib.h}
+declare @code{free} (and thus presumably @code{malloc} and other related
+functions), and whether the @file{ctype.h} macros work on characters
+with the high bit set, as the C standard requires.
+
+If you use this macro, your code can refer to @code{STDC_HEADERS} to
+determine whether the system has conforming header files (and probably C
+library functions).
+
+This macro caches its result in the @code{ac_cv_header_stdc} variable.
+
+This macro is obsolescent, as current systems have conforming header
+files. New programs need not use this macro.
+
+ at hdrindex{string.h}
+ at hdrindex{strings.h}
+Nowadays @file{string.h} is part of the C standard and declares functions like
+ at code{strcpy}, and @file{strings.h} is standardized by Posix and declares
+BSD functions like @code{bcopy}; but
+historically, string functions were a major sticking point in this area.
+If you still want to worry about portability to ancient systems without
+standard headers, there is so much variation
+that it is probably easier to declare the functions you use than to
+figure out exactly what the system header files declare. Some ancient systems
+contained a mix of functions from the C standard and from BSD;
+some were mostly standard but lacked @samp{memmove}; some defined the
+BSD functions as macros in @file{string.h} or
+ at file{strings.h}; some had only the BSD functions but
+ at file{string.h}; some declared the memory functions in @file{memory.h},
+some in @file{string.h}; etc. It is probably sufficient to check for
+one string function and one memory function; if the library had the
+standard versions of those then it probably had most of the others.
+If you put the following in @file{configure.ac}:
+
+ at example
+# This example is obsolescent.
+# Nowadays you can omit these macro calls.
+AC_HEADER_STDC
+AC_CHECK_FUNCS([strchr memcpy])
+ at end example
+
+ at noindent
+then, in your code, you can use declarations like this:
+
+ at example
+ at group
+/* This example is obsolescent.
+ Nowadays you can just #include <string.h>. */
+#ifdef STDC_HEADERS
+# include <string.h>
+#else
+# ifndef HAVE_STRCHR
+# define strchr index
+# define strrchr rindex
+# endif
+char *strchr (), *strrchr ();
+# ifndef HAVE_MEMCPY
+# define memcpy(d, s, n) bcopy ((s), (d), (n))
+# define memmove(d, s, n) bcopy ((s), (d), (n))
+# endif
+#endif
+ at end group
+ at end example
+
+ at noindent
+If you use a function like @code{memchr}, @code{memset}, @code{strtok},
+or @code{strspn}, which have no BSD equivalent, then macros don't
+suffice to port to ancient hosts; you must provide an implementation of
+each function. An easy
+way to incorporate your implementations only when needed (since the ones
+in system C libraries may be hand optimized) is to, taking @code{memchr}
+for example, put it in @file{memchr.c} and use
+ at samp{AC_REPLACE_FUNCS([memchr])}.
+ at end defmac
+
+ at defmac AC_HEADER_SYS_WAIT
+ at acindex{HEADER_SYS_WAIT}
+ at cvindex HAVE_SYS_WAIT_H
+ at hdrindex{sys/wait.h}
+ at caindex header_sys_wait_h
+If @file{sys/wait.h} exists and is compatible with Posix, define
+ at code{HAVE_SYS_WAIT_H}. Incompatibility can occur if @file{sys/wait.h}
+does not exist, or if it uses the old BSD @code{union wait} instead
+of @code{int} to store a status value. If @file{sys/wait.h} is not
+Posix compatible, then instead of including it, define the
+Posix macros with their usual interpretations. Here is an
+example:
+
+ at example
+ at group
+#include <sys/types.h>
+#ifdef HAVE_SYS_WAIT_H
+# include <sys/wait.h>
+#endif
+#ifndef WEXITSTATUS
+# define WEXITSTATUS(stat_val) ((unsigned int) (stat_val) >> 8)
+#endif
+#ifndef WIFEXITED
+# define WIFEXITED(stat_val) (((stat_val) & 255) == 0)
+#endif
+ at end group
+ at end example
+
+ at noindent
+This macro caches its result in the @code{ac_cv_header_sys_wait_h}
+variable.
+
+This macro is obsolescent, as current systems are compatible with Posix.
+New programs need not use this macro.
+ at end defmac
+
+ at cvindex _POSIX_VERSION
+ at hdrindex{unistd.h}
+ at code{_POSIX_VERSION} is defined when @file{unistd.h} is included on
+Posix systems. If there is no @file{unistd.h}, it is definitely
+not a Posix system. However, some non-Posix systems do
+have @file{unistd.h}.
+
+The way to check whether the system supports Posix is:
+
+ at example
+ at group
+#ifdef HAVE_UNISTD_H
+# include <sys/types.h>
+# include <unistd.h>
+#endif
+
+#ifdef _POSIX_VERSION
+/* Code for Posix systems. */
+#endif
+ at end group
+ at end example
+
+ at anchor{AC_HEADER_TIME}
+ at defmac AC_HEADER_TIME
+ at acindex{HEADER_TIME}
+ at cvindex TIME_WITH_SYS_TIME
+ at hdrindex{time.h}
+ at hdrindex{sys/time.h}
+ at caindex header_time
+If a program may include both @file{time.h} and @file{sys/time.h},
+define @code{TIME_WITH_SYS_TIME}. On some ancient systems,
+ at file{sys/time.h} included @file{time.h}, but @file{time.h} was not
+protected against multiple inclusion, so programs could not explicitly
+include both files. This macro is useful in programs that use, for
+example, @code{struct timeval} as well as
+ at code{struct tm}. It is best used in conjunction with
+ at code{HAVE_SYS_TIME_H}, which can be checked for using
+ at code{AC_CHECK_HEADERS([sys/time.h])}.
+
+ at example
+ at group
+#ifdef TIME_WITH_SYS_TIME
+# include <sys/time.h>
+# include <time.h>
+#else
+# ifdef HAVE_SYS_TIME_H
+# include <sys/time.h>
+# else
+# include <time.h>
+# endif
+#endif
+ at end group
+ at end example
+
+ at noindent
+This macro caches its result in the @code{ac_cv_header_time} variable.
+
+This macro is obsolescent, as current systems can include both files
+when they exist. New programs need not use this macro.
+ at end defmac
+
+
+ at defmac AC_HEADER_TIOCGWINSZ
+ at acindex{HEADER_TIOCGWINSZ}
+ at cvindex GWINSZ_IN_SYS_IOCTL
+ at hdrindex{sys/ioctl.h}
+ at hdrindex{termios.h}
+ at c FIXME: I need clarifications from Jim.
+If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
+define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
+found in @file{<termios.h>}.
+
+Use:
+
+ at example
+ at group
+#ifdef HAVE_TERMIOS_H
+# include <termios.h>
+#endif
+
+#ifdef GWINSZ_IN_SYS_IOCTL
+# include <sys/ioctl.h>
+#endif
+ at end group
+ at end example
+ at end defmac
+
+ at node Generic Headers
+ at subsection Generic Header Checks
+
+These macros are used to find system header files not covered by the
+``particular'' test macros. If you need to check the contents of a header
+as well as find out whether it is present, you have to write your own
+test for it (@pxref{Writing Tests}).
+
+ at anchor{AC_CHECK_HEADER}
+ at defmac AC_CHECK_HEADER (@var{header-file}, @ovar{action-if-found}, @
+ @ovar{action-if-not-found}, @ovar{includes})
+ at acindex{CHECK_HEADER}
+ at caindex header_ at var{header-file}
+If the system header file @var{header-file} is compilable, execute shell
+commands @var{action-if-found}, otherwise execute
+ at var{action-if-not-found}. If you just want to define a symbol if the
+header file is available, consider using @code{AC_CHECK_HEADERS}
+instead.
+
+ at var{includes} is decoded to determine the appropriate include
+directives. If omitted or empty, @file{configure} will check for both header
+existence (with the preprocessor) and usability (with the compiler),
+using @code{AC_INCLUDES_DEFAULT} for the compile test. If
+there is a discrepancy between the results, a warning is issued to the
+user, and the compiler results are favored (@pxref{Present But
+Cannot Be Compiled}). In general, favoring the compiler results means
+that a header will be treated as not found even though the file exists,
+because you did not provide enough prerequisites.
+
+Providing a non-empty @var{includes} argument allows the code to provide
+any prerequisites prior to including the header under test; it is common
+to use the argument @code{AC_INCLUDES_DEFAULT} (@pxref{Default
+Includes}). With an explicit fourth argument, no preprocessor test is
+needed. As a special case, an @var{includes} of exactly @samp{-}
+triggers the older preprocessor check, which merely determines existence
+of the file in the preprocessor search path; this should only be used as
+a last resort (it is safer to determine the actual prerequisites and
+perform a compiler check, or else use @code{AC_PREPROC_IFELSE} to make
+it obvious that only a preprocessor check is desired).
+
+This macro caches its result in the @code{ac_cv_header_ at var{header-file}}
+variable, with characters not suitable for a variable name mapped to
+underscores.
+ at end defmac
+
+ at anchor{AC_CHECK_HEADERS}
+ at defmac AC_CHECK_HEADERS (@var{header-file}@dots{}, @
+ @ovar{action-if-found}, @ovar{action-if-not-found}, @
+ @ovar{includes})
+ at acindex{CHECK_HEADERS}
+ at cvindex HAVE_ at var{header}
+ at caindex header_ at var{header-file}
+For each given system header file @var{header-file} in the
+blank-separated argument list that exists, define
+ at code{HAVE_ at var{header-file}} (in all capitals). If @var{action-if-found}
+is given, it is additional shell code to execute when one of the header
+files is found. You can give it a value of @samp{break} to break out of
+the loop on the first match. If @var{action-if-not-found} is given, it
+is executed when one of the header files is not found.
+
+ at var{includes} is interpreted as in @code{AC_CHECK_HEADER}, in order to
+choose the set of preprocessor directives supplied before the header
+under test.
+
+This macro caches its result in the @code{ac_cv_header_ at var{header-file}}
+variable, with characters not suitable for a variable name mapped to
+underscores.
+ at end defmac
+
+Previous versions of Autoconf merely checked whether the header was
+accepted by the preprocessor. This was changed because the old test was
+inappropriate for typical uses. Headers are typically used to compile,
+not merely to preprocess, and the old behavior sometimes accepted
+headers that clashed at compile-time (@pxref{Present But Cannot Be
+Compiled}). If you need to check whether a header is preprocessable,
+you can use @code{AC_PREPROC_IFELSE} (@pxref{Running the Preprocessor}).
+
+Actually requiring a header to compile improves the robustness of the
+test, but it also requires
+that you make sure that headers that must be included before the
+ at var{header-file} be part of the @var{includes}, (@pxref{Default
+Includes}). If looking for @file{bar.h}, which requires that
+ at file{foo.h} be included before if it exists, we suggest the following
+scheme:
+
+ at verbatim
+AC_CHECK_HEADERS([foo.h])
+AC_CHECK_HEADERS([bar.h], [], [],
+[#ifdef HAVE_FOO_H
+# include <foo.h>
+#endif
+])
+ at end verbatim
+
+The following variant generates smaller, faster @command{configure}
+files if you do not need the full power of @code{AC_CHECK_HEADERS}.
+
+ at defmac AC_CHECK_HEADERS_ONCE (@var{header-file}@dots{})
+ at acindex{CHECK_HEADERS_ONCE}
+ at cvindex HAVE_ at var{header}
+For each given system header file @var{header-file} in the
+blank-separated argument list that exists, define
+ at code{HAVE_ at var{header-file}} (in all capitals).
+This is a once-only variant of @code{AC_CHECK_HEADERS}. It generates the
+checking code at most once, so that @command{configure} is smaller and
+faster; but the checks cannot be conditionalized and are always done once,
+early during the @command{configure} run. Thus, this macro is only safe
+for checking headers that do not have prerequisites beyond what
+ at code{AC_INCLUDES_DEFAULT} provides.
+ at end defmac
+
+ at node Declarations
+ at section Declarations
+ at cindex Declaration, checking
+
+The following macros check for the declaration of variables and
+functions. If there is no macro specifically defined to check for a
+symbol you need, then you can use the general macros (@pxref{Generic
+Declarations}) or, for more complex tests, you may use
+ at code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
+
+ at menu
+* Particular Declarations:: Macros to check for certain declarations
+* Generic Declarations:: How to find other declarations
+ at end menu
+
+ at node Particular Declarations
+ at subsection Particular Declaration Checks
+
+There are no specific macros for declarations.
+
+ at node Generic Declarations
+ at subsection Generic Declaration Checks
+
+These macros are used to find declarations not covered by the ``particular''
+test macros.
+
+ at defmac AC_CHECK_DECL (@var{symbol}, @ovar{action-if-found}, @
+ @ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT})
+ at acindex{CHECK_DECL}
+ at caindex have_decl_ at var{symbol}
+If @var{symbol} (a function, variable, or constant) is not declared in
+ at var{includes} and a declaration is needed, run the shell commands
+ at var{action-if-not-found}, otherwise @var{action-if-found}.
+ at var{includes} is a series of include directives, defaulting to
+ at code{AC_INCLUDES_DEFAULT} (@pxref{Default Includes}), which are used
+prior to the declaration under test.
+
+This macro actually tests whether @var{symbol} is defined as a macro or
+can be used as an r-value, not whether it is really declared, because it
+is much safer to avoid introducing extra declarations when they are not
+needed. In order to facilitate use of C++ and overloaded function
+declarations, it is possible to specify function argument types in
+parentheses for types which can be zero-initialized:
+
+ at example
+AC_CHECK_DECL([basename(char *)])
+ at end example
+
+This macro caches its result in the @code{ac_cv_have_decl_ at var{symbol}}
+variable, with characters not suitable for a variable name mapped to
+underscores.
+ at end defmac
+
+ at anchor{AC_CHECK_DECLS}
+ at defmac AC_CHECK_DECLS (@var{symbols}, @ovar{action-if-found}, @
+ @ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT})
+ at acindex{CHECK_DECLS}
+ at cvindex HAVE_DECL_ at var{symbol}
+ at caindex have_decl_ at var{symbol}
+For each of the @var{symbols} (@emph{comma}-separated list with optional
+function argument types for C++ overloads), define
+ at code{HAVE_DECL_ at var{symbol}} (in all capitals) to @samp{1} if
+ at var{symbol} is declared, otherwise to @samp{0}. If
+ at var{action-if-not-found} is given, it is additional shell code to
+execute when one of the function declarations is needed, otherwise
+ at var{action-if-found} is executed.
+
+ at var{includes} is a series of include directives, defaulting to
+ at code{AC_INCLUDES_DEFAULT} (@pxref{Default Includes}), which are used
+prior to the declarations under test.
+
+This macro uses an M4 list as first argument:
+ at example
+AC_CHECK_DECLS([strdup])
+AC_CHECK_DECLS([strlen])
+AC_CHECK_DECLS([malloc, realloc, calloc, free])
+AC_CHECK_DECLS([j0], [], [], [[#include <math.h>]])
+AC_CHECK_DECLS([[basename(char *)], [dirname(char *)]])
+ at end example
+
+Unlike the other @samp{AC_CHECK_*S} macros, when a @var{symbol} is not
+declared, @code{HAVE_DECL_ at var{symbol}} is defined to @samp{0} instead
+of leaving @code{HAVE_DECL_ at var{symbol}} undeclared. When you are
+ at emph{sure} that the check was performed, use
+ at code{HAVE_DECL_ at var{symbol}} in @code{#if}:
+
+ at example
+#if !HAVE_DECL_SYMBOL
+extern char *symbol;
+#endif
+ at end example
+
+ at noindent
+If the test may have not been performed, however, because it is safer
+ at emph{not} to declare a symbol than to use a declaration that conflicts
+with the system's one, you should use:
+
+ at example
+#if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC
+void *malloc (size_t *s);
+#endif
+ at end example
+
+ at noindent
+You fall into the second category only in extreme situations: either
+your files may be used without being configured, or they are used during
+the configuration. In most cases the traditional approach is enough.
+
+This macro caches its results in @code{ac_cv_have_decl_ at var{symbol}}
+variables, with characters not suitable for a variable name mapped to
+underscores.
+ at end defmac
+
+ at defmac AC_CHECK_DECLS_ONCE (@var{symbols})
+ at acindex{CHECK_DECLS_ONCE}
+ at cvindex HAVE_DECL_ at var{symbol}
+For each of the @var{symbols} (@emph{comma}-separated list), define
+ at code{HAVE_DECL_ at var{symbol}} (in all capitals) to @samp{1} if
+ at var{symbol} is declared in the default include files, otherwise to
+ at samp{0}. This is a once-only variant of @code{AC_CHECK_DECLS}. It
+generates the checking code at most once, so that @command{configure} is
+smaller and faster; but the checks cannot be conditionalized and are
+always done once, early during the @command{configure} run.
+ at end defmac
+
+
+ at node Structures
+ at section Structures
+ at cindex Structure, checking
+
+The following macros check for the presence of certain members in C
+structures. If there is no macro specifically defined to check for a
+member you need, then you can use the general structure-member macros
+(@pxref{Generic Structures}) or, for more complex tests, you may use
+ at code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
+
+ at menu
+* Particular Structures:: Macros to check for certain structure members
+* Generic Structures:: How to find other structure members
+ at end menu
+
+ at node Particular Structures
+ at subsection Particular Structure Checks
+
+The following macros check for certain structures or structure members.
+
+ at defmac AC_STRUCT_DIRENT_D_INO
+ at acindex{STRUCT_DIRENT_D_INO}
+ at cvindex HAVE_STRUCT_DIRENT_D_INO
+ at c @caindex header_dirent_dirent_h
+ at c @caindex member_struct_dirent_d_ino
+Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular
+Headers}). Then, if @code{struct dirent} contains a @code{d_ino}
+member, define @code{HAVE_STRUCT_DIRENT_D_INO}.
+
+ at code{HAVE_STRUCT_DIRENT_D_INO} indicates only the presence of
+ at code{d_ino}, not whether its contents are always reliable.
+Traditionally, a zero @code{d_ino} indicated a deleted directory entry,
+though current systems hide this detail from the user and never return
+zero @code{d_ino} values.
+Many current systems report an incorrect @code{d_ino} for a directory
+entry that is a mount point.
+ at end defmac
+
+ at defmac AC_STRUCT_DIRENT_D_TYPE
+ at acindex{STRUCT_DIRENT_D_TYPE}
+ at cvindex HAVE_STRUCT_DIRENT_D_TYPE
+ at c @caindex header_dirent_dirent_h
+ at c @caindex member_struct_dirent_d_type
+Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular
+Headers}). Then, if @code{struct dirent} contains a @code{d_type}
+member, define @code{HAVE_STRUCT_DIRENT_D_TYPE}.
+ at end defmac
+
+ at anchor{AC_STRUCT_ST_BLOCKS}
+ at defmac AC_STRUCT_ST_BLOCKS
+ at acindex{STRUCT_ST_BLOCKS}
+ at cvindex HAVE_STRUCT_STAT_ST_BLOCKS
+ at cvindex HAVE_ST_BLOCKS
+ at ovindex LIBOBJS
+ at caindex member_struct_stat_st_blocks
+If @code{struct stat} contains an @code{st_blocks} member, define
+ at code{HAVE_STRUCT_STAT_ST_BLOCKS}. Otherwise, require an
+ at code{AC_LIBOBJ} replacement of @samp{fileblocks}. The former name,
+ at code{HAVE_ST_BLOCKS} is to be avoided, as its support will cease in the
+future.
+
+This macro caches its result in the @code{ac_cv_member_struct_stat_st_blocks}
+variable.
+ at end defmac
+
+ at defmac AC_STRUCT_TM
+ at acindex{STRUCT_TM}
+ at cvindex TM_IN_SYS_TIME
+ at hdrindex{time.h}
+ at hdrindex{sys/time.h}
+If @file{time.h} does not define @code{struct tm}, define
+ at code{TM_IN_SYS_TIME}, which means that including @file{sys/time.h}
+had better define @code{struct tm}.
+
+This macro is obsolescent, as @file{time.h} defines @code{struct tm} in
+current systems. New programs need not use this macro.
+ at end defmac
+
+ at anchor{AC_STRUCT_TIMEZONE}
+ at defmac AC_STRUCT_TIMEZONE
+ at acindex{STRUCT_TIMEZONE}
+ at cvindex HAVE_DECL_TZNAME
+ at cvindex HAVE_STRUCT_TM_TM_ZONE
+ at cvindex HAVE_TM_ZONE
+ at cvindex HAVE_TZNAME
+ at c @caindex member_struct_tm_tm_zone
+ at c @caindex struct_tm
+Figure out how to get the current timezone. If @code{struct tm} has a
+ at code{tm_zone} member, define @code{HAVE_STRUCT_TM_TM_ZONE} (and the
+obsoleted @code{HAVE_TM_ZONE}). Otherwise, if the external array
+ at code{tzname} is found, define @code{HAVE_TZNAME}; if it is declared,
+define @code{HAVE_DECL_TZNAME}.
+ at end defmac
+
+ at node Generic Structures
+ at subsection Generic Structure Checks
+
+These macros are used to find structure members not covered by the
+``particular'' test macros.
+
+ at defmac AC_CHECK_MEMBER (@var{aggregate}. at var{member}, @
+ @ovar{action-if-found}, @ovar{action-if-not-found}, @
+ @dvar{includes, AC_INCLUDES_DEFAULT})
+ at acindex{CHECK_MEMBER}
+ at caindex member_ at var{aggregate}_ at var{member}
+Check whether @var{member} is a member of the aggregate @var{aggregate}.
+If no @var{includes} are specified, the default includes are used
+(@pxref{Default Includes}).
+
+ at example
+AC_CHECK_MEMBER([struct passwd.pw_gecos], [],
+ [AC_MSG_ERROR([we need `passwd.pw_gecos'])],
+ [[#include <pwd.h>]])
+ at end example
+
+You can use this macro for submembers:
+
+ at example
+AC_CHECK_MEMBER(struct top.middle.bot)
+ at end example
+
+This macro caches its result in the
+ at code{ac_cv_member_ at var{aggregate}_ at var{member}} variable, with
+characters not suitable for a variable name mapped to underscores.
+ at end defmac
+
+ at anchor{AC_CHECK_MEMBERS}
+ at defmac AC_CHECK_MEMBERS (@var{members}, @ovar{action-if-found}, @
+ @ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT})
+ at acindex{CHECK_MEMBERS}
+ at cvindex HAVE_ at var{aggregate}_ at var{member}
+Check for the existence of each @samp{@var{aggregate}. at var{member}} of
+ at var{members} using the previous macro. When @var{member} belongs to
+ at var{aggregate}, define @code{HAVE_ at var{aggregate}_ at var{member}} (in all
+capitals, with spaces and dots replaced by underscores). If
+ at var{action-if-found} is given, it is executed for each of the found
+members. If @var{action-if-not-found} is given, it is executed for each
+of the members that could not be found.
+
+ at var{includes} is a series of include directives, defaulting to
+ at code{AC_INCLUDES_DEFAULT} (@pxref{Default Includes}), which are used
+prior to the members under test.
+
+This macro uses M4 lists:
+ at example
+AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize])
+ at end example
+ at end defmac
+
+
+ at node Types
+ at section Types
+ at cindex Types
+ at cindex C types
+
+The following macros check for C types, either builtin or typedefs. If
+there is no macro specifically defined to check for a type you need, and
+you don't need to check for any special properties of it, then you can
+use a general type-check macro.
+
+ at menu
+* Particular Types:: Special handling to find certain types
+* Generic Types:: How to find other types
+ at end menu
+
+ at node Particular Types
+ at subsection Particular Type Checks
+
+ at hdrindex{sys/types.h}
+ at hdrindex{stdlib.h}
+ at hdrindex{stdint.h}
+ at hdrindex{inttypes.h}
+These macros check for particular C types in @file{sys/types.h},
+ at file{stdlib.h}, @file{stdint.h}, @file{inttypes.h} and others, if they
+exist.
+
+The Gnulib @code{stdint} module is an alternate way to define many of
+these symbols; it is useful if you prefer your code to assume a
+C99-or-better environment. @xref{Gnulib}.
+
+ at anchor{AC_TYPE_GETGROUPS}
+ at defmac AC_TYPE_GETGROUPS
+ at acindex{TYPE_GETGROUPS}
+ at cvindex GETGROUPS_T
+ at caindex type_getgroups
+Define @code{GETGROUPS_T} to be whichever of @code{gid_t} or @code{int}
+is the base type of the array argument to @code{getgroups}.
+
+This macro caches the base type in the @code{ac_cv_type_getgroups}
+variable.
+ at end defmac
+
+ at defmac AC_TYPE_INT8_T
+ at acindex{TYPE_INT8_T}
+ at cvindex HAVE_INT8_T
+ at cvindex int8_t
+ at caindex c_int8_t
+If @file{stdint.h} or @file{inttypes.h} does not define the type
+ at code{int8_t}, define @code{int8_t} to a signed
+integer type that is exactly 8 bits wide and that uses two's complement
+representation, if such a type exists.
+If you are worried about porting to hosts that lack such a type, you can
+use the results of this macro in C89-or-later code as follows:
+
+ at example
+#if HAVE_STDINT_H
+# include <stdint.h>
+#endif
+#if defined INT8_MAX || defined int8_t
+ @emph{code using int8_t}
+#else
+ @emph{complicated alternative using >8-bit 'signed char'}
+#endif
+ at end example
+
+This macro caches the type in the @code{ac_cv_c_int8_t} variable.
+ at end defmac
+
+ at defmac AC_TYPE_INT16_T
+ at acindex{TYPE_INT16_T}
+ at cvindex HAVE_INT16_T
+ at cvindex int16_t
+ at caindex c_int16_t
+This is like @code{AC_TYPE_INT8_T}, except for 16-bit integers.
+ at end defmac
+
+ at defmac AC_TYPE_INT32_T
+ at acindex{TYPE_INT32_T}
+ at cvindex HAVE_INT32_T
+ at cvindex int32_t
+ at caindex c_int32_t
+This is like @code{AC_TYPE_INT8_T}, except for 32-bit integers.
+ at end defmac
+
+ at defmac AC_TYPE_INT64_T
+ at acindex{TYPE_INT64_T}
+ at cvindex HAVE_INT64_T
+ at cvindex int64_t
+ at caindex c_int64_t
+This is like @code{AC_TYPE_INT8_T}, except for 64-bit integers.
+ at end defmac
+
+ at defmac AC_TYPE_INTMAX_T
+ at acindex{TYPE_INTMAX_T}
+ at cvindex HAVE_INTMAX_T
+ at cvindex intmax_t
+ at c @caindex type_intmax_t
+If @file{stdint.h} or @file{inttypes.h} defines the type @code{intmax_t},
+define @code{HAVE_INTMAX_T}. Otherwise, define @code{intmax_t} to the
+widest signed integer type.
+ at end defmac
+
+ at defmac AC_TYPE_INTPTR_T
+ at acindex{TYPE_INTPTR_T}
+ at cvindex HAVE_INTPTR_T
+ at cvindex intptr_t
+ at c @caindex type_intptr_t
+If @file{stdint.h} or @file{inttypes.h} defines the type @code{intptr_t},
+define @code{HAVE_INTPTR_T}. Otherwise, define @code{intptr_t} to a
+signed integer type wide enough to hold a pointer, if such a type
+exists.
+ at end defmac
+
+ at defmac AC_TYPE_LONG_DOUBLE
+ at acindex{TYPE_LONG_DOUBLE}
+ at cvindex HAVE_LONG_DOUBLE
+ at caindex type_long_double
+If the C compiler supports a working @code{long double} type, define
+ at code{HAVE_LONG_DOUBLE}. The @code{long double} type might have the
+same range and precision as @code{double}.
+
+This macro caches its result in the @code{ac_cv_type_long_double}
+variable.
+
+This macro is obsolescent, as current C compilers support @code{long
+double}. New programs need not use this macro.
+ at end defmac
+
+ at defmac AC_TYPE_LONG_DOUBLE_WIDER
+ at acindex{TYPE_LONG_DOUBLE_WIDER}
+ at cvindex HAVE_LONG_DOUBLE_WIDER
+ at caindex type_long_double_wider
+If the C compiler supports a working @code{long double} type with more
+range or precision than the @code{double} type, define
+ at code{HAVE_LONG_DOUBLE_WIDER}.
+
+This macro caches its result in the @code{ac_cv_type_long_double_wider}
+variable.
+ at end defmac
+
+ at defmac AC_TYPE_LONG_LONG_INT
+ at acindex{TYPE_LONG_LONG_INT}
+ at cvindex HAVE_LONG_LONG_INT
+ at caindex type_long_long_int
+If the C compiler supports a working @code{long long int} type, define
+ at code{HAVE_LONG_LONG_INT}. However, this test does not test
+ at code{long long int} values in preprocessor @code{#if} expressions,
+because too many compilers mishandle such expressions.
+ at xref{Preprocessor Arithmetic}.
+
+This macro caches its result in the @code{ac_cv_type_long_long_int}
+variable.
+ at end defmac
+
+ at defmac AC_TYPE_MBSTATE_T
+ at acindex{TYPE_MBSTATE_T}
+ at cvindex mbstate_t
+ at hdrindex{wchar.h}
+ at caindex type_mbstate_t
+Define @code{HAVE_MBSTATE_T} if @code{<wchar.h>} declares the
+ at code{mbstate_t} type. Also, define @code{mbstate_t} to be a type if
+ at code{<wchar.h>} does not declare it.
+
+This macro caches its result in the @code{ac_cv_type_mbstate_t}
+variable.
+ at end defmac
+
+ at anchor{AC_TYPE_MODE_T}
+ at defmac AC_TYPE_MODE_T
+ at acindex{TYPE_MODE_T}
+ at cvindex mode_t
+ at caindex type_mode_t
+Define @code{mode_t} to a suitable type, if standard headers do not
+define it.
+
+This macro caches its result in the @code{ac_cv_type_mode_t} variable.
+ at end defmac
+
+ at anchor{AC_TYPE_OFF_T}
+ at defmac AC_TYPE_OFF_T
+ at acindex{TYPE_OFF_T}
+ at cvindex off_t
+ at caindex type_off_t
+Define @code{off_t} to a suitable type, if standard headers do not
+define it.
+
+This macro caches its result in the @code{ac_cv_type_off_t} variable.
+ at end defmac
+
+ at anchor{AC_TYPE_PID_T}
+ at defmac AC_TYPE_PID_T
+ at acindex{TYPE_PID_T}
+ at cvindex pid_t
+ at caindex type_pid_t
+Define @code{pid_t} to a suitable type, if standard headers do not
+define it.
+
+This macro caches its result in the @code{ac_cv_type_pid_t} variable.
+ at end defmac
+
+ at anchor{AC_TYPE_SIZE_T}
+ at defmac AC_TYPE_SIZE_T
+ at acindex{TYPE_SIZE_T}
+ at cvindex size_t
+ at caindex type_size_t
+Define @code{size_t} to a suitable type, if standard headers do not
+define it.
+
+This macro caches its result in the @code{ac_cv_type_size_t} variable.
+ at end defmac
+
+ at defmac AC_TYPE_SSIZE_T
+ at acindex{TYPE_SSIZE_T}
+ at cvindex ssize_t
+ at caindex type_ssize_t
+Define @code{ssize_t} to a suitable type, if standard headers do not
+define it.
+
+This macro caches its result in the @code{ac_cv_type_ssize_t} variable.
+ at end defmac
+
+ at anchor{AC_TYPE_UID_T}
+ at defmac AC_TYPE_UID_T
+ at acindex{TYPE_UID_T}
+ at cvindex uid_t
+ at cvindex gid_t
+ at caindex type_uid_t
+Define @code{uid_t} and @code{gid_t} to suitable types, if standard
+headers do not define them.
+
+This macro caches its result in the @code{ac_cv_type_uid_t} variable.
+ at end defmac
+
+ at defmac AC_TYPE_UINT8_T
+ at acindex{TYPE_UINT8_T}
+ at cvindex HAVE_UINT8_T
+ at cvindex uint8_t
+ at caindex c_uint8_t
+If @file{stdint.h} or @file{inttypes.h} does not define the type
+ at code{uint8_t}, define @code{uint8_t} to an
+unsigned integer type that is exactly 8 bits wide, if such a type
+exists.
+This is like @code{AC_TYPE_INT8_T}, except for unsigned integers.
+ at end defmac
+
+ at defmac AC_TYPE_UINT16_T
+ at acindex{TYPE_UINT16_T}
+ at cvindex HAVE_UINT16_T
+ at cvindex uint16_t
+ at caindex c_uint16_t
+This is like @code{AC_TYPE_UINT8_T}, except for 16-bit integers.
+ at end defmac
+
+ at defmac AC_TYPE_UINT32_T
+ at acindex{TYPE_UINT32_T}
+ at cvindex HAVE_UINT32_T
+ at cvindex uint32_t
+ at caindex c_uint32_t
+This is like @code{AC_TYPE_UINT8_T}, except for 32-bit integers.
+ at end defmac
+
+ at defmac AC_TYPE_UINT64_T
+ at acindex{TYPE_UINT64_T}
+ at cvindex HAVE_UINT64_T
+ at cvindex uint64_t
+ at caindex c_uint64_t
+This is like @code{AC_TYPE_UINT8_T}, except for 64-bit integers.
+ at end defmac
+
+ at defmac AC_TYPE_UINTMAX_T
+ at acindex{TYPE_UINTMAX_T}
+ at cvindex HAVE_UINTMAX_T
+ at cvindex uintmax_t
+ at c @caindex type_uintmax_t
+If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintmax_t},
+define @code{HAVE_UINTMAX_T}. Otherwise, define @code{uintmax_t} to the
+widest unsigned integer type.
+ at end defmac
+
+ at defmac AC_TYPE_UINTPTR_T
+ at acindex{TYPE_UINTPTR_T}
+ at cvindex HAVE_UINTPTR_T
+ at cvindex uintptr_t
+ at c @caindex type_uintptr_t
+If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintptr_t},
+define @code{HAVE_UINTPTR_T}. Otherwise, define @code{uintptr_t} to an
+unsigned integer type wide enough to hold a pointer, if such a type
+exists.
+ at end defmac
+
+ at defmac AC_TYPE_UNSIGNED_LONG_LONG_INT
+ at acindex{TYPE_UNSIGNED_LONG_LONG_INT}
+ at cvindex HAVE_UNSIGNED_LONG_LONG_INT
+ at caindex type_unsigned_long_long_int
+If the C compiler supports a working @code{unsigned long long int} type,
+define @code{HAVE_UNSIGNED_LONG_LONG_INT}. However, this test does not test
+ at code{unsigned long long int} values in preprocessor @code{#if} expressions,
+because too many compilers mishandle such expressions.
+ at xref{Preprocessor Arithmetic}.
+
+This macro caches its result in the @code{ac_cv_type_unsigned_long_long_int}
+variable.
+ at end defmac
+
+ at node Generic Types
+ at subsection Generic Type Checks
+
+These macros are used to check for types not covered by the ``particular''
+test macros.
+
+ at defmac AC_CHECK_TYPE (@var{type}, @ovar{action-if-found}, @
+ @ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT})
+ at acindex{CHECK_TYPE}
+ at caindex type_ at var{type}
+Check whether @var{type} is defined. It may be a compiler builtin type
+or defined by the @var{includes}. @var{includes} is a series of include
+directives, defaulting to @code{AC_INCLUDES_DEFAULT} (@pxref{Default
+Includes}), which are used prior to the type under test.
+
+In C, @var{type} must be a type-name, so that the expression @samp{sizeof
+(@var{type})} is valid (but @samp{sizeof ((@var{type}))} is not). The
+same test is applied when compiling for C++, which means that in C++
+ at var{type} should be a type-id and should not be an anonymous
+ at samp{struct} or @samp{union}.
+
+This macro caches its result in the @code{ac_cv_type_ at var{type}}
+variable, with @samp{*} mapped to @samp{p} and other characters not
+suitable for a variable name mapped to underscores.
+ at end defmac
+
+
+ at defmac AC_CHECK_TYPES (@var{types}, @ovar{action-if-found}, @
+ @ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT})
+ at acindex{CHECK_TYPES}
+ at cvindex HAVE_ at var{type}
+For each @var{type} of the @var{types} that is defined, define
+ at code{HAVE_ at var{type}} (in all capitals). Each @var{type} must follow
+the rules of @code{AC_CHECK_TYPE}. If no @var{includes} are
+specified, the default includes are used (@pxref{Default Includes}). If
+ at var{action-if-found} is given, it is additional shell code to execute
+when one of the types is found. If @var{action-if-not-found} is given,
+it is executed when one of the types is not found.
+
+This macro uses M4 lists:
+ at example
+AC_CHECK_TYPES([ptrdiff_t])
+AC_CHECK_TYPES([unsigned long long int, uintmax_t])
+AC_CHECK_TYPES([float_t], [], [], [[#include <math.h>]])
+ at end example
+
+ at end defmac
+
+Autoconf, up to 2.13, used to provide to another version of
+ at code{AC_CHECK_TYPE}, broken by design. In order to keep backward
+compatibility, a simple heuristic, quite safe but not totally, is
+implemented. In case of doubt, read the documentation of the former
+ at code{AC_CHECK_TYPE}, see @ref{Obsolete Macros}.
+
+
+ at node Compilers and Preprocessors
+ at section Compilers and Preprocessors
+ at cindex Compilers
+ at cindex Preprocessors
+
+ at ovindex EXEEXT
+All the tests for compilers (@code{AC_PROG_CC}, @code{AC_PROG_CXX},
+ at code{AC_PROG_F77}) define the output variable @code{EXEEXT} based on
+the output of the compiler, typically to the empty string if
+Posix and @samp{.exe} if a DOS variant.
+
+ at ovindex OBJEXT
+They also define the output variable @code{OBJEXT} based on the
+output of the compiler, after @file{.c} files have been excluded, typically
+to @samp{o} if Posix, @samp{obj} if a DOS variant.
+
+If the compiler being used does not produce executables, the tests fail. If
+the executables can't be run, and cross-compilation is not enabled, they
+fail too. @xref{Manual Configuration}, for more on support for cross
+compiling.
+
+ at menu
+* 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
+ at end menu
+
+ at node Specific Compiler Characteristics
+ at subsection Specific Compiler Characteristics
+
+Some compilers exhibit different behaviors.
+
+ at table @asis
+ at item Static/Dynamic Expressions
+Autoconf relies on a trick to extract one bit of information from the C
+compiler: using negative array sizes. For instance the following
+excerpt of a C source demonstrates how to test whether @samp{int} objects are 4
+bytes wide:
+
+ at example
+static int test_array[sizeof (int) == 4 ? 1 : -1];
+ at end example
+
+ at noindent
+To our knowledge, there is a single compiler that does not support this
+trick: the HP C compilers (the real ones, not only the
+``bundled'') on HP-UX 11.00.
+They incorrectly reject the above program with the diagnostic
+``Variable-length arrays cannot have static storage.''
+This bug comes from HP compilers' mishandling of @code{sizeof (int)},
+not from the @code{? 1 : -1}, and
+Autoconf works around this problem by casting @code{sizeof (int)} to
+ at code{long int} before comparing it.
+ at end table
+
+ at node Generic Compiler Characteristics
+ at subsection Generic Compiler Characteristics
+
+ at anchor{AC_CHECK_SIZEOF}
+ at defmac AC_CHECK_SIZEOF (@var{type-or-expr}, @ovar{unused}, @
+ @dvar{includes, AC_INCLUDES_DEFAULT})
+ at acindex{CHECK_SIZEOF}
+ at cvindex SIZEOF_ at var{type-or-expr}
+ at caindex sizeof_ at var{type-or-expr}
+Define @code{SIZEOF_ at var{type-or-expr}} (@pxref{Standard Symbols}) to be
+the size in bytes of @var{type-or-expr}, which may be either a type or
+an expression returning a value that has a size. If the expression
+ at samp{sizeof (@var{type-or-expr})} is invalid, the result is 0.
+ at var{includes} is a series of include directives, defaulting to
+ at code{AC_INCLUDES_DEFAULT} (@pxref{Default Includes}), which are used
+prior to the expression under test.
+
+This macro now works even when cross-compiling. The @var{unused}
+argument was used when cross-compiling.
+
+For example, the call
+
+ at example
+ at c If you change this example, adjust tests/semantics.at:AC_CHECK_SIZEOF struct.
+AC_CHECK_SIZEOF([int *])
+ at end example
+
+ at noindent
+defines @code{SIZEOF_INT_P} to be 8 on DEC Alpha AXP systems.
+
+This macro caches its result in the @code{ac_cv_sizeof_ at var{type-or-expr}}
+variable, with @samp{*} mapped to @samp{p} and other characters not
+suitable for a variable name mapped to underscores.
+ at end defmac
+
+ at defmac AC_CHECK_ALIGNOF (@var{type}, @dvar{includes, AC_INCLUDES_DEFAULT})
+ at acindex{CHECK_ALIGNOF}
+ at cvindex ALIGNOF_ at var{type}
+ at caindex alignof_ at var{type-or-expr}
+Define @code{ALIGNOF_ at var{type}} (@pxref{Standard Symbols}) to be the
+alignment in bytes of @var{type}. @samp{@var{type} y;} must be valid as
+a structure member declaration. If @samp{type} is unknown, the result
+is 0. If no @var{includes} are specified, the default includes are used
+(@pxref{Default Includes}).
+
+This macro caches its result in the @code{ac_cv_alignof_ at var{type-or-expr}}
+variable, with @samp{*} mapped to @samp{p} and other characters not
+suitable for a variable name mapped to underscores.
+ at end defmac
+
+ at defmac AC_COMPUTE_INT (@var{var}, @var{expression}, @
+ @dvar{includes, AC_INCLUDES_DEFAULT}, @ovar{action-if-fails})
+ at acindex{COMPUTE_INT}
+Store into the shell variable @var{var} the value of the integer
+ at var{expression}. The
+value should fit in an initializer in a C variable of type @code{signed
+long}. To support cross compilation (in which case, the macro only works on
+hosts that use twos-complement arithmetic), it should be possible to evaluate
+the expression at compile-time. If no @var{includes} are specified, the
+default includes are used (@pxref{Default Includes}).
+
+Execute @var{action-if-fails} if the value cannot be determined correctly.
+ at end defmac
+
+ at defmac AC_LANG_WERROR
+ at acindex{LANG_WERROR}
+Normally Autoconf ignores warnings generated by the compiler, linker, and
+preprocessor. If this macro is used, warnings count as fatal
+errors for the current language. This macro is useful when the
+results of configuration are used where warnings are unacceptable; for
+instance, if parts of a program are built with the GCC
+ at option{-Werror}
+option. If the whole program is built using @option{-Werror} it is
+often simpler to put @option{-Werror} in the compiler flags (@code{CFLAGS},
+etc.).
+ at end defmac
+
+ at defmac AC_OPENMP
+ at acindex{OPENMP}
+ at cvindex _OPENMP
+ at ovindex OPENMP_CFLAGS
+ at ovindex OPENMP_CXXFLAGS
+ at ovindex OPENMP_FFLAGS
+ at ovindex OPENMP_FCFLAGS
+ at caindex prog_c_openmp
+ at caindex prog_cxx_openmp
+ at caindex prog_f77_openmp
+ at caindex prog_fc_openmp
+ at uref{http://@/www.openmp.org/, OpenMP} specifies extensions of C, C++,
+and Fortran that simplify optimization of shared memory parallelism,
+which is a common problem on multicore CPUs.
+
+If the current language is C, the macro @code{AC_OPENMP} sets the
+variable @code{OPENMP_CFLAGS} to the C compiler flags needed for
+supporting OpenMP at . @code{OPENMP_CFLAGS} is set to empty if the
+compiler already supports OpenMP, if it has no way to activate OpenMP
+support, or if the user rejects OpenMP support by invoking
+ at samp{configure} with the @samp{--disable-openmp} option.
+
+ at code{OPENMP_CFLAGS} needs to be used when compiling programs, when
+preprocessing program source, and when linking programs. Therefore you
+need to add @code{$(OPENMP_CFLAGS)} to the @code{CFLAGS} of C programs
+that use OpenMP at . If you preprocess OpenMP-specific C code, you also
+need to add @code{$(OPENMP_CFLAGS)} to @code{CPPFLAGS}. The presence of
+OpenMP support is revealed at compile time by the preprocessor macro
+ at code{_OPENMP}.
+
+Linking a program with @code{OPENMP_CFLAGS} typically adds one more
+shared library to the program's dependencies, so its use is recommended
+only on programs that actually require OpenMP.
+
+If the current language is C++, @code{AC_OPENMP} sets the variable
+ at code{OPENMP_CXXFLAGS}, suitably for the C++ compiler. The same remarks
+hold as for C.
+
+If the current language is Fortran 77 or Fortran, @code{AC_OPENMP} sets
+the variable @code{OPENMP_FFLAGS} or @code{OPENMP_FCFLAGS},
+respectively. Similar remarks as for C hold, except that
+ at code{CPPFLAGS} is not used for Fortran, and no preprocessor macro
+signals OpenMP support.
+
+For portability, it is best to avoid spaces between @samp{#} and
+ at samp{pragma omp}. That is, write @samp{#pragma omp}, not
+ at samp{# pragma omp}. The Sun WorkShop 6.2 C compiler chokes on the
+latter.
+
+This macro caches its result in the @code{ac_cv_prog_c_openmp},
+ at code{ac_cv_prog_cxx_openmp}, @code{ac_cv_prog_f77_openmp}, or
+ at code{ac_cv_prog_fc_openmp} variable, depending on the current language.
+ at end defmac
+
+ at node C Compiler
+ at subsection C Compiler Characteristics
+
+The following macros provide ways to find and exercise a C Compiler.
+There are a few constructs that ought to be avoided, but do not deserve
+being checked for, since they can easily be worked around.
+
+ at table @asis
+ at item Don't use lines containing solitary backslashes
+They tickle a bug in the HP-UX C compiler (checked on
+HP-UX 10.20,
+11.00, and 11i). When given the following source:
+
+ at example
+#ifdef __STDC__
+/\
+* A comment with backslash-newlines in it. %@{ %@} *\
+\
+/
+char str[] = "\\
+" A string with backslash-newlines in it %@{ %@} \\
+"";
+char apostrophe = '\\
+\
+'\
+';
+#endif
+ at end example
+
+ at noindent
+the compiler incorrectly fails with the diagnostics ``Non-terminating
+comment at end of file'' and ``Missing @samp{#endif} at end of file.''
+Removing the lines with solitary backslashes solves the problem.
+
+ at item Don't compile several files at once if output matters to you
+Some compilers, such as HP's, report names of files being
+compiled when given more than one file operand. For instance:
+
+ at example
+$ @kbd{cc a.c b.c}
+a.c:
+b.c:
+ at end example
+
+ at noindent
+This can cause problems if you observe the output of the compiler to
+detect failures. Invoking @samp{cc -c a.c && cc -c b.c && cc -o c a.o
+b.o} solves the issue.
+
+ at item Don't rely on @code{#error} failing
+The IRIX C compiler does not fail when #error is preprocessed; it
+simply emits a diagnostic and continues, exiting successfully. So,
+instead of an error directive like @code{#error "Unsupported word size"}
+it is more portable to use an invalid directive like @code{#Unsupported
+word size} in Autoconf tests. In ordinary source code, @code{#error} is
+OK, since installers with inadequate compilers like IRIX can simply
+examine these compilers' diagnostic output.
+
+ at item Don't rely on correct @code{#line} support
+On Solaris, @command{c89} (at least Sun C 5.3 through 5.8)
+diagnoses @code{#line} directives whose line
+numbers are greater than 32767. Nothing in Posix
+makes this invalid. That is why Autoconf stopped issuing
+ at code{#line} directives.
+ at end table
+
+ at defmac AC_PROG_CC (@ovar{compiler-search-list})
+ at acindex{PROG_CC}
+ at evindex CC
+ at evindex CFLAGS
+ at ovindex CC
+ at ovindex CFLAGS
+ at caindex prog_cc_c89
+Determine a C compiler to use. If @code{CC} is not already set in the
+environment, check for @code{gcc} and @code{cc}, then for other C
+compilers. Set output variable @code{CC} to the name of the compiler
+found.
+
+This macro may, however, be invoked with an optional first argument
+which, if specified, must be a blank-separated list of C compilers to
+search for. This just gives the user an opportunity to specify an
+alternative search list for the C compiler. For example, if you didn't
+like the default order, then you could invoke @code{AC_PROG_CC} like
+this:
+
+ at example
+AC_PROG_CC([gcc cl cc])
+ at end example
+
+If the C compiler does not handle function prototypes correctly by
+default, try to add an option to output variable @code{CC} to make it
+so. This macro tries various options that select standard-conformance
+modes on various systems.
+
+After calling this macro you can check whether the C compiler has been
+set to accept ANSI C89 (ISO C90); if not, the shell
+variable
+ at code{ac_cv_prog_cc_c89} is set to @samp{no}. See also
+ at code{AC_C_PROTOTYPES} below.
+
+If using the GNU C compiler, set shell variable @code{GCC} to
+ at samp{yes}. If output variable @code{CFLAGS} was not already set, set
+it to @option{-g -O2} for the GNU C compiler (@option{-O2} on systems
+where GCC does not accept @option{-g}), or @option{-g} for
+other compilers. If your package does not like this default, then it is
+acceptable to insert the line @samp{: $@{CFLAGS=""@}} after @code{AC_INIT}
+and before @code{AC_PROG_CC} to select an empty default instead.
+
+Many Autoconf macros use a compiler, and thus call
+ at samp{AC_REQUIRE([AC_PROG_CC])} to ensure that the compiler has been
+determined before the body of the outermost @code{AC_DEFUN} macro.
+Although @code{AC_PROG_CC} is safe to directly expand multiple times, it
+performs certain checks (such as the proper value of @env{EXEEXT}) only
+on the first invocation. Therefore, care must be used when invoking
+this macro from within another macro rather than at the top level
+(@pxref{Expanded Before Required}).
+ at end defmac
+
+ at anchor{AC_PROG_CC_C_O}
+ at defmac AC_PROG_CC_C_O
+ at acindex{PROG_CC_C_O}
+ at cvindex NO_MINUS_C_MINUS_O
+ at caindex prog_cc_ at var{compiler}_c_o
+If the C compiler does not accept the @option{-c} and @option{-o} options
+simultaneously, define @code{NO_MINUS_C_MINUS_O}. This macro actually
+tests both the compiler found by @code{AC_PROG_CC}, and, if different,
+the first @code{cc} in the path. The test fails if one fails. This
+macro was created for GNU Make to choose the default C compilation
+rule.
+
+For the compiler @var{compiler}, this macro caches its result in the
+ at code{ac_cv_prog_cc_ at var{compiler}_c_o} variable.
+ at end defmac
+
+
+ at defmac AC_PROG_CPP
+ at acindex{PROG_CPP}
+ at evindex CPP
+ at ovindex CPP
+Set output variable @code{CPP} to a command that runs the
+C preprocessor. If @samp{$CC -E} doesn't work, @file{/lib/cpp} is used.
+It is only portable to run @code{CPP} on files with a @file{.c}
+extension.
+
+Some preprocessors don't indicate missing include files by the error
+status. For such preprocessors an internal variable is set that causes
+other macros to check the standard error from the preprocessor and
+consider the test failed if any warnings have been reported.
+For most preprocessors, though, warnings do not cause include-file
+tests to fail unless @code{AC_PROG_CPP_WERROR} is also specified.
+ at end defmac
+
+ at defmac AC_PROG_CPP_WERROR
+ at acindex{PROG_CPP_WERROR}
+ at ovindex CPP
+This acts like @code{AC_PROG_CPP}, except it treats warnings from the
+preprocessor as errors even if the preprocessor exit status indicates
+success. This is useful for avoiding headers that generate mandatory
+warnings, such as deprecation notices.
+ at end defmac
+
+
+The following macros check for C compiler or machine architecture
+features. To check for characteristics not listed here, use
+ at code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
+ at code{AC_RUN_IFELSE} (@pxref{Runtime}).
+
+ at defmac AC_PROG_CC_STDC
+ at acindex{PROG_CC_STDC}
+ at caindex prog_cc_stdc
+If the C compiler cannot compile ISO Standard C (currently
+C99), try to add an option to output variable @code{CC} to make it work.
+If the compiler does not support C99, fall back to supporting
+ANSI C89 (ISO C90).
+
+After calling this macro you can check whether the C compiler has been
+set to accept Standard C; if not, the shell variable
+ at code{ac_cv_prog_cc_stdc} is set to @samp{no}.
+ at end defmac
+
+ at defmac AC_PROG_CC_C89
+ at acindex{PROG_CC_C89}
+ at caindex prog_cc_c89
+If the C compiler is not in ANSI C89 (ISO C90) mode by
+default, try to add an option to output variable @code{CC} to make it
+so. This macro tries various options that select ANSI C89 on
+some system or another, preferring extended functionality modes over
+strict conformance modes. It considers the compiler to be in
+ANSI C89 mode if it handles function prototypes correctly.
+
+After calling this macro you can check whether the C compiler has been
+set to accept ANSI C89; if not, the shell variable
+ at code{ac_cv_prog_cc_c89} is set to @samp{no}.
+
+This macro is called automatically by @code{AC_PROG_CC}.
+ at end defmac
+
+ at defmac AC_PROG_CC_C99
+ at acindex{PROG_CC_C99}
+ at caindex prog_cc_c99
+If the C compiler is not in C99 mode by default, try to add an
+option to output variable @code{CC} to make it so. This macro tries
+various options that select C99 on some system or another, preferring
+extended functionality modes over strict conformance modes. It
+considers the compiler to be in C99 mode if it handles @code{_Bool},
+ at code{//} comments, flexible array members, @code{inline}, signed and
+unsigned @code{long long int}, mixed code and declarations, named
+initialization of structs,
+ at code{restrict}, @code{va_copy}, varargs macros, variable declarations
+in @code{for} loops, and variable length arrays.
+
+After calling this macro you can check whether the C compiler has been
+set to accept C99; if not, the shell variable
+ at code{ac_cv_prog_cc_c99} is set to @samp{no}.
+ at end defmac
+
+ at defmac AC_C_BACKSLASH_A
+ at acindex{C_BACKSLASH_A}
+ at cvindex HAVE_C_BACKSLASH_A
+Define @samp{HAVE_C_BACKSLASH_A} to 1 if the C compiler understands
+ at samp{\a}.
+
+This macro is obsolescent, as current C compilers understand @samp{\a}.
+New programs need not use this macro.
+ at end defmac
+
+ at anchor{AC_C_BIGENDIAN}
+ at defmac AC_C_BIGENDIAN (@ovar{action-if-true}, @ovar{action-if-false}, @
+ @ovar{action-if-unknown}, @ovar{action-if-universal})
+ at acindex{C_BIGENDIAN}
+ at cvindex WORDS_BIGENDIAN
+ at cindex Endianness
+If words are stored with the most significant byte first (like Motorola
+and SPARC CPUs), execute @var{action-if-true}. If words are stored with
+the least significant byte first (like Intel and VAX CPUs), execute
+ at var{action-if-false}.
+
+This macro runs a test-case if endianness cannot be determined from the
+system header files. When cross-compiling, the test-case is not run but
+grep'ed for some magic values. @var{action-if-unknown} is executed if
+the latter case fails to determine the byte sex of the host system.
+
+In some cases a single run of a compiler can generate code for multiple
+architectures. This can happen, for example, when generating Mac OS X
+universal binary files, which work on both PowerPC and Intel
+architectures. In this case, the different variants might be for
+different architectures whose endiannesses differ. If
+ at command{configure} detects this, it executes @var{action-if-universal}
+instead of @var{action-if-unknown}.
+
+The default for @var{action-if-true} is to define
+ at samp{WORDS_BIGENDIAN}. The default for @var{action-if-false} is to do
+nothing. The default for @var{action-if-unknown} is to
+abort configure and tell the installer how to bypass this test.
+And finally, the default for @var{action-if-universal} is to ensure that
+ at samp{WORDS_BIGENDIAN} is defined if and only if a universal build is
+detected and the current code is big-endian; this default works only if
+ at command{autoheader} is used (@pxref{autoheader Invocation}).
+
+If you use this macro without specifying @var{action-if-universal}, you
+should also use @code{AC_CONFIG_HEADERS}; otherwise
+ at samp{WORDS_BIGENDIAN} may be set incorrectly for Mac OS X universal
+binary files.
+ at end defmac
+
+ at anchor{AC_C_CONST}
+ at defmac AC_C_CONST
+ at acindex{C_CONST}
+ at cvindex const
+ at caindex c_const
+If the C compiler does not fully support the @code{const} keyword,
+define @code{const} to be empty. Some C compilers that do
+not define @code{__STDC__} do support @code{const}; some compilers that
+define @code{__STDC__} do not completely support @code{const}. Programs
+can simply use @code{const} as if every C compiler supported it; for
+those that don't, the makefile or configuration header file
+defines it as empty.
+
+Occasionally installers use a C++ compiler to compile C code, typically
+because they lack a C compiler. This causes problems with @code{const},
+because C and C++ treat @code{const} differently. For example:
+
+ at example
+const int foo;
+ at end example
+
+ at noindent
+is valid in C but not in C++. These differences unfortunately cannot be
+papered over by defining @code{const} to be empty.
+
+If @command{autoconf} detects this situation, it leaves @code{const} alone,
+as this generally yields better results in practice. However, using a
+C++ compiler to compile C code is not recommended or supported, and
+installers who run into trouble in this area should get a C compiler
+like GCC to compile their C code.
+
+This macro caches its result in the @code{ac_cv_c_const} variable.
+
+This macro is obsolescent, as current C compilers support @code{const}.
+New programs need not use this macro.
+ at end defmac
+
+ at defmac AC_C_RESTRICT
+ at acindex{C_RESTRICT}
+ at cvindex restrict
+ at caindex c_restrict
+If the C compiler recognizes a variant spelling for the @code{restrict}
+keyword (@code{__restrict}, @code{__restrict__}, or @code{_Restrict}),
+then define @code{restrict} to that; this is more likely to do the right
+thing with compilers that support language variants where plain
+ at code{restrict} is not a keyword. Otherwise, if the C compiler
+recognizes the @code{restrict} keyword, don't do anything.
+Otherwise, define @code{restrict} to be empty.
+Thus, programs may simply use @code{restrict} as if every C compiler
+supported it; for those that do not, the makefile
+or configuration header defines it away.
+
+Although support in C++ for the @code{restrict} keyword is not
+required, several C++ compilers do accept the keyword.
+This macro works for them, too.
+
+This macro caches @samp{no} in the @code{ac_cv_c_restrict} variable
+if @code{restrict} is not supported, and a supported spelling otherwise.
+ at end defmac
+
+ at defmac AC_C_VOLATILE
+ at acindex{C_VOLATILE}
+ at cvindex volatile
+If the C compiler does not understand the keyword @code{volatile},
+define @code{volatile} to be empty. Programs can simply use
+ at code{volatile} as if every C compiler supported it; for those that do
+not, the makefile or configuration header defines it as
+empty.
+
+If the correctness of your program depends on the semantics of
+ at code{volatile}, simply defining it to be empty does, in a sense, break
+your code. However, given that the compiler does not support
+ at code{volatile}, you are at its mercy anyway. At least your
+program compiles, when it wouldn't before.
+ at xref{Volatile Objects}, for more about @code{volatile}.
+
+In general, the @code{volatile} keyword is a standard C feature, so
+you might expect that @code{volatile} is available only when
+ at code{__STDC__} is defined. However, Ultrix 4.3's native compiler does
+support volatile, but does not define @code{__STDC__}.
+
+This macro is obsolescent, as current C compilers support @code{volatile}.
+New programs need not use this macro.
+ at end defmac
+
+ at anchor{AC_C_INLINE}
+ at defmac AC_C_INLINE
+ at acindex{C_INLINE}
+ at cvindex inline
+If the C compiler supports the keyword @code{inline}, do nothing.
+Otherwise define @code{inline} to @code{__inline__} or @code{__inline}
+if it accepts one of those, otherwise define @code{inline} to be empty.
+ at end defmac
+
+ at anchor{AC_C_CHAR_UNSIGNED}
+ at defmac AC_C_CHAR_UNSIGNED
+ at acindex{C_CHAR_UNSIGNED}
+ at cvindex __CHAR_UNSIGNED__
+If the C type @code{char} is unsigned, define @code{__CHAR_UNSIGNED__},
+unless the C compiler predefines it.
+
+These days, using this macro is not necessary. The same information can
+be determined by this portable alternative, thus avoiding the use of
+preprocessor macros in the namespace reserved for the implementation.
+
+ at example
+#include <limits.h>
+#if CHAR_MIN == 0
+# define CHAR_UNSIGNED 1
+#endif
+ at end example
+ at end defmac
+
+ at defmac AC_C_STRINGIZE
+ at acindex{C_STRINGIZE}
+ at cvindex HAVE_STRINGIZE
+If the C preprocessor supports the stringizing operator, define
+ at code{HAVE_STRINGIZE}. The stringizing operator is @samp{#} and is
+found in macros such as this:
+
+ at example
+#define x(y) #y
+ at end example
+
+This macro is obsolescent, as current C compilers support the
+stringizing operator. New programs need not use this macro.
+ at end defmac
+
+ at defmac AC_C_FLEXIBLE_ARRAY_MEMBER
+ at acindex{C_FLEXIBLE_ARRAY_MEMBER}
+ at cvindex FLEXIBLE_ARRAY_MEMBER
+If the C compiler supports flexible array members, define
+ at code{FLEXIBLE_ARRAY_MEMBER} to nothing; otherwise define it to 1.
+That way, a declaration like this:
+
+ at example
+struct s
+ @{
+ size_t n_vals;
+ double val[FLEXIBLE_ARRAY_MEMBER];
+ @};
+ at end example
+
+ at noindent
+will let applications use the ``struct hack'' even with compilers that
+do not support flexible array members. To allocate and use such an
+object, you can use code like this:
+
+ at example
+size_t i;
+size_t n = compute_value_count ();
+struct s *p =
+ malloc (offsetof (struct s, val)
+ + n * sizeof (double));
+p->n_vals = n;
+for (i = 0; i < n; i++)
+ p->val[i] = compute_value (i);
+ at end example
+ at end defmac
+
+ at defmac AC_C_VARARRAYS
+ at acindex{C_VARARRAYS}
+ at cvindex HAVE_C_VARARRAYS
+If the C compiler supports variable-length arrays, define
+ at code{HAVE_C_VARARRAYS}. A variable-length array is an array of automatic
+storage duration whose length is determined at run time, when the array
+is declared.
+ at end defmac
+
+ at defmac AC_C_TYPEOF
+ at acindex{C_TYPEOF}
+ at cvindex HAVE_TYPEOF
+ at cvindex typeof
+If the C compiler supports GCC's @code{typeof} syntax either
+directly or
+through a different spelling of the keyword (e.g., @code{__typeof__}),
+define @code{HAVE_TYPEOF}. If the support is available only through a
+different spelling, define @code{typeof} to that spelling.
+ at end defmac
+
+ at defmac AC_C_PROTOTYPES
+ at acindex{C_PROTOTYPES}
+ at cvindex PROTOTYPES
+ at cvindex __PROTOTYPES
+ at cvindex PARAMS
+If function prototypes are understood by the compiler (as determined by
+ at code{AC_PROG_CC}), define @code{PROTOTYPES} and @code{__PROTOTYPES}.
+Defining @code{__PROTOTYPES} is for the benefit of
+header files that cannot use macros that infringe on user name space.
+
+This macro is obsolescent, as current C compilers support prototypes.
+New programs need not use this macro.
+ at end defmac
+
+ at anchor{AC_PROG_GCC_TRADITIONAL}
+ at defmac AC_PROG_GCC_TRADITIONAL
+ at acindex{PROG_GCC_TRADITIONAL}
+ at ovindex CC
+Add @option{-traditional} to output variable @code{CC} if using the
+GNU C compiler and @code{ioctl} does not work properly without
+ at option{-traditional}. That usually happens when the fixed header files
+have not been installed on an old system.
+
+This macro is obsolescent, since current versions of the GNU C
+compiler fix the header files automatically when installed.
+ at end defmac
+
+
+ at node C++ Compiler
+ at subsection C++ Compiler Characteristics
+
+
+ at defmac AC_PROG_CXX (@ovar{compiler-search-list})
+ at acindex{PROG_CXX}
+ at evindex CXX
+ at evindex CXXFLAGS
+ at ovindex CXX
+ at ovindex CXXFLAGS
+Determine a C++ compiler to use. Check whether the environment variable
+ at code{CXX} or @code{CCC} (in that order) is set; if so, then set output
+variable @code{CXX} to its value.
+
+Otherwise, if the macro is invoked without an argument, then search for
+a C++ compiler under the likely names (first @code{g++} and @code{c++}
+then other names). If none of those checks succeed, then as a last
+resort set @code{CXX} to @code{g++}.
+
+This macro may, however, be invoked with an optional first argument
+which, if specified, must be a blank-separated list of C++ compilers to
+search for. This just gives the user an opportunity to specify an
+alternative search list for the C++ compiler. For example, if you
+didn't like the default order, then you could invoke @code{AC_PROG_CXX}
+like this:
+
+ at example
+AC_PROG_CXX([gcc cl KCC CC cxx cc++ xlC aCC c++ g++])
+ at end example
+
+If using the GNU C++ compiler, set shell variable @code{GXX} to
+ at samp{yes}. If output variable @code{CXXFLAGS} was not already set, set
+it to @option{-g -O2} for the GNU C++ compiler (@option{-O2} on
+systems where G++ does not accept @option{-g}), or @option{-g} for other
+compilers. If your package does not like this default, then it is
+acceptable to insert the line @samp{: $@{CXXFLAGS=""@}} after @code{AC_INIT}
+and before @code{AC_PROG_CXX} to select an empty default instead.
+
+ at end defmac
+
+ at defmac AC_PROG_CXXCPP
+ at acindex{PROG_CXXCPP}
+ at evindex CXXCPP
+ at ovindex CXXCPP
+Set output variable @code{CXXCPP} to a command that runs the C++
+preprocessor. If @samp{$CXX -E} doesn't work, @file{/lib/cpp} is used.
+It is portable to run @code{CXXCPP} only on files with a @file{.c},
+ at file{.C}, @file{.cc}, or @file{.cpp} extension.
+
+Some preprocessors don't indicate missing include files by the error
+status. For such preprocessors an internal variable is set that causes
+other macros to check the standard error from the preprocessor and
+consider the test failed if any warnings have been reported. However,
+it is not known whether such broken preprocessors exist for C++.
+ at end defmac
+
+ at defmac AC_PROG_CXX_C_O
+ at acindex{PROG_CXX_C_O}
+ at cvindex CXX_NO_MINUS_C_MINUS_O
+Test whether the C++ compiler accepts the options @option{-c} and
+ at option{-o} simultaneously, and define @code{CXX_NO_MINUS_C_MINUS_O},
+if it does not.
+ at end defmac
+
+
+ at node Objective C Compiler
+ at subsection Objective C Compiler Characteristics
+
+
+ at defmac AC_PROG_OBJC (@ovar{compiler-search-list})
+ at acindex{PROG_OBJC}
+ at evindex OBJC
+ at evindex OBJCFLAGS
+ at ovindex OBJC
+ at ovindex OBJCFLAGS
+Determine an Objective C compiler to use. If @code{OBJC} is not already
+set in the environment, check for Objective C compilers. Set output
+variable @code{OBJC} to the name of the compiler found.
+
+This macro may, however, be invoked with an optional first argument
+which, if specified, must be a blank-separated list of Objective C compilers to
+search for. This just gives the user an opportunity to specify an
+alternative search list for the Objective C compiler. For example, if you
+didn't like the default order, then you could invoke @code{AC_PROG_OBJC}
+like this:
+
+ at example
+AC_PROG_OBJC([gcc objcc objc])
+ at end example
+
+If using the GNU Objective C compiler, set shell variable
+ at code{GOBJC} to @samp{yes}. If output variable @code{OBJCFLAGS} was not
+already set, set it to @option{-g -O2} for the GNU Objective C
+compiler (@option{-O2} on systems where @command{gcc} does not accept
+ at option{-g}), or @option{-g} for other compilers.
+ at end defmac
+
+ at defmac AC_PROG_OBJCPP
+ at acindex{PROG_OBJCPP}
+ at evindex OBJCPP
+ at ovindex OBJCPP
+Set output variable @code{OBJCPP} to a command that runs the Objective C
+preprocessor. If @samp{$OBJC -E} doesn't work, @file{/lib/cpp} is used.
+ at end defmac
+
+
+ at node Objective C++ Compiler
+ at subsection Objective C++ Compiler Characteristics
+
+
+ at defmac AC_PROG_OBJCXX (@ovar{compiler-search-list})
+ at acindex{PROG_OBJCXX}
+ at evindex OBJCXX
+ at evindex OBJCXXFLAGS
+ at ovindex OBJCXX
+ at ovindex OBJCXXFLAGS
+Determine an Objective C++ compiler to use. If @code{OBJCXX} is not already
+set in the environment, check for Objective C++ compilers. Set output
+variable @code{OBJCXX} to the name of the compiler found.
+
+This macro may, however, be invoked with an optional first argument
+which, if specified, must be a blank-separated list of Objective C++ compilers
+to search for. This just gives the user an opportunity to specify an
+alternative search list for the Objective C++ compiler. For example, if you
+didn't like the default order, then you could invoke @code{AC_PROG_OBJCXX}
+like this:
+
+ at example
+AC_PROG_OBJCXX([gcc g++ objcc++ objcxx])
+ at end example
+
+If using the GNU Objective C++ compiler, set shell variable
+ at code{GOBJCXX} to @samp{yes}. If output variable @code{OBJCXXFLAGS} was not
+already set, set it to @option{-g -O2} for the GNU Objective C++
+compiler (@option{-O2} on systems where @command{gcc} does not accept
+ at option{-g}), or @option{-g} for other compilers.
+ at end defmac
+
+ at defmac AC_PROG_OBJCXXCPP
+ at acindex{PROG_OBJCXXCPP}
+ at evindex OBJCXXCPP
+ at ovindex OBJCXXCPP
+Set output variable @code{OBJCXXCPP} to a command that runs the Objective C++
+preprocessor. If @samp{$OBJCXX -E} doesn't work, @file{/lib/cpp} is used.
+ at end defmac
+
+
+ at node Erlang Compiler and Interpreter
+ at subsection Erlang Compiler and Interpreter Characteristics
+ at cindex Erlang
+
+Autoconf defines the following macros for determining paths to the essential
+Erlang/OTP programs:
+
+ at defmac AC_ERLANG_PATH_ERLC (@ovar{value-if-not-found}, @dvar{path, $PATH})
+ at acindex{ERLANG_PATH_ERLC}
+ at evindex ERLC
+ at evindex ERLCFLAGS
+ at ovindex ERLC
+ at ovindex ERLCFLAGS
+Determine an Erlang compiler to use. If @code{ERLC} is not already set in the
+environment, check for @command{erlc}. Set output variable @code{ERLC} to the
+complete path of the compiler command found. In addition, if @code{ERLCFLAGS}
+is not set in the environment, set it to an empty value.
+
+The two optional arguments have the same meaning as the two last arguments of
+macro @code{AC_PATH_PROG} for looking for the @command{erlc} program. For
+example, to look for @command{erlc} only in the @file{/usr/lib/erlang/bin}
+directory:
+
+ at example
+AC_ERLANG_PATH_ERLC([not found], [/usr/lib/erlang/bin])
+ at end example
+ at end defmac
+
+ at defmac AC_ERLANG_NEED_ERLC (@dvar{path, $PATH})
+ at acindex{ERLANG_NEED_ERLC}
+A simplified variant of the @code{AC_ERLANG_PATH_ERLC} macro, that prints an
+error message and exits the @command{configure} script if the @command{erlc}
+program is not found.
+ at end defmac
+
+ at defmac AC_ERLANG_PATH_ERL (@ovar{value-if-not-found}, @dvar{path, $PATH})
+ at acindex{ERLANG_PATH_ERL}
+ at evindex ERL
+ at ovindex ERL
+Determine an Erlang interpreter to use. If @code{ERL} is not already
+set in the
+environment, check for @command{erl}. Set output variable @code{ERL} to the
+complete path of the interpreter command found.
+
+The two optional arguments have the same meaning as the two last arguments of
+macro @code{AC_PATH_PROG} for looking for the @command{erl} program. For
+example, to look for @command{erl} only in the @file{/usr/lib/erlang/bin}
+directory:
+
+ at example
+AC_ERLANG_PATH_ERL([not found], [/usr/lib/erlang/bin])
+ at end example
+ at end defmac
+
+ at defmac AC_ERLANG_NEED_ERL (@dvar{path, $PATH})
+ at acindex{ERLANG_NEED_ERL}
+A simplified variant of the @code{AC_ERLANG_PATH_ERL} macro, that prints an
+error message and exits the @command{configure} script if the @command{erl}
+program is not found.
+ at end defmac
+
+
+ at node Fortran Compiler
+ at subsection Fortran Compiler Characteristics
+ at cindex Fortran
+ at cindex F77
+
+The Autoconf Fortran support is divided into two categories: legacy
+Fortran 77 macros (@code{F77}), and modern Fortran macros (@code{FC}).
+The former are intended for traditional Fortran 77 code, and have output
+variables like @code{F77}, @code{FFLAGS}, and @code{FLIBS}. The latter
+are for newer programs that can (or must) compile under the newer
+Fortran standards, and have output variables like @code{FC},
+ at code{FCFLAGS}, and @code{FCLIBS}.
+
+Except for the macros @code{AC_FC_SRCEXT}, @code{AC_FC_FREEFORM},
+ at code{AC_FC_FIXEDFORM}, and @code{AC_FC_LINE_LENGTH} (see below), the
+ at code{FC} and @code{F77} macros behave almost identically, and so they
+are documented together in this section.
+
+
+ at defmac AC_PROG_F77 (@ovar{compiler-search-list})
+ at acindex{PROG_F77}
+ at evindex F77
+ at evindex FFLAGS
+ at ovindex F77
+ at ovindex FFLAGS
+ at caindex f77_compiler_gnu
+ at caindex prog_f77_g
+Determine a Fortran 77 compiler to use. If @code{F77} is not already
+set in the environment, then check for @code{g77} and @code{f77}, and
+then some other names. Set the output variable @code{F77} to the name
+of the compiler found.
+
+This macro may, however, be invoked with an optional first argument
+which, if specified, must be a blank-separated list of Fortran 77
+compilers to search for. This just gives the user an opportunity to
+specify an alternative search list for the Fortran 77 compiler. For
+example, if you didn't like the default order, then you could invoke
+ at code{AC_PROG_F77} like this:
+
+ at example
+AC_PROG_F77([fl32 f77 fort77 xlf g77 f90 xlf90])
+ at end example
+
+If using @code{g77} (the GNU Fortran 77 compiler), then
+set the shell variable @code{G77} to @samp{yes}.
+If the output variable @code{FFLAGS} was not already set in the
+environment, then set it to @option{-g -02} for @code{g77} (or @option{-O2}
+where @code{g77} does not accept @option{-g}). Otherwise, set
+ at code{FFLAGS} to @option{-g} for all other Fortran 77 compilers.
+
+The result of the GNU test is cached in the
+ at code{ac_cv_f77_compiler_gnu} variable, acceptance of @option{-g} in the
+ at code{ac_cv_prog_f77_g} variable.
+ at end defmac
+
+ at defmac AC_PROG_FC (@ovar{compiler-search-list}, @ovar{dialect})
+ at acindex{PROG_FC}
+ at evindex FC
+ at evindex FCFLAGS
+ at ovindex FC
+ at ovindex FCFLAGS
+ at caindex fc_compiler_gnu
+ at caindex prog_fc_g
+Determine a Fortran compiler to use. If @code{FC} is not already set in
+the environment, then @code{dialect} is a hint to indicate what Fortran
+dialect to search for; the default is to search for the newest available
+dialect. Set the output variable @code{FC} to the name of the compiler
+found.
+
+By default, newer dialects are preferred over older dialects, but if
+ at code{dialect} is specified then older dialects are preferred starting
+with the specified dialect. @code{dialect} can currently be one of
+Fortran 77, Fortran 90, or Fortran 95. However, this is only a hint of
+which compiler @emph{name} to prefer (e.g., @code{f90} or @code{f95}),
+and no attempt is made to guarantee that a particular language standard
+is actually supported. Thus, it is preferable that you avoid the
+ at code{dialect} option, and use AC_PROG_FC only for code compatible with
+the latest Fortran standard.
+
+This macro may, alternatively, be invoked with an optional first argument
+which, if specified, must be a blank-separated list of Fortran
+compilers to search for, just as in @code{AC_PROG_F77}.
+
+If using @code{gfortran} or @code{g77} (the GNU Fortran compilers), then
+set the shell variable @code{GFC} to @samp{yes}.
+If the output variable @code{FCFLAGS} was not already set in the
+environment, then set it to @option{-g -02} for GNU @code{g77} (or
+ at option{-O2} where @code{g77} does not accept @option{-g}). Otherwise,
+set @code{FCFLAGS} to @option{-g} for all other Fortran compilers.
+
+The result of the GNU test is cached in the @code{ac_cv_fc_compiler_gnu}
+variable, acceptance of @option{-g} in the @code{ac_cv_prog_fc_g}
+variable.
+ at end defmac
+
+ at defmac AC_PROG_F77_C_O
+ at defmacx AC_PROG_FC_C_O
+ at acindex{PROG_F77_C_O}
+ at acindex{PROG_FC_C_O}
+ at cvindex F77_NO_MINUS_C_MINUS_O
+ at cvindex FC_NO_MINUS_C_MINUS_O
+ at caindex prog_f77_c_o
+ at caindex prog_fc_c_o
+Test whether the Fortran compiler accepts the options @option{-c} and
+ at option{-o} simultaneously, and define @code{F77_NO_MINUS_C_MINUS_O} or
+ at code{FC_NO_MINUS_C_MINUS_O}, respectively, if it does not.
+
+The result of the test is cached in the @code{ac_cv_prog_f77_c_o} or
+ at code{ac_cv_prog_fc_c_o} variable, respectively.
+ at end defmac
+
+The following macros check for Fortran compiler characteristics.
+To check for characteristics not listed here, use
+ at code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
+ at code{AC_RUN_IFELSE} (@pxref{Runtime}), making sure to first set the
+current language to Fortran 77 or Fortran via @code{AC_LANG([Fortran 77])}
+or @code{AC_LANG(Fortran)} (@pxref{Language Choice}).
+
+
+ at defmac AC_F77_LIBRARY_LDFLAGS
+ at defmacx AC_FC_LIBRARY_LDFLAGS
+ at acindex{F77_LIBRARY_LDFLAGS}
+ at ovindex FLIBS
+ at acindex{FC_LIBRARY_LDFLAGS}
+ at ovindex FCLIBS
+ at caindex prog_f77_v
+ at caindex prog_fc_v
+ at caindex f77_libs
+ at caindex fc_libs
+Determine the linker flags (e.g., @option{-L} and @option{-l}) for the
+ at dfn{Fortran intrinsic and runtime libraries} that are required to
+successfully link a Fortran program or shared library. The output
+variable @code{FLIBS} or @code{FCLIBS} is set to these flags (which
+should be included after @code{LIBS} when linking).
+
+This macro is intended to be used in those situations when it is
+necessary to mix, e.g., C++ and Fortran source code in a single
+program or shared library (@pxref{Mixing Fortran 77 With C and C++, , ,
+automake, GNU Automake}).
+
+For example, if object files from a C++ and Fortran compiler must be
+linked together, then the C++ compiler/linker must be used for linking
+(since special C++-ish things need to happen at link time like calling
+global constructors, instantiating templates, enabling exception
+support, etc.).
+
+However, the Fortran intrinsic and runtime libraries must be linked in
+as well, but the C++ compiler/linker doesn't know by default how to add
+these Fortran 77 libraries. Hence, this macro was created to determine
+these Fortran libraries.
+
+The macros @code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or
+ at code{AC_F77_MAIN} and @code{AC_FC_MAIN} are probably also necessary to
+link C/C++ with Fortran; see below. Further, it is highly recommended
+that you use @code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers})
+because the complex defines that the function wrapper macros create
+may not work with C/C++ compiler drivers.
+
+These macros internally compute the flag needed to verbose linking
+output and cache it in @code{ac_cv_prog_f77_v} or @code{ac_cv_prog_fc_v}
+variables, respectively. The computed linker flags are cached in
+ at code{ac_cv_f77_libs} or @code{ac_cv_fc_libs}, respectively.
+ at end defmac
+
+ at defmac AC_F77_DUMMY_MAIN (@ovar{action-if-found}, @dvar{action-if-not-found, @
+ AC_MSG_FAILURE})
+ at defmacx AC_FC_DUMMY_MAIN (@ovar{action-if-found}, @dvar{action-if-not-found, @
+ AC_MSG_FAILURE})
+ at acindex{F77_DUMMY_MAIN}
+ at cvindex F77_DUMMY_MAIN
+ at acindex{FC_DUMMY_MAIN}
+ at cvindex FC_DUMMY_MAIN
+ at caindex f77_dummy_main
+ at caindex fc_dummy_main
+With many compilers, the Fortran libraries detected by
+ at code{AC_F77_LIBRARY_LDFLAGS} or @code{AC_FC_LIBRARY_LDFLAGS} provide
+their own @code{main} entry function that initializes things like
+Fortran I/O, and which then calls a user-provided entry function named
+(say) @code{MAIN__} to run the user's program. The
+ at code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or
+ at code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros figure out how to deal with
+this interaction.
+
+When using Fortran for purely numerical functions (no I/O, etc.)@: often
+one prefers to provide one's own @code{main} and skip the Fortran
+library initializations. In this case, however, one may still need to
+provide a dummy @code{MAIN__} routine in order to prevent linking errors
+on some systems. @code{AC_F77_DUMMY_MAIN} or @code{AC_FC_DUMMY_MAIN}
+detects whether any such routine is @emph{required} for linking, and
+what its name is; the shell variable @code{F77_DUMMY_MAIN} or
+ at code{FC_DUMMY_MAIN} holds this name, @code{unknown} when no solution
+was found, and @code{none} when no such dummy main is needed.
+
+By default, @var{action-if-found} defines @code{F77_DUMMY_MAIN} or
+ at code{FC_DUMMY_MAIN} to the name of this routine (e.g., @code{MAIN__})
+ at emph{if} it is required. @var{action-if-not-found} defaults to
+exiting with an error.
+
+In order to link with Fortran routines, the user's C/C++ program should
+then include the following code to define the dummy main if it is
+needed:
+
+ at example
+ at c If you change this example, adjust tests/fortran.at:AC_F77_DUMMY_MAIN usage.
+#ifdef F77_DUMMY_MAIN
+# ifdef __cplusplus
+ extern "C"
+# endif
+ int F77_DUMMY_MAIN () @{ return 1; @}
+#endif
+ at end example
+
+(Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
+
+Note that this macro is called automatically from @code{AC_F77_WRAPPERS}
+or @code{AC_FC_WRAPPERS}; there is generally no need to call it
+explicitly unless one wants to change the default actions.
+
+The result of this macro is cached in the @code{ac_cv_f77_dummy_main} or
+ at code{ac_cv_fc_dummy_main} variable, respectively.
+ at end defmac
+
+ at defmac AC_F77_MAIN
+ at defmacx AC_FC_MAIN
+ at acindex{F77_MAIN}
+ at cvindex F77_MAIN
+ at acindex{FC_MAIN}
+ at cvindex FC_MAIN
+ at caindex f77_main
+ at caindex fc_main
+As discussed above, many Fortran libraries allow you to provide an entry
+point called (say) @code{MAIN__} instead of the usual @code{main}, which
+is then called by a @code{main} function in the Fortran libraries that
+initializes things like Fortran I/O at . The
+ at code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros detect whether it is
+ at emph{possible} to utilize such an alternate main function, and defines
+ at code{F77_MAIN} and @code{FC_MAIN} to the name of the function. (If no
+alternate main function name is found, @code{F77_MAIN} and @code{FC_MAIN} are
+simply defined to @code{main}.)
+
+Thus, when calling Fortran routines from C that perform things like I/O,
+one should use this macro and declare the "main" function like so:
+
+ at example
+ at c If you change this example, adjust tests/fortran.at:AC_F77_DUMMY_MAIN usage.
+#ifdef __cplusplus
+ extern "C"
+#endif
+int F77_MAIN (int argc, char *argv[]);
+ at end example
+
+(Again, replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
+
+The result of this macro is cached in the @code{ac_cv_f77_main} or
+ at code{ac_cv_fc_main} variable, respectively.
+ at end defmac
+
+ at defmac AC_F77_WRAPPERS
+ at defmacx AC_FC_WRAPPERS
+ at acindex{F77_WRAPPERS}
+ at cvindex F77_FUNC
+ at cvindex F77_FUNC_
+ at acindex{FC_WRAPPERS}
+ at cvindex FC_FUNC
+ at cvindex FC_FUNC_
+ at caindex f77_mangling
+ at caindex fc_mangling
+Defines C macros @code{F77_FUNC (name, NAME)}, @code{FC_FUNC (name, NAME)},
+ at code{F77_FUNC_(name, NAME)}, and @code{FC_FUNC_(name, NAME)} to properly
+mangle the names of C/C++ identifiers, and identifiers with underscores,
+respectively, so that they match the name-mangling scheme used by the
+Fortran compiler.
+
+Fortran is case-insensitive, and in order to achieve this the Fortran
+compiler converts all identifiers into a canonical case and format. To
+call a Fortran subroutine from C or to write a C function that is
+callable from Fortran, the C program must explicitly use identifiers in
+the format expected by the Fortran compiler. In order to do this, one
+simply wraps all C identifiers in one of the macros provided by
+ at code{AC_F77_WRAPPERS} or @code{AC_FC_WRAPPERS}. For example, suppose
+you have the following Fortran 77 subroutine:
+
+ at example
+ at c If you change this example, adjust tests/fortran.at:AC_F77_DUMMY_MAIN usage.
+ subroutine foobar (x, y)
+ double precision x, y
+ y = 3.14159 * x
+ return
+ end
+ at end example
+
+You would then declare its prototype in C or C++ as:
+
+ at example
+ at c If you change this example, adjust tests/fortran.at:AC_F77_DUMMY_MAIN usage.
+#define FOOBAR_F77 F77_FUNC (foobar, FOOBAR)
+#ifdef __cplusplus
+extern "C" /* prevent C++ name mangling */
+#endif
+void FOOBAR_F77 (double *x, double *y);
+ at end example
+
+Note that we pass both the lowercase and uppercase versions of the
+function name to @code{F77_FUNC} so that it can select the right one.
+Note also that all parameters to Fortran 77 routines are passed as
+pointers (@pxref{Mixing Fortran 77 With C and C++, , , automake, GNU
+Automake}).
+
+(Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
+
+Although Autoconf tries to be intelligent about detecting the
+name-mangling scheme of the Fortran compiler, there may be Fortran
+compilers that it doesn't support yet. In this case, the above code
+generates a compile-time error, but some other behavior
+(e.g., disabling Fortran-related features) can be induced by checking
+whether @code{F77_FUNC} or @code{FC_FUNC} is defined.
+
+Now, to call that routine from a C program, we would do something like:
+
+ at example
+ at c If you change this example, adjust tests/fortran.at:AC_F77_DUMMY_MAIN usage.
+@{
+ double x = 2.7183, y;
+ FOOBAR_F77 (&x, &y);
+@}
+ at end example
+
+If the Fortran identifier contains an underscore (e.g., @code{foo_bar}),
+you should use @code{F77_FUNC_} or @code{FC_FUNC_} instead of
+ at code{F77_FUNC} or @code{FC_FUNC} (with the same arguments). This is
+because some Fortran compilers mangle names differently if they contain
+an underscore.
+
+The name mangling scheme is encoded in the @code{ac_cv_f77_mangling} or
+ at code{ac_cv_fc_mangling} cache variable, respectively, and also used for
+the @code{AC_F77_FUNC} and @code{AC_FC_FUNC} macros described below.
+ at end defmac
+
+ at defmac AC_F77_FUNC (@var{name}, @ovar{shellvar})
+ at defmacx AC_FC_FUNC (@var{name}, @ovar{shellvar})
+ at acindex{F77_FUNC}
+ at acindex{FC_FUNC}
+Given an identifier @var{name}, set the shell variable @var{shellvar} to
+hold the mangled version @var{name} according to the rules of the
+Fortran linker (see also @code{AC_F77_WRAPPERS} or
+ at code{AC_FC_WRAPPERS}). @var{shellvar} is optional; if it is not
+supplied, the shell variable is simply @var{name}. The purpose of
+this macro is to give the caller a way to access the name-mangling
+information other than through the C preprocessor as above, for example,
+to call Fortran routines from some language other than C/C++.
+ at end defmac
+
+ at defmac AC_FC_SRCEXT (@var{ext}, @ovar{action-if-success}, @
+ @dvar{action-if-failure, AC_MSG_FAILURE})
+ at defmacx AC_FC_PP_SRCEXT (@var{ext}, @ovar{action-if-success}, @
+ @dvar{action-if-failure, AC_MSG_FAILURE})
+ at acindex{FC_SRCEXT}
+ at acindex{FC_PP_SRCEXT}
+ at caindex fc_srcext_ at var{ext}
+ at caindex fc_pp_srcext_ at var{ext}
+By default, the @code{FC} macros perform their tests using a @file{.f}
+extension for source-code files. Some compilers, however, only enable
+newer language features for appropriately named files, e.g., Fortran 90
+features only for @file{.f90} files, or preprocessing only with
+ at file{.F} files or maybe other upper-case extensions. On the other
+hand, some other compilers expect all source files to end in @file{.f}
+and require special flags to support other file name extensions. The
+ at code{AC_FC_SRCEXT} and @code{AC_FC_PP_SRCEXT} macros deal with these
+issues.
+
+The @code{AC_FC_SRCEXT} macro tries to get the @code{FC} compiler to
+accept files ending with the extension @file{. at var{ext}} (i.e.,
+ at var{ext} does @emph{not} contain the dot). If any special compiler
+flags are needed for this, it stores them in the output variable
+ at code{FCFLAGS_ at var{ext}}. This extension and these flags are then used
+for all subsequent @code{FC} tests (until @code{AC_FC_SRCEXT} or
+ at code{AC_FC_PP_SRCEXT} is called another time).
+
+For example, you would use @code{AC_FC_SRCEXT(f90)} to employ the
+ at file{.f90} extension in future tests, and it would set the
+ at code{FCFLAGS_f90} output variable with any extra flags that are needed
+to compile such files.
+
+Similarly, the @code{AC_FC_PP_SRCEXT} macro tries to get the @code{FC}
+compiler to preprocess and compile files with the extension
+ at file{. at var{ext}}. When both @command{fpp} and @command{cpp} style
+preprocessing are provided, the former is preferred, as the latter may
+treat continuation lines, @code{//} tokens, and white space differently
+from what some Fortran dialects expect. Conversely, if you do not want
+files to be preprocessed, use only lower-case characters in the file
+name extension. Like with @code{AC_FC_SRCEXT(f90)}, any needed flags
+are stored in the @code{FCFLAGS_ at var{ext}} variable.
+
+The @code{FCFLAGS_ at var{ext}} flags can @emph{not} be simply absorbed
+into @code{FCFLAGS}, for two reasons based on the limitations of some
+compilers. First, only one @code{FCFLAGS_ at var{ext}} can be used at a
+time, so files with different extensions must be compiled separately.
+Second, @code{FCFLAGS_ at var{ext}} must appear @emph{immediately} before
+the source-code file name when compiling. So, continuing the example
+above, you might compile a @file{foo.f90} file in your makefile with the
+command:
+
+ at example
+foo.o: foo.f90
+ $(FC) -c $(FCFLAGS) $(FCFLAGS_f90) '$(srcdir)/foo.f90'
+ at end example
+
+If @code{AC_FC_SRCEXT} or @code{AC_FC_PP_SRCEXT} succeeds in compiling
+files with the @var{ext} extension, it calls @var{action-if-success}
+(defaults to nothing). If it fails, and cannot find a way to make the
+ at code{FC} compiler accept such files, it calls @var{action-if-failure}
+(defaults to exiting with an error message).
+
+The @code{AC_FC_SRCEXT} and @code{AC_FC_PP_SRCEXT} macros cache their
+results in @code{ac_cv_fc_srcext_ at var{ext}} and
+ at code{ac_cv_fc_pp_srcext_ at var{ext}} variables, respectively.
+ at end defmac
+
+ at defmac AC_FC_PP_DEFINE (@ovar{action-if-success}, @dvar{action-if-failure, @
+ AC_MSG_FAILURE})
+ at acindex{FC_PP_DEFINE}
+ at caindex fc_pp_define
+
+Find a flag to specify defines for preprocessed Fortran. Not all
+Fortran compilers use @option{-D}. Substitute @code{FC_DEFINE} with
+the result and call @var{action-if-success} (defaults to nothing) if
+successful, and @var{action-if-failure} (defaults to failing with an
+error message) if not.
+
+This macro calls @code{AC_FC_PP_SRCEXT([F])} in order to learn how to
+preprocess a @file{conftest.F} file, but restores a previously used
+Fortran source file extension afterwards again.
+
+The result of this test is cached in the @code{ac_cv_fc_pp_define}
+variable.
+ at end defmac
+
+ at defmac AC_FC_FREEFORM (@ovar{action-if-success}, @dvar{action-if-failure, @
+ AC_MSG_FAILURE})
+ at acindex{FC_FREEFORM}
+ at caindex fc_freeform
+
+Try to ensure that the Fortran compiler (@code{$FC}) allows free-format
+source code (as opposed to the older fixed-format style from Fortran
+77). If necessary, it may add some additional flags to @code{FCFLAGS}.
+
+This macro is most important if you are using the default @file{.f}
+extension, since many compilers interpret this extension as indicating
+fixed-format source unless an additional flag is supplied. If you
+specify a different extension with @code{AC_FC_SRCEXT}, such as
+ at file{.f90}, then @code{AC_FC_FREEFORM} ordinarily succeeds without
+modifying @code{FCFLAGS}. For extensions which the compiler does not
+know about, the flag set by the @code{AC_FC_SRCEXT} macro might let
+the compiler assume Fortran 77 by default, however.
+
+If @code{AC_FC_FREEFORM} succeeds in compiling free-form source, it
+calls @var{action-if-success} (defaults to nothing). If it fails, it
+calls @var{action-if-failure} (defaults to exiting with an error
+message).
+
+The result of this test, or @samp{none} or @samp{unknown}, is cached in
+the @code{ac_cv_fc_freeform} variable.
+ at end defmac
+
+ at defmac AC_FC_FIXEDFORM (@ovar{action-if-success}, @dvar{action-if-failure, @
+ AC_MSG_FAILURE})
+ at acindex{FC_FIXEDFORM}
+ at caindex fc_fixedform
+
+Try to ensure that the Fortran compiler (@code{$FC}) allows the old
+fixed-format source code (as opposed to free-format style). If
+necessary, it may add some additional flags to @code{FCFLAGS}.
+
+This macro is needed for some compilers alias names like @command{xlf95}
+which assume free-form source code by default, and in case you want to
+use fixed-form source with an extension like @file{.f90} which many
+compilers interpret as free-form by default. If you specify a different
+extension with @code{AC_FC_SRCEXT}, such as @file{.f}, then
+ at code{AC_FC_FIXEDFORM} ordinarily succeeds without modifying
+ at code{FCFLAGS}.
+
+If @code{AC_FC_FIXEDFORM} succeeds in compiling fixed-form source, it
+calls @var{action-if-success} (defaults to nothing). If it fails, it
+calls @var{action-if-failure} (defaults to exiting with an error
+message).
+
+The result of this test, or @samp{none} or @samp{unknown}, is cached in
+the @code{ac_cv_fc_fixedform} variable.
+ at end defmac
+
+ at defmac AC_FC_LINE_LENGTH (@ovar{length}, @ovar{action-if-success}, @
+ @dvar{action-if-failure, AC_MSG_FAILURE})
+ at acindex{FC_LINE_LENGTH}
+ at caindex fc_line_length
+
+Try to ensure that the Fortran compiler (@code{$FC}) accepts long source
+code lines. The @var{length} argument may be given as 80, 132, or
+unlimited, and defaults to 132. Note that line lengths above 254
+columns are not portable, and some compilers do not accept more than 132
+columns at least for fixed format source. If necessary, it may add some
+additional flags to @code{FCFLAGS}.
+
+If @code{AC_FC_LINE_LENGTH} succeeds in compiling fixed-form source, it
+calls @var{action-if-success} (defaults to nothing). If it fails, it
+calls @var{action-if-failure} (defaults to exiting with an error
+message).
+
+The result of this test, or @samp{none} or @samp{unknown}, is cached in
+the @code{ac_cv_fc_line_length} variable.
+ at end defmac
+
+ at defmac AC_FC_CHECK_BOUNDS (@ovar{action-if-success}, @
+ @dvar{action-if-failure, AC_MSG_FAILURE})
+ at acindex{FC_CHECK_BOUNDS}
+ at caindex fc_check_bounds
+
+The @code{AC_FC_CHECK_BOUNDS} macro tries to enable array bounds checking
+in the Fortran compiler. If successful, the @var{action-if-success}
+is called and any needed flags are added to @code{FCFLAGS}. Otherwise,
+ at var{action-if-failure} is called, which defaults to failing with an error
+message. The macro currently requires Fortran 90 or a newer dialect.
+
+The result of the macro is cached in the @code{ac_cv_fc_check_bounds}
+variable.
+ at end defmac
+
+ at defmac AC_F77_IMPLICIT_NONE (@ovar{action-if-success}, @
+ @dvar{action-if-failure, AC_MSG_FAILURE})
+ at defmacx AC_FC_IMPLICIT_NONE (@ovar{action-if-success}, @
+ @dvar{action-if-failure, AC_MSG_FAILURE})
+ at acindex{F77_IMPLICIT_NONE}
+ at acindex{FC_IMPLICIT_NONE}
+ at caindex f77_implicit_none
+ at caindex fc_implicit_none
+
+Try to disallow implicit declarations in the Fortran compiler. If
+successful, @var{action-if-success} is called and any needed flags
+are added to @code{FFLAGS} or @code{FCFLAGS}, respectively. Otherwise,
+ at var{action-if-failure} is called, which defaults to failing with an error
+message.
+
+The result of these macros are cached in the
+ at code{ac_cv_f77_implicit_none} and @code{ac_cv_fc_implicit_none}
+variables, respectively.
+ at end defmac
+
+ at defmac AC_FC_MODULE_EXTENSION
+ at acindex{FC_MODULE_EXTENSION}
+ at caindex fc_module_ext
+ at ovindex FC_MODEXT
+
+Find the Fortran 90 module file name extension. Most Fortran 90
+compilers store module information in files separate from the object
+files. The module files are usually named after the name of the module
+rather than the source file name, with characters possibly turned to
+upper case, plus an extension, often @file{.mod}.
+
+Not all compilers use module files at all, or by default. The Cray
+Fortran compiler requires @option{-e m} in order to store and search
+module information in @file{.mod} files rather than in object files.
+Likewise, the Fujitsu Fortran compilers uses the @option{-Am} option to
+indicate how module information is stored.
+
+The @code{AC_FC_MODULE_EXTENSION} macro computes the module extension
+without the leading dot, and stores that in the @code{FC_MODEXT}
+variable. If the compiler does not produce module files, or the
+extension cannot be determined, @code{FC_MODEXT} is empty. Typically,
+the result of this macro may be used in cleanup @command{make} rules as
+follows:
+
+ at example
+clean-modules:
+ -test -z "$(FC_MODEXT)" || rm -f *.$(FC_MODEXT)
+ at end example
+
+The extension, or @samp{unknown}, is cached in the
+ at code{ac_cv_fc_module_ext} variable.
+ at end defmac
+
+ at defmac AC_FC_MODULE_FLAG (@ovar{action-if-success}, @
+ @dvar{action-if-failure, AC_MSG_FAILURE})
+ at acindex{FC_MODULE_FLAG}
+ at caindex fc_module_flag
+ at ovindex FC_MODINC
+ at ovindex ac_empty
+
+Find the compiler flag to include Fortran 90 module information from
+another directory, and store that in the @code{FC_MODINC} variable.
+Call @var{action-if-success} (defaults to nothing) if successful, and
+set @code{FC_MODINC} to empty and call @var{action-if-failure} (defaults
+to exiting with an error message) if not.
+
+Most Fortran 90 compilers provide a way to specify module directories.
+Some have separate flags for the directory to write module files to,
+and directories to search them in, whereas others only allow writing to
+the current directory or to the first directory specified in the include
+path. Further, with some compilers, the module search path and the
+preprocessor search path can only be modified with the same flag. Thus,
+for portability, write module files to the current directory only and
+list that as first directory in the search path.
+
+There may be no whitespace between @code{FC_MODINC} and the following
+directory name, but @code{FC_MODINC} may contain trailing white space.
+For example, if you use Automake and would like to search @file{../lib}
+for module files, you can use the following:
+
+ at example
+AM_FCFLAGS = $(FC_MODINC). $(FC_MODINC)../lib
+ at end example
+
+Inside @command{configure} tests, you can use:
+
+ at example
+if test -n "$FC_MODINC"; then
+ FCFLAGS="$FCFLAGS $FC_MODINC. $FC_MODINC../lib"
+fi
+ at end example
+
+The flag is cached in the @code{ac_cv_fc_module_flag} variable.
+The substituted value of @code{FC_MODINC} may refer to the
+ at code{ac_empty} dummy placeholder empty variable, to avoid losing
+the significant trailing whitespace in a @file{Makefile}.
+ at end defmac
+
+ at defmac AC_FC_MODULE_OUTPUT_FLAG (@ovar{action-if-success}, @
+ @dvar{action-if-failure, AC_MSG_FAILURE})
+ at acindex{FC_MODULE_OUTPUT_FLAG}
+ at caindex fc_module_output_flag
+ at ovindex FC_MODOUT
+
+Find the compiler flag to write Fortran 90 module information to
+another directory, and store that in the @code{FC_MODOUT} variable.
+Call @var{action-if-success} (defaults to nothing) if successful, and
+set @code{FC_MODOUT} to empty and call @var{action-if-failure} (defaults
+to exiting with an error message) if not.
+
+Not all Fortran 90 compilers write module files, and of those that do,
+not all allow writing to a directory other than the current one, nor
+do all have separate flags for writing and reading; see the description
+of @code{AC_FC_MODULE_FLAG} above. If you need to be able to write to
+another directory, for maximum portability use @code{FC_MODOUT} before
+any @code{FC_MODINC} and include both the current directory and the one
+you write to in the search path:
+
+ at example
+AM_FCFLAGS = $(FC_MODOUT)../mod $(FC_MODINC)../mod $(FC_MODINC). @dots{}
+ at end example
+
+The flag is cached in the @code{ac_cv_fc_module_output_flag} variable.
+The substituted value of @code{FC_MODOUT} may refer to the
+ at code{ac_empty} dummy placeholder empty variable, to avoid losing
+the significant trailing whitespace in a @file{Makefile}.
+ at end defmac
+
+
+ at node Go Compiler
+ at subsection Go Compiler Characteristics
+ at cindex Go
+
+Autoconf provides basic support for the Go programming language when
+using the @code{gccgo} compiler (there is currently no support for the
+ at code{6g} and @code{8g} compilers).
+
+ at defmac AC_PROG_GO (@ovar{compiler-search-list})
+Find the Go compiler to use. Check whether the environment variable
+ at code{GOC} is set; if so, then set output variable @code{GOC} to its
+value.
+
+Otherwise, if the macro is invoked without an argument, then search for
+a Go compiler named @code{gccgo}. If it is not found, then as a last
+resort set @code{GOC} to @code{gccgo}.
+
+This macro may be invoked with an optional first argument which, if
+specified, must be a blank-separated list of Go compilers to search for.
+
+If output variable @code{GOFLAGS} was not already set, set it to
+ at option{-g -O2}. If your package does not like this default,
+ at code{GOFLAGS} may be set before @code{AC_PROG_GO}.
+ at end defmac
+
+
+ at node System Services
+ at section System Services
+
+The following macros check for operating system services or capabilities.
+
+ at anchor{AC_PATH_X}
+ at defmac AC_PATH_X
+ at acindex{PATH_X}
+ at evindex XMKMF
+ at cindex X Window System
+Try to locate the X Window System include files and libraries. If the
+user gave the command line options @option{--x-includes=@var{dir}} and
+ at option{--x-libraries=@var{dir}}, use those directories.
+
+If either or both were not given, get the missing values by running
+ at code{xmkmf} (or an executable pointed to by the @code{XMKMF}
+environment variable) on a trivial @file{Imakefile} and examining the
+makefile that it produces. Setting @code{XMKMF} to @samp{false}
+disables this method.
+
+If this method fails to find the X Window System, @command{configure}
+looks for the files in several directories where they often reside.
+If either method is successful, set the shell variables
+ at code{x_includes} and @code{x_libraries} to their locations, unless they
+are in directories the compiler searches by default.
+
+If both methods fail, or the user gave the command line option
+ at option{--without-x}, set the shell variable @code{no_x} to @samp{yes};
+otherwise set it to the empty string.
+ at end defmac
+
+ at anchor{AC_PATH_XTRA}
+ at defmac AC_PATH_XTRA
+ at acindex{PATH_XTRA}
+ at ovindex X_CFLAGS
+ at ovindex X_LIBS
+ at ovindex X_EXTRA_LIBS
+ at ovindex X_PRE_LIBS
+ at cvindex X_DISPLAY_MISSING
+An enhanced version of @code{AC_PATH_X}. It adds the C compiler flags
+that X needs to output variable @code{X_CFLAGS}, and the X linker flags
+to @code{X_LIBS}. Define @code{X_DISPLAY_MISSING} if X is not
+available.
+
+This macro also checks for special libraries that some systems need in
+order to compile X programs. It adds any that the system needs to
+output variable @code{X_EXTRA_LIBS}. And it checks for special X11R6
+libraries that need to be linked with before @option{-lX11}, and adds
+any found to the output variable @code{X_PRE_LIBS}.
+
+ at c This is an incomplete kludge. Make a real way to do it.
+ at c If you need to check for other X functions or libraries yourself, then
+ at c after calling this macro, add the contents of @code{X_EXTRA_LIBS} to
+ at c @code{LIBS} temporarily, like this: (FIXME - add example)
+ at end defmac
+
+ at anchor{AC_SYS_INTERPRETER}
+ at defmac AC_SYS_INTERPRETER
+ at acindex{SYS_INTERPRETER}
+Check whether the system supports starting scripts with a line of the
+form @samp{#!/bin/sh} to select the interpreter to use for the script.
+After running this macro, shell code in @file{configure.ac} can check
+the shell variable @code{interpval}; it is set to @samp{yes}
+if the system supports @samp{#!}, @samp{no} if not.
+ at end defmac
+
+ at defmac AC_SYS_LARGEFILE
+ at acindex{SYS_LARGEFILE}
+ at cvindex _FILE_OFFSET_BITS
+ at cvindex _LARGE_FILES
+ at ovindex CC
+ at cindex Large file support
+ at cindex LFS
+Arrange for 64-bit file offsets, known as
+ at uref{http://@/www.unix-systems@/.org/@/version2/@/whatsnew/@/lfs20mar.html,
+large-file support}. On some hosts, one must use special compiler
+options to build programs that can access large files. Append any such
+options to the output variable @code{CC}. Define
+ at code{_FILE_OFFSET_BITS} and @code{_LARGE_FILES} if necessary.
+
+Large-file support can be disabled by configuring with the
+ at option{--disable-largefile} option.
+
+If you use this macro, check that your program works even when
+ at code{off_t} is wider than @code{long int}, since this is common when
+large-file support is enabled. For example, it is not correct to print
+an arbitrary @code{off_t} value @code{X} with @code{printf ("%ld",
+(long int) X)}.
+
+The LFS introduced the @code{fseeko} and @code{ftello} functions to
+replace their C counterparts @code{fseek} and @code{ftell} that do not
+use @code{off_t}. Take care to use @code{AC_FUNC_FSEEKO} to make their
+prototypes available when using them and large-file support is
+enabled.
+ at end defmac
+
+ at anchor{AC_SYS_LONG_FILE_NAMES}
+ at defmac AC_SYS_LONG_FILE_NAMES
+ at acindex{SYS_LONG_FILE_NAMES}
+ at cvindex HAVE_LONG_FILE_NAMES
+If the system supports file names longer than 14 characters, define
+ at code{HAVE_LONG_FILE_NAMES}.
+ at end defmac
+
+ at defmac AC_SYS_POSIX_TERMIOS
+ at acindex{SYS_POSIX_TERMIOS}
+ at cindex Posix termios headers
+ at cindex termios Posix headers
+ at caindex sys_posix_termios
+Check to see if the Posix termios headers and functions are available on the
+system. If so, set the shell variable @code{ac_cv_sys_posix_termios} to
+ at samp{yes}. If not, set the variable to @samp{no}.
+ at end defmac
+
+ at node Posix Variants
+ at section Posix Variants
+
+The following macro makes it possible to use features of Posix that are
+extensions to C, as well as platform extensions not defined by Posix.
+
+ at anchor{AC_USE_SYSTEM_EXTENSIONS}
+ at defmac AC_USE_SYSTEM_EXTENSIONS
+ at acindex{USE_SYSTEM_EXTENSIONS}
+ at cvindex _ALL_SOURCE
+ at cvindex _GNU_SOURCE
+ at cvindex _MINIX
+ at cvindex _POSIX_1_SOURCE
+ at cvindex _POSIX_PTHREAD_SEMANTICS
+ at cvindex _POSIX_SOURCE
+ at cvindex _TANDEM_SOURCE
+ at cvindex __EXTENSIONS__
+This macro was introduced in Autoconf 2.60. If possible, enable
+extensions to C or Posix on hosts that normally disable the extensions,
+typically due to standards-conformance namespace issues. This should be
+called before any macros that run the C compiler. The following
+preprocessor macros are defined where appropriate:
+
+ at table @code
+ at item _GNU_SOURCE
+Enable extensions on GNU/Linux.
+ at item __EXTENSIONS__
+Enable general extensions on Solaris.
+ at item _POSIX_PTHREAD_SEMANTICS
+Enable threading extensions on Solaris.
+ at item _TANDEM_SOURCE
+Enable extensions for the HP NonStop platform.
+ at item _ALL_SOURCE
+Enable extensions for AIX 3, and for Interix.
+ at item _POSIX_SOURCE
+Enable Posix functions for Minix.
+ at item _POSIX_1_SOURCE
+Enable additional Posix functions for Minix.
+ at item _MINIX
+Identify Minix platform. This particular preprocessor macro is
+obsolescent, and may be removed in a future release of Autoconf.
+ at end table
+ at end defmac
+
+
+ at node Erlang Libraries
+ at section Erlang Libraries
+ at cindex Erlang, Library, checking
+
+The following macros check for an installation of Erlang/OTP, and for the
+presence of certain Erlang libraries. All those macros require the
+configuration of an Erlang interpreter and an Erlang compiler
+(@pxref{Erlang Compiler and Interpreter}).
+
+ at defmac AC_ERLANG_SUBST_ERTS_VER
+ at acindex{ERLANG_SUBST_ERTS_VER}
+ at ovindex ERLANG_ERTS_VER
+Set the output variable @code{ERLANG_ERTS_VER} to the version of the
+Erlang runtime system (as returned by Erlang's
+ at code{erlang:system_info(version)} function). The result of this test
+is cached if caching is enabled when running @command{configure}. The
+ at code{ERLANG_ERTS_VER} variable is not intended to be used for testing
+for features of specific ERTS versions, but to be used for substituting
+the ERTS version in Erlang/OTP release resource files (@code{.rel}
+files), as shown below.
+ at end defmac
+
+ at defmac AC_ERLANG_SUBST_ROOT_DIR
+ at acindex{ERLANG_SUBST_ROOT_DIR}
+ at ovindex ERLANG_ROOT_DIR
+Set the output variable @code{ERLANG_ROOT_DIR} to the path to the base
+directory in which Erlang/OTP is installed (as returned by Erlang's
+ at code{code:root_dir/0} function). The result of this test is cached if
+caching is enabled when running @command{configure}.
+ at end defmac
+
+ at defmac AC_ERLANG_SUBST_LIB_DIR
+ at acindex{ERLANG_SUBST_LIB_DIR}
+ at ovindex ERLANG_LIB_DIR
+Set the output variable @code{ERLANG_LIB_DIR} to the path of the library
+directory of Erlang/OTP (as returned by Erlang's
+ at code{code:lib_dir/0} function), which subdirectories each contain an installed
+Erlang/OTP library. The result of this test is cached if caching is enabled
+when running @command{configure}.
+ at end defmac
+
+ at defmac AC_ERLANG_CHECK_LIB (@var{library}, @ovar{action-if-found}, @
+ @ovar{action-if-not-found})
+ at acindex{ERLANG_CHECK_LIB}
+ at ovindex ERLANG_LIB_DIR_ at var{library}
+ at ovindex ERLANG_LIB_VER_ at var{library}
+Test whether the Erlang/OTP library @var{library} is installed by
+calling Erlang's @code{code:lib_dir/1} function. The result of this
+test is cached if caching is enabled when running @command{configure}.
+ at var{action-if-found} is a list of shell commands to run if the library
+is installed; @var{action-if-not-found} is a list of shell commands to
+run if it is not. Additionally, if the library is installed, the output
+variable @samp{ERLANG_LIB_DIR_ at var{library}} is set to the path to the
+library installation directory, and the output variable
+ at samp{ERLANG_LIB_VER_ at var{library}} is set to the version number that is
+part of the subdirectory name, if it is in the standard form
+(@code{@var{library}- at var{version}}). If the directory name does not
+have a version part, @samp{ERLANG_LIB_VER_ at var{library}} is set to the
+empty string. If the library is not installed,
+ at samp{ERLANG_LIB_DIR_ at var{library}} and
+ at samp{ERLANG_LIB_VER_ at var{library}} are set to @code{"not found"}. For
+example, to check if library @code{stdlib} is installed:
+
+ at example
+AC_ERLANG_CHECK_LIB([stdlib],
+ [echo "stdlib version \"$ERLANG_LIB_VER_stdlib\""
+ echo "is installed in \"$ERLANG_LIB_DIR_stdlib\""],
+ [AC_MSG_ERROR([stdlib was not found!])])
+ at end example
+
+The @samp{ERLANG_LIB_VER_ at var{library}} variables (set by
+ at code{AC_ERLANG_CHECK_LIB}) and the @code{ERLANG_ERTS_VER} variable (set
+by @code{AC_ERLANG_SUBST_ERTS_VER}) are not intended to be used for
+testing for features of specific versions of libraries or of the Erlang
+runtime system. Those variables are intended to be substituted in
+Erlang release resource files (@code{.rel} files). For instance, to
+generate a @file{example.rel} file for an application depending on the
+ at code{stdlib} library, @file{configure.ac} could contain:
+
+ at example
+AC_ERLANG_SUBST_ERTS_VER
+AC_ERLANG_CHECK_LIB([stdlib],
+ [],
+ [AC_MSG_ERROR([stdlib was not found!])])
+AC_CONFIG_FILES([example.rel])
+ at end example
+
+ at noindent
+The @file{example.rel.in} file used to generate @file{example.rel}
+should contain:
+
+ at example
+@{release,
+ @{"@@PACKAGE@@", "@@VERSION@@"@},
+ @{erts, "@@ERLANG_ERTS_VER@@"@},
+ [@{stdlib, "@@ERLANG_LIB_VER_stdlib@@"@},
+ @{@@PACKAGE@@, "@@VERSION@@"@}]@}.
+ at end example
+ at end defmac
+
+In addition to the above macros, which test installed Erlang libraries, the
+following macros determine the paths to the directories into which newly built
+Erlang libraries are to be installed:
+
+ at defmac AC_ERLANG_SUBST_INSTALL_LIB_DIR
+ at acindex{ERLANG_SUBST_INSTALL_LIB_DIR}
+ at ovindex ERLANG_INSTALL_LIB_DIR
+
+Set the @code{ERLANG_INSTALL_LIB_DIR} output variable to the directory into
+which every built Erlang library should be installed in a separate
+subdirectory.
+If this variable is not set in the environment when @command{configure} runs,
+its default value is @code{$@{libdir@}/erlang/lib}.
+ at end defmac
+
+ at defmac AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR (@var{library}, @var{version})
+ at acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR}
+ at ovindex ERLANG_INSTALL_LIB_DIR_ at var{library}
+
+Set the @samp{ERLANG_INSTALL_LIB_DIR_ at var{library}} output variable to the
+directory into which the built Erlang library @var{library} version
+ at var{version} should be installed. If this variable is not set in the
+environment when @command{configure} runs, its default value is
+ at samp{$ERLANG_INSTALL_LIB_DIR/@var{library}- at var{version}}, the value of the
+ at code{ERLANG_INSTALL_LIB_DIR} variable being set by the
+ at code{AC_ERLANG_SUBST_INSTALL_LIB_DIR} macro.
+ at end defmac
+
+
+
+
+
+ at c ========================================================= Writing Tests
+
+ at node Writing Tests
+ at chapter Writing Tests
+
+If the existing feature tests don't do something you need, you have to
+write new ones. These macros are the building blocks. They provide
+ways for other macros to check whether various kinds of features are
+available and report the results.
+
+This chapter contains some suggestions and some of the reasons why the
+existing tests are written the way they are. You can also learn a lot
+about how to write Autoconf tests by looking at the existing ones. If
+something goes wrong in one or more of the Autoconf tests, this
+information can help you understand the assumptions behind them, which
+might help you figure out how to best solve the problem.
+
+These macros check the output of the compiler system of the current
+language (@pxref{Language Choice}). They do not cache the results of
+their tests for future use (@pxref{Caching Results}), because they don't
+know enough about the information they are checking for to generate a
+cache variable name. They also do not print any messages, for the same
+reason. The checks for particular kinds of features call these macros
+and do cache their results and print messages about what they're
+checking for.
+
+When you write a feature test that could be applicable to more than one
+software package, the best thing to do is encapsulate it in a new macro.
+ at xref{Writing Autoconf Macros}, for how to do that.
+
+ at menu
+* 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
+ at end menu
+
+ at node Language Choice
+ at section Language Choice
+ at cindex Language
+
+Autoconf-generated @command{configure} scripts check for the C compiler and
+its features by default. Packages that use other programming languages
+(maybe more than one, e.g., C and C++) need to test features of the
+compilers for the respective languages. The following macros determine
+which programming language is used in the subsequent tests in
+ at file{configure.ac}.
+
+ at anchor{AC_LANG}
+ at defmac AC_LANG (@var{language})
+ at acindex{LANG}
+Do compilation tests using the compiler, preprocessor, and file
+extensions for the specified @var{language}.
+
+Supported languages are:
+
+ at table @samp
+ at item C
+Do compilation tests using @code{CC} and @code{CPP} and use extension
+ at file{.c} for test programs. Use compilation flags: @code{CPPFLAGS} with
+ at code{CPP}, and both @code{CPPFLAGS} and @code{CFLAGS} with @code{CC}.
+
+ at item C++
+Do compilation tests using @code{CXX} and @code{CXXCPP} and use
+extension @file{.C} for test programs. Use compilation flags:
+ at code{CPPFLAGS} with @code{CXXCPP}, and both @code{CPPFLAGS} and
+ at code{CXXFLAGS} with @code{CXX}.
+
+ at item Fortran 77
+Do compilation tests using @code{F77} and use extension @file{.f} for
+test programs. Use compilation flags: @code{FFLAGS}.
+
+ at item Fortran
+Do compilation tests using @code{FC} and use extension @file{.f} (or
+whatever has been set by @code{AC_FC_SRCEXT}) for test programs. Use
+compilation flags: @code{FCFLAGS}.
+
+ at item Erlang
+ at ovindex ERLC
+ at ovindex ERL
+ at ovindex ERLCFLAGS
+Compile and execute tests using @code{ERLC} and @code{ERL} and use extension
+ at file{.erl} for test Erlang modules. Use compilation flags: @code{ERLCFLAGS}.
+
+ at item Objective C
+Do compilation tests using @code{OBJC} and @code{OBJCPP} and use
+extension @file{.m} for test programs. Use compilation flags:
+ at code{CPPFLAGS} with @code{OBJCPP}, and both @code{CPPFLAGS} and
+ at code{OBJCFLAGS} with @code{OBJC}.
+
+ at item Objective C++
+Do compilation tests using @code{OBJCXX} and @code{OBJCXXCPP} and use
+extension @file{.mm} for test programs. Use compilation flags:
+ at code{CPPFLAGS} with @code{OBJCXXCPP}, and both @code{CPPFLAGS} and
+ at code{OBJCXXFLAGS} with @code{OBJCXX}.
+
+ at item Go
+Do compilation tests using @code{GOC} and use extension @file{.go} for
+test programs. Use compilation flags @code{GOFLAGS}.
+ at end table
+ at end defmac
+
+ at anchor{AC_LANG_PUSH}
+ at defmac AC_LANG_PUSH (@var{language})
+ at acindex{LANG_PUSH}
+Remember the current language (as set by @code{AC_LANG}) on a stack, and
+then select the @var{language}. Use this macro and @code{AC_LANG_POP}
+in macros that need to temporarily switch to a particular language.
+ at end defmac
+
+ at defmac AC_LANG_POP (@ovar{language})
+ at acindex{LANG_POP}
+Select the language that is saved on the top of the stack, as set by
+ at code{AC_LANG_PUSH}, and remove it from the stack.
+
+If given, @var{language} specifies the language we just @emph{quit}. It
+is a good idea to specify it when it's known (which should be the
+case at dots{}), since Autoconf detects inconsistencies.
+
+ at example
+AC_LANG_PUSH([Fortran 77])
+# Perform some tests on Fortran 77.
+# @dots{}
+AC_LANG_POP([Fortran 77])
+ at end example
+ at end defmac
+
+ at defmac AC_LANG_ASSERT (@var{language})
+ at acindex{LANG_ASSERT}
+Check statically that the current language is @var{language}.
+You should use this in your language specific macros
+to avoid that they be called with an inappropriate language.
+
+This macro runs only at @command{autoconf} time, and incurs no cost at
+ at command{configure} time. Sadly enough and because Autoconf is a two
+layer language @footnote{Because M4 is not aware of Sh code,
+especially conditionals, some optimizations that look nice statically
+may produce incorrect results at runtime.}, the macros
+ at code{AC_LANG_PUSH} and @code{AC_LANG_POP} cannot be ``optimizing'',
+therefore as much as possible you ought to avoid using them to wrap
+your code, rather, require from the user to run the macro with a
+correct current language, and check it with @code{AC_LANG_ASSERT}.
+And anyway, that may help the user understand she is running a Fortran
+macro while expecting a result about her Fortran 77 compiler at enddots{}
+ at end defmac
+
+
+ at defmac AC_REQUIRE_CPP
+ at acindex{REQUIRE_CPP}
+Ensure that whichever preprocessor would currently be used for tests has
+been found. Calls @code{AC_REQUIRE} (@pxref{Prerequisite Macros}) with an
+argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP},
+depending on which language is current.
+ at end defmac
+
+
+ at node Writing Test Programs
+ at section Writing Test Programs
+
+Autoconf tests follow a common scheme: feed some program with some
+input, and most of the time, feed a compiler with some source file.
+This section is dedicated to these source samples.
+
+ at menu
+* Guidelines:: General rules for writing test programs
+* Test Functions:: Avoiding pitfalls in test programs
+* Generating Sources:: Source program boilerplate
+ at end menu
+
+ at node Guidelines
+ at subsection Guidelines for Test Programs
+
+The most important rule to follow when writing testing samples is:
+
+ at center @emph{Look for realism.}
+
+This motto means that testing samples must be written with the same
+strictness as real programs are written. In particular, you should
+avoid ``shortcuts'' and simplifications.
+
+Don't just play with the preprocessor if you want to prepare a
+compilation. For instance, using @command{cpp} to check whether a header is
+functional might let your @command{configure} accept a header which
+causes some @emph{compiler} error. Do not hesitate to check a header with
+other headers included before, especially required headers.
+
+Make sure the symbols you use are properly defined, i.e., refrain from
+simply declaring a function yourself instead of including the proper
+header.
+
+Test programs should not write to standard output. They
+should exit with status 0 if the test succeeds, and with status 1
+otherwise, so that success
+can be distinguished easily from a core dump or other failure;
+segmentation violations and other failures produce a nonzero exit
+status. Unless you arrange for @code{exit} to be declared, test
+programs should @code{return}, not @code{exit}, from @code{main},
+because on many systems @code{exit} is not declared by default.
+
+Test programs can use @code{#if} or @code{#ifdef} to check the values of
+preprocessor macros defined by tests that have already run. For
+example, if you call @code{AC_HEADER_STDBOOL}, then later on in
+ at file{configure.ac} you can have a test program that includes
+ at file{stdbool.h} conditionally:
+
+ at example
+ at group
+#ifdef HAVE_STDBOOL_H
+# include <stdbool.h>
+#endif
+ at end group
+ at end example
+
+Both @code{#if HAVE_STDBOOL_H} and @code{#ifdef HAVE_STDBOOL_H} will
+work with any standard C compiler. Some developers prefer @code{#if}
+because it is easier to read, while others prefer @code{#ifdef} because
+it avoids diagnostics with picky compilers like GCC with the
+ at option{-Wundef} option.
+
+If a test program needs to use or create a data file, give it a name
+that starts with @file{conftest}, such as @file{conftest.data}. The
+ at command{configure} script cleans up by running @samp{rm -f -r conftest*}
+after running test programs and if the script is interrupted.
+
+ at node Test Functions
+ at subsection Test Functions
+
+These days it's safe to assume support for function prototypes
+(introduced in C89).
+
+Functions that test programs declare should also be conditionalized for
+C++, which requires @samp{extern "C"} prototypes. Make sure to not
+include any header files containing clashing prototypes.
+
+ at example
+#ifdef __cplusplus
+extern "C"
+#endif
+void *valloc (size_t);
+ at end example
+
+If a test program calls a function with invalid parameters (just to see
+whether it exists), organize the program to ensure that it never invokes
+that function. You can do this by calling it in another function that is
+never invoked. You can't do it by putting it after a call to
+ at code{exit}, because GCC version 2 knows that @code{exit}
+never returns
+and optimizes out any code that follows it in the same block.
+
+If you include any header files, be sure to call the functions
+relevant to them with the correct number of arguments, even if they are
+just 0, to avoid compilation errors due to prototypes. GCC
+version 2
+has internal prototypes for several functions that it automatically
+inlines; for example, @code{memcpy}. To avoid errors when checking for
+them, either pass them the correct number of arguments or redeclare them
+with a different return type (such as @code{char}).
+
+
+ at node Generating Sources
+ at subsection Generating Sources
+
+Autoconf provides a set of macros that can be used to generate test
+source files. They are written to be language generic, i.e., they
+actually depend on the current language (@pxref{Language Choice}) to
+``format'' the output properly.
+
+
+ at defmac AC_LANG_CONFTEST (@var{source})
+ at acindex{LANG_CONFTEST}
+Save the @var{source} text in the current test source file:
+ at file{conftest. at var{extension}} where the @var{extension} depends on the
+current language. As of Autoconf 2.63b, the source file also contains
+the results of all of the @code{AC_DEFINE} performed so far.
+
+Note that the @var{source} is evaluated exactly once, like regular
+Autoconf macro arguments, and therefore (i) you may pass a macro
+invocation, (ii) if not, be sure to double quote if needed.
+
+This macro issues a warning during @command{autoconf} processing if
+ at var{source} does not include an expansion of the macro
+ at code{AC_LANG_DEFINES_PROVIDED} (note that both @code{AC_LANG_SOURCE} and
+ at code{AC_LANG_PROGRAM} call this macro, and thus avoid the warning).
+
+This macro is seldom called directly, but is used under the hood by more
+common macros such as @code{AC_COMPILE_IFELSE} and @code{AC_RUN_IFELSE}.
+ at end defmac
+
+ at defmac AC_LANG_DEFINES_PROVIDED
+ at acindex{LANG_DEFINES_PROVIDED}
+This macro is called as a witness that the file
+ at file{conftest. at var{extension}} appropriate for the current language is
+complete, including all previously determined results from
+ at code{AC_DEFINE}. This macro is seldom called directly, but exists if
+you have a compelling reason to write a conftest file without using
+ at code{AC_LANG_SOURCE}, yet still want to avoid a syntax warning from
+ at code{AC_LANG_CONFTEST}.
+ at end defmac
+
+ at defmac AC_LANG_SOURCE (@var{source})
+ at acindex{LANG_SOURCE}
+Expands into the @var{source}, with the definition of
+all the @code{AC_DEFINE} performed so far. This macro includes an
+expansion of @code{AC_LANG_DEFINES_PROVIDED}.
+
+In many cases, you may find it more convenient to use the wrapper
+ at code{AC_LANG_PROGRAM}.
+ at end defmac
+
+For instance, executing (observe the double quotation!):
+
+ at example
+ at c If you change this example, adjust tests/compile.at:AC_LANG_SOURCE example.
+AC_INIT([Hello], [1.0], [bug-hello@@example.org], [],
+ [http://www.example.org/])
+AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
+ [Greetings string.])
+AC_LANG([C])
+AC_LANG_CONFTEST(
+ [AC_LANG_SOURCE([[const char hw[] = "Hello, World\n";]])])
+gcc -E -dD conftest.c
+ at end example
+
+ at noindent
+on a system with @command{gcc} installed, results in:
+
+ at example
+ at c If you change this example, adjust tests/compile.at:AC_LANG_SOURCE example.
+ at dots{}
+# 1 "conftest.c"
+
+#define PACKAGE_NAME "Hello"
+#define PACKAGE_TARNAME "hello"
+#define PACKAGE_VERSION "1.0"
+#define PACKAGE_STRING "Hello 1.0"
+#define PACKAGE_BUGREPORT "bug-hello@@example.org"
+#define PACKAGE_URL "http://www.example.org/"
+#define HELLO_WORLD "Hello, World\n"
+
+const char hw[] = "Hello, World\n";
+ at end example
+
+When the test language is Fortran, Erlang, or Go, the @code{AC_DEFINE}
+definitions are not automatically translated into constants in the
+source code by this macro.
+
+ at defmac AC_LANG_PROGRAM (@var{prologue}, @var{body})
+ at acindex{LANG_PROGRAM}
+Expands into a source file which consists of the @var{prologue}, and
+then @var{body} as body of the main function (e.g., @code{main} in
+C). Since it uses @code{AC_LANG_SOURCE}, the features of the latter are
+available.
+ at end defmac
+
+For instance:
+
+ at example
+ at c If you change this example, adjust tests/compile.at:AC_LANG_PROGRAM example.
+AC_INIT([Hello], [1.0], [bug-hello@@example.org], [],
+ [http://www.example.org/])
+AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
+ [Greetings string.])
+AC_LANG_CONFTEST(
+[AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
+ [[fputs (hw, stdout);]])])
+gcc -E -dD conftest.c
+ at end example
+
+ at noindent
+on a system with @command{gcc} installed, results in:
+
+ at example
+ at c If you change this example, adjust tests/compile.at:AC_LANG_PROGRAM example.
+ at dots{}
+# 1 "conftest.c"
+
+#define PACKAGE_NAME "Hello"
+#define PACKAGE_TARNAME "hello"
+#define PACKAGE_VERSION "1.0"
+#define PACKAGE_STRING "Hello 1.0"
+#define PACKAGE_BUGREPORT "bug-hello@@example.org"
+#define PACKAGE_URL "http://www.example.org/"
+#define HELLO_WORLD "Hello, World\n"
+
+const char hw[] = "Hello, World\n";
+int
+main ()
+@{
+fputs (hw, stdout);
+ ;
+ return 0;
+@}
+ at end example
+
+In Erlang tests, the created source file is that of an Erlang module called
+ at code{conftest} (@file{conftest.erl}). This module defines and exports
+at least
+one @code{start/0} function, which is called to perform the test. The
+ at var{prologue} is optional code that is inserted between the module header and
+the @code{start/0} function definition. @var{body} is the body of the
+ at code{start/0} function without the final period (@pxref{Runtime}, about
+constraints on this function's behavior).
+
+For instance:
+
+ at example
+AC_INIT([Hello], [1.0], [bug-hello@@example.org])
+AC_LANG(Erlang)
+AC_LANG_CONFTEST(
+[AC_LANG_PROGRAM([[-define(HELLO_WORLD, "Hello, world!").]],
+ [[io:format("~s~n", [?HELLO_WORLD])]])])
+cat conftest.erl
+ at end example
+
+ at noindent
+results in:
+
+ at example
+-module(conftest).
+-export([start/0]).
+-define(HELLO_WORLD, "Hello, world!").
+start() ->
+io:format("~s~n", [?HELLO_WORLD])
+.
+ at end example
+
+ at defmac AC_LANG_CALL (@var{prologue}, @var{function})
+ at acindex{LANG_CALL}
+Expands into a source file which consists of the @var{prologue}, and
+then a call to the @var{function} as body of the main function (e.g.,
+ at code{main} in C). Since it uses @code{AC_LANG_PROGRAM}, the feature
+of the latter are available.
+
+This function will probably be replaced in the future by a version
+which would enable specifying the arguments. The use of this macro is
+not encouraged, as it violates strongly the typing system.
+
+This macro cannot be used for Erlang tests.
+ at end defmac
+
+ at defmac AC_LANG_FUNC_LINK_TRY (@var{function})
+ at acindex{LANG_FUNC_LINK_TRY}
+Expands into a source file which uses the @var{function} in the body of
+the main function (e.g., @code{main} in C). Since it uses
+ at code{AC_LANG_PROGRAM}, the features of the latter are available.
+
+As @code{AC_LANG_CALL}, this macro is documented only for completeness.
+It is considered to be severely broken, and in the future will be
+removed in favor of actual function calls (with properly typed
+arguments).
+
+This macro cannot be used for Erlang tests.
+ at end defmac
+
+ at node Running the Preprocessor
+ at section Running the Preprocessor
+
+Sometimes one might need to run the preprocessor on some source file.
+ at emph{Usually it is a bad idea}, as you typically need to @emph{compile}
+your project, not merely run the preprocessor on it; therefore you
+certainly want to run the compiler, not the preprocessor. Resist the
+temptation of following the easiest path.
+
+Nevertheless, if you need to run the preprocessor, then use
+ at code{AC_PREPROC_IFELSE}.
+
+The macros described in this section cannot be used for tests in Erlang,
+Fortran, or Go, since those languages require no preprocessor.
+
+ at anchor{AC_PREPROC_IFELSE}
+ at defmac AC_PREPROC_IFELSE (@var{input}, @ovar{action-if-true}, @
+ @ovar{action-if-false})
+ at acindex{PREPROC_IFELSE}
+Run the preprocessor of the current language (@pxref{Language Choice})
+on the @var{input}, run the shell commands @var{action-if-true} on
+success, @var{action-if-false} otherwise. The @var{input} can be made
+by @code{AC_LANG_PROGRAM} and friends.
+
+This macro uses @code{CPPFLAGS}, but not @code{CFLAGS}, because
+ at option{-g}, @option{-O}, etc.@: are not valid options to many C
+preprocessors.
+
+It is customary to report unexpected failures with
+ at code{AC_MSG_FAILURE}. If needed, @var{action-if-true} can further access
+the preprocessed output in the file @file{conftest.i}.
+ at end defmac
+
+For instance:
+
+ at example
+AC_INIT([Hello], [1.0], [bug-hello@@example.org])
+AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
+ [Greetings string.])
+AC_PREPROC_IFELSE(
+ [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
+ [[fputs (hw, stdout);]])],
+ [AC_MSG_RESULT([OK])],
+ [AC_MSG_FAILURE([unexpected preprocessor failure])])
+ at end example
+
+ at noindent
+results in:
+
+ at example
+checking for gcc... gcc
+checking for C compiler default output file name... a.out
+checking whether the C compiler works... yes
+checking whether we are cross compiling... no
+checking for suffix of executables...
+checking for suffix of object files... o
+checking whether we are using the GNU C compiler... yes
+checking whether gcc accepts -g... yes
+checking for gcc option to accept ISO C89... none needed
+checking how to run the C preprocessor... gcc -E
+OK
+ at end example
+
+ at sp 1
+
+The macro @code{AC_TRY_CPP} (@pxref{Obsolete Macros}) used to play the
+role of @code{AC_PREPROC_IFELSE}, but double quotes its argument, making
+it impossible to use it to elaborate sources. You are encouraged to
+get rid of your old use of the macro @code{AC_TRY_CPP} in favor of
+ at code{AC_PREPROC_IFELSE}, but, in the first place, are you sure you need
+to run the @emph{preprocessor} and not the compiler?
+
+ at anchor{AC_EGREP_HEADER}
+ at defmac AC_EGREP_HEADER (@var{pattern}, @var{header-file}, @
+ @var{action-if-found}, @ovar{action-if-not-found})
+ at acindex{EGREP_HEADER}
+If the output of running the preprocessor on the system header file
+ at var{header-file} matches the extended regular expression
+ at var{pattern}, execute shell commands @var{action-if-found}, otherwise
+execute @var{action-if-not-found}.
+ at end defmac
+
+ at anchor{AC_EGREP_CPP}
+ at defmac AC_EGREP_CPP (@var{pattern}, @var{program}, @
+ @ovar{action-if-found}, @ovar{action-if-not-found})
+ at acindex{EGREP_CPP}
+ at var{program} is the text of a C or C++ program, on which shell
+variable, back quote, and backslash substitutions are performed. If the
+output of running the preprocessor on @var{program} matches the
+extended regular expression @var{pattern}, execute shell commands
+ at var{action-if-found}, otherwise execute @var{action-if-not-found}.
+ at end defmac
+
+
+
+ at node Running the Compiler
+ at section Running the Compiler
+
+To check for a syntax feature of the current language's (@pxref{Language
+Choice}) compiler, such as whether it recognizes a certain keyword, or
+simply to try some library feature, use @code{AC_COMPILE_IFELSE} to try
+to compile a small program that uses that feature.
+
+ at defmac AC_COMPILE_IFELSE (@var{input}, @ovar{action-if-true}, @
+ @ovar{action-if-false})
+ at acindex{COMPILE_IFELSE}
+Run the compiler and compilation flags of the current language
+(@pxref{Language Choice}) on the @var{input}, run the shell commands
+ at var{action-if-true} on success, @var{action-if-false} otherwise. The
+ at var{input} can be made by @code{AC_LANG_PROGRAM} and friends.
+
+It is customary to report unexpected failures with
+ at code{AC_MSG_FAILURE}. This macro does not try to link; use
+ at code{AC_LINK_IFELSE} if you need to do that (@pxref{Running the
+Linker}). If needed, @var{action-if-true} can further access the
+just-compiled object file @file{conftest.$OBJEXT}.
+
+This macro uses @code{AC_REQUIRE} for the compiler associated with the
+current language, which means that if the compiler has not yet been
+determined, the compiler determination will be made prior to the body of
+the outermost @code{AC_DEFUN} macro that triggered this macro to
+expand (@pxref{Expanded Before Required}).
+ at end defmac
+
+ at ovindex ERL
+For tests in Erlang, the @var{input} must be the source code of a module named
+ at code{conftest}. @code{AC_COMPILE_IFELSE} generates a @file{conftest.beam}
+file that can be interpreted by the Erlang virtual machine (@code{ERL}). It is
+recommended to use @code{AC_LANG_PROGRAM} to specify the test program,
+to ensure that the Erlang module has the right name.
+
+ at node Running the Linker
+ at section Running the Linker
+
+To check for a library, a function, or a global variable, Autoconf
+ at command{configure} scripts try to compile and link a small program that
+uses it. This is unlike Metaconfig, which by default uses @code{nm} or
+ at code{ar} on the C library to try to figure out which functions are
+available. Trying to link with the function is usually a more reliable
+approach because it avoids dealing with the variations in the options
+and output formats of @code{nm} and @code{ar} and in the location of the
+standard libraries. It also allows configuring for cross-compilation or
+checking a function's runtime behavior if needed. On the other hand,
+it can be slower than scanning the libraries once, but accuracy is more
+important than speed.
+
+ at code{AC_LINK_IFELSE} is used to compile test programs to test for
+functions and global variables. It is also used by @code{AC_CHECK_LIB}
+to check for libraries (@pxref{Libraries}), by adding the library being
+checked for to @code{LIBS} temporarily and trying to link a small
+program.
+
+ at anchor{AC_LINK_IFELSE}
+ at defmac AC_LINK_IFELSE (@var{input}, @ovar{action-if-true}, @
+ @ovar{action-if-false})
+ at acindex{LINK_IFELSE}
+Run the compiler (and compilation flags) and the linker of the current
+language (@pxref{Language Choice}) on the @var{input}, run the shell
+commands @var{action-if-true} on success, @var{action-if-false}
+otherwise. The @var{input} can be made by @code{AC_LANG_PROGRAM} and
+friends. If needed, @var{action-if-true} can further access the
+just-linked program file @file{conftest$EXEEXT}.
+
+ at code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
+current compilation flags.
+
+It is customary to report unexpected failures with
+ at code{AC_MSG_FAILURE}. This macro does not try to execute the program;
+use @code{AC_RUN_IFELSE} if you need to do that (@pxref{Runtime}).
+ at end defmac
+
+The @code{AC_LINK_IFELSE} macro cannot be used for Erlang tests, since Erlang
+programs are interpreted and do not require linking.
+
+
+
+ at node Runtime
+ at section Checking Runtime Behavior
+
+Sometimes you need to find out how a system performs at runtime, such
+as whether a given function has a certain capability or bug. If you
+can, make such checks when your program runs instead of when it is
+configured. You can check for things like the machine's endianness when
+your program initializes itself.
+
+If you really need to test for a runtime behavior while configuring,
+you can write a test program to determine the result, and compile and
+run it using @code{AC_RUN_IFELSE}. Avoid running test programs if
+possible, because this prevents people from configuring your package for
+cross-compiling.
+
+ at anchor{AC_RUN_IFELSE}
+ at defmac AC_RUN_IFELSE (@var{input}, @ovar{action-if-true}, @
+ @ovar{action-if-false}, @dvar{action-if-cross-compiling, AC_MSG_FAILURE})
+ at acindex{RUN_IFELSE}
+Run the compiler (and compilation flags) and the linker of the current
+language (@pxref{Language Choice}) on the @var{input}, then execute the
+resulting program. If the program returns an exit
+status of 0 when executed, run shell commands @var{action-if-true}.
+Otherwise, run shell commands @var{action-if-false}.
+
+The @var{input} can be made by @code{AC_LANG_PROGRAM} and friends.
+ at code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
+compilation flags of the current language (@pxref{Language Choice}).
+Additionally, @var{action-if-true} can run @command{./conftest$EXEEXT}
+for further testing.
+
+In the @var{action-if-false} section, the failing exit status is
+available in the shell variable @samp{$?}. This exit status might be
+that of a failed compilation, or it might be that of a failed program
+execution.
+
+If cross-compilation mode is enabled (this is the case if either the
+compiler being used does not produce executables that run on the system
+where @command{configure} is being run, or if the options @code{--build}
+and @code{--host} were both specified and their values are different),
+then the test program is
+not run. If the optional shell commands @var{action-if-cross-compiling}
+are given, those commands are run instead; typically these commands
+provide pessimistic defaults that allow cross-compilation to work even
+if the guess was wrong. If the fourth argument is empty or omitted, but
+cross-compilation is detected, then @command{configure} prints an error
+message and exits. If you want your package to be useful in a
+cross-compilation scenario, you @emph{should} provide a non-empty
+ at var{action-if-cross-compiling} clause, as well as wrap the
+ at code{AC_RUN_IFELSE} compilation inside an @code{AC_CACHE_CHECK}
+(@pxref{Caching Results}) which allows the user to override the
+pessimistic default if needed.
+
+It is customary to report unexpected failures with
+ at code{AC_MSG_FAILURE}.
+ at end defmac
+
+ at command{autoconf} prints a warning message when creating
+ at command{configure} each time it encounters a call to
+ at code{AC_RUN_IFELSE} with no @var{action-if-cross-compiling} argument
+given. If you are not concerned about users configuring your package
+for cross-compilation, you may ignore the warning. A few of the macros
+distributed with Autoconf produce this warning message; but if this is a
+problem for you, please report it as a bug, along with an appropriate
+pessimistic guess to use instead.
+
+To configure for cross-compiling you can also choose a value for those
+parameters based on the canonical system name (@pxref{Manual
+Configuration}). Alternatively, set up a test results cache file with
+the correct values for the host system (@pxref{Caching Results}).
+
+ at ovindex cross_compiling
+To provide a default for calls of @code{AC_RUN_IFELSE} that are embedded
+in other macros, including a few of the ones that come with Autoconf,
+you can test whether the shell variable @code{cross_compiling} is set to
+ at samp{yes}, and then use an alternate method to get the results instead
+of calling the macros.
+
+It is also permissible to temporarily assign to @code{cross_compiling}
+in order to force tests to behave as though they are in a
+cross-compilation environment, particularly since this provides a way to
+test your @var{action-if-cross-compiling} even when you are not using a
+cross-compiler.
+
+ at example
+# We temporarily set cross-compile mode to force AC_COMPUTE_INT
+# to use the slow link-only method
+save_cross_compiling=$cross_compiling
+cross_compiling=yes
+AC_COMPUTE_INT([@dots{}])
+cross_compiling=$save_cross_compiling
+ at end example
+
+A C or C++ runtime test should be portable.
+ at xref{Portable C and C++}.
+
+Erlang tests must exit themselves the Erlang VM by calling the @code{halt/1}
+function: the given status code is used to determine the success of the test
+(status is @code{0}) or its failure (status is different than @code{0}), as
+explained above. It must be noted that data output through the standard output
+(e.g., using @code{io:format/2}) may be truncated when halting the VM.
+Therefore, if a test must output configuration information, it is recommended
+to create and to output data into the temporary file named @file{conftest.out},
+using the functions of module @code{file}. The @code{conftest.out} file is
+automatically deleted by the @code{AC_RUN_IFELSE} macro. For instance, a
+simplified implementation of Autoconf's @code{AC_ERLANG_SUBST_LIB_DIR}
+macro is:
+
+ at example
+AC_INIT([LibdirTest], [1.0], [bug-libdirtest@@example.org])
+AC_ERLANG_NEED_ERL
+AC_LANG(Erlang)
+AC_RUN_IFELSE(
+ [AC_LANG_PROGRAM([], [dnl
+ file:write_file("conftest.out", code:lib_dir()),
+ halt(0)])],
+ [echo "code:lib_dir() returned: `cat conftest.out`"],
+ [AC_MSG_FAILURE([test Erlang program execution failed])])
+ at end example
+
+
+ at node Systemology
+ at section Systemology
+ at cindex Systemology
+
+This section aims at presenting some systems and pointers to
+documentation. It may help you addressing particular problems reported
+by users.
+
+ at uref{http://@/www.opengroup.org/@/susv3, Posix-conforming systems} are
+derived from the @uref{http://@/www.bell-labs.com/@/history/@/unix/, Unix
+operating system}.
+
+The @uref{http://@/bhami.com/@/rosetta.html, Rosetta Stone for Unix}
+contains a table correlating the features of various Posix-conforming
+systems. @uref{http://@/www.levenez.com/@/unix/, Unix History} is a
+simplified diagram of how many Unix systems were derived from each
+other.
+
+ at uref{http://@/heirloom.sourceforge.net/, The Heirloom Project}
+provides some variants of traditional implementations of Unix utilities.
+
+ at table @asis
+ at item Darwin
+ at cindex Darwin
+Darwin is also known as Mac OS X at . Beware that the file system @emph{can} be
+case-preserving, but case insensitive. This can cause nasty problems,
+since for instance the installation attempt for a package having an
+ at file{INSTALL} file can result in @samp{make install} report that
+nothing was to be done!
+
+That's all dependent on whether the file system is a UFS (case
+sensitive) or HFS+ (case preserving). By default Apple wants you to
+install the OS on HFS+. Unfortunately, there are some pieces of
+software which really need to be built on UFS at . We may want to rebuild
+Darwin to have both UFS and HFS+ available (and put the /local/build
+tree on the UFS).
+
+ at item QNX 4.25
+ at cindex QNX 4.25
+ at c FIXME: Please, if you feel like writing something more precise,
+ at c it'd be great. In particular, I can't understand the difference with
+ at c QNX Neutrino.
+QNX is a realtime operating system running on Intel architecture
+meant to be scalable from the small embedded systems to the hundred
+processor super-computer. It claims to be Posix certified. More
+information is available on the
+ at uref{http://@/www.qnx.com/, QNX home page}.
+
+ at item Tru64
+ at cindex Tru64
+ at uref{http://@/h30097.www3.hp.com/@/docs/,
+Documentation of several versions of Tru64} is available in different
+formats.
+
+ at item Unix version 7
+ at cindex Unix version 7
+ at cindex V7
+Officially this was called the ``Seventh Edition'' of ``the UNIX
+time-sharing system'' but we use the more-common name ``Unix version 7''.
+Documentation is available in the
+ at uref{http://@/plan9.bell-labs.com/@/7thEdMan/, Unix Seventh Edition Manual}.
+Previous versions of Unix are called ``Unix version 6'', etc., but
+they were not as widely used.
+ at end table
+
+
+ at node Multiple Cases
+ at section Multiple Cases
+
+Some operations are accomplished in several possible ways, depending on
+the OS variant. Checking for them essentially requires a ``case
+statement''. Autoconf does not directly provide one; however, it is
+easy to simulate by using a shell variable to keep track of whether a
+way to perform the operation has been found yet.
+
+Here is an example that uses the shell variable @code{fstype} to keep
+track of whether the remaining cases need to be checked. Note that
+since the value of @code{fstype} is under our control, we don't have to
+use the longer @samp{test "x$fstype" = xno}.
+
+ at example
+ at group
+AC_MSG_CHECKING([how to get file system type])
+fstype=no
+# The order of these tests is important.
+AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statvfs.h>
+#include <sys/fstyp.h>]])],
+ [AC_DEFINE([FSTYPE_STATVFS], [1],
+ [Define if statvfs exists.])
+ fstype=SVR4])
+if test $fstype = no; then
+ AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
+#include <sys/fstyp.h>]])],
+ [AC_DEFINE([FSTYPE_USG_STATFS], [1],
+ [Define if USG statfs.])
+ fstype=SVR3])
+fi
+if test $fstype = no; then
+ AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
+#include <sys/vmount.h>]])]),
+ [AC_DEFINE([FSTYPE_AIX_STATFS], [1],
+ [Define if AIX statfs.])
+ fstype=AIX])
+fi
+# (more cases omitted here)
+AC_MSG_RESULT([$fstype])
+ at end group
+ at end example
+
+ at c ====================================================== Results of Tests.
+
+ at node Results
+ at chapter Results of Tests
+
+Once @command{configure} has determined whether a feature exists, what can
+it do to record that information? There are four sorts of things it can
+do: define a C preprocessor symbol, set a variable in the output files,
+save the result in a cache file for future @command{configure} runs, and
+print a message letting the user know the result of the test.
+
+ at menu
+* 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 @command{configure} runs
+* Printing Messages:: Notifying @command{configure} users
+ at end menu
+
+ at node Defining Symbols
+ at section Defining C Preprocessor Symbols
+
+A common action to take in response to a feature test is to define a C
+preprocessor symbol indicating the results of the test. That is done by
+calling @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}.
+
+By default, @code{AC_OUTPUT} places the symbols defined by these macros
+into the output variable @code{DEFS}, which contains an option
+ at option{-D at var{symbol}=@var{value}} for each symbol defined. Unlike in
+Autoconf version 1, there is no variable @code{DEFS} defined while
+ at command{configure} is running. To check whether Autoconf macros have
+already defined a certain C preprocessor symbol, test the value of the
+appropriate cache variable, as in this example:
+
+ at example
+AC_CHECK_FUNC([vprintf], [AC_DEFINE([HAVE_VPRINTF], [1],
+ [Define if vprintf exists.])])
+if test "x$ac_cv_func_vprintf" != xyes; then
+ AC_CHECK_FUNC([_doprnt], [AC_DEFINE([HAVE_DOPRNT], [1],
+ [Define if _doprnt exists.])])
+fi
+ at end example
+
+If @code{AC_CONFIG_HEADERS} has been called, then instead of creating
+ at code{DEFS}, @code{AC_OUTPUT} creates a header file by substituting the
+correct values into @code{#define} statements in a template file.
+ at xref{Configuration Headers}, for more information about this kind of
+output.
+
+ at defmac AC_DEFINE (@var{variable}, @var{value}, @ovar{description})
+ at defmacx AC_DEFINE (@var{variable})
+ at cvindex @var{variable}
+ at acindex{DEFINE}
+Define @var{variable} to @var{value} (verbatim), by defining a C
+preprocessor macro for @var{variable}. @var{variable} should be a C
+identifier, optionally suffixed by a parenthesized argument list to
+define a C preprocessor macro with arguments. The macro argument list,
+if present, should be a comma-separated list of C identifiers, possibly
+terminated by an ellipsis @samp{...} if C99 syntax is employed.
+ at var{variable} should not contain comments, white space, trigraphs,
+backslash-newlines, universal character names, or non-ASCII
+characters.
+
+ at var{value} may contain backslash-escaped newlines, which will be
+preserved if you use @code{AC_CONFIG_HEADERS} but flattened if passed
+via @code{@@DEFS@@} (with no effect on the compilation, since the
+preprocessor sees only one line in the first place). @var{value} should
+not contain raw newlines. If you are not using
+ at code{AC_CONFIG_HEADERS}, @var{value} should not contain any @samp{#}
+characters, as @command{make} tends to eat them. To use a shell
+variable, use @code{AC_DEFINE_UNQUOTED} instead.
+
+ at var{description} is only useful if you are using
+ at code{AC_CONFIG_HEADERS}. In this case, @var{description} is put into
+the generated @file{config.h.in} as the comment before the macro define.
+The following example defines the C preprocessor variable
+ at code{EQUATION} to be the string constant @samp{"$a > $b"}:
+
+ at example
+AC_DEFINE([EQUATION], ["$a > $b"],
+ [Equation string.])
+ at end example
+
+If neither @var{value} nor @var{description} are given, then
+ at var{value} defaults to 1 instead of to the empty string. This is for
+backwards compatibility with older versions of Autoconf, but this usage
+is obsolescent and may be withdrawn in future versions of Autoconf.
+
+If the @var{variable} is a literal string, it is passed to
+ at code{m4_pattern_allow} (@pxref{Forbidden Patterns}).
+
+If multiple @code{AC_DEFINE} statements are executed for the same
+ at var{variable} name (not counting any parenthesized argument list),
+the last one wins.
+ at end defmac
+
+ at defmac AC_DEFINE_UNQUOTED (@var{variable}, @var{value}, @ovar{description})
+ at defmacx AC_DEFINE_UNQUOTED (@var{variable})
+ at acindex{DEFINE_UNQUOTED}
+ at cvindex @var{variable}
+Like @code{AC_DEFINE}, but three shell expansions are
+performed---once---on @var{variable} and @var{value}: variable expansion
+(@samp{$}), command substitution (@samp{`}), and backslash escaping
+(@samp{\}), as if in an unquoted here-document. Single and double quote
+characters in the value have no
+special meaning. Use this macro instead of @code{AC_DEFINE} when
+ at var{variable} or @var{value} is a shell variable. Examples:
+
+ at example
+AC_DEFINE_UNQUOTED([config_machfile], ["$machfile"],
+ [Configuration machine file.])
+AC_DEFINE_UNQUOTED([GETGROUPS_T], [$ac_cv_type_getgroups],
+ [getgroups return type.])
+AC_DEFINE_UNQUOTED([$ac_tr_hdr], [1],
+ [Translated header name.])
+ at end example
+ at end defmac
+
+Due to a syntactical bizarreness of the Bourne shell, do not use
+semicolons to separate @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}
+calls from other macro calls or shell code; that can cause syntax errors
+in the resulting @command{configure} script. Use either blanks or
+newlines. That is, do this:
+
+ at example
+AC_CHECK_HEADER([elf.h],
+ [AC_DEFINE([SVR4], [1], [System V Release 4]) LIBS="-lelf $LIBS"])
+ at end example
+
+ at noindent
+or this:
+
+ at example
+AC_CHECK_HEADER([elf.h],
+ [AC_DEFINE([SVR4], [1], [System V Release 4])
+ LIBS="-lelf $LIBS"])
+ at end example
+
+ at noindent
+instead of this:
+
+ at example
+AC_CHECK_HEADER([elf.h],
+ [AC_DEFINE([SVR4], [1], [System V Release 4]); LIBS="-lelf $LIBS"])
+ at end example
+
+ at node Setting Output Variables
+ at section Setting Output Variables
+ at cindex Output variables
+
+Another way to record the results of tests is to set @dfn{output
+variables}, which are shell variables whose values are substituted into
+files that @command{configure} outputs. The two macros below create new
+output variables. @xref{Preset Output Variables}, for a list of output
+variables that are always available.
+
+ at defmac AC_SUBST (@var{variable}, @ovar{value})
+ at acindex{SUBST}
+Create an output variable from a shell variable. Make @code{AC_OUTPUT}
+substitute the variable @var{variable} into output files (typically one
+or more makefiles). This means that @code{AC_OUTPUT}
+replaces instances of @samp{@@@var{variable}@@} in input files with the
+value that the shell variable @var{variable} has when @code{AC_OUTPUT}
+is called. The value can contain any non- at code{NUL} character, including
+newline. If you are using Automake 1.11 or newer, for newlines in values
+you might want to consider using @code{AM_SUBST_NOTMAKE} to prevent
+ at command{automake} from adding a line @code{@var{variable} =
+@@@var{variable}@@} to the @file{Makefile.in} files (@pxref{Optional, ,
+Automake, automake, Other things Automake recognizes}).
+
+Variable occurrences should not overlap: e.g., an input file should
+not contain @samp{@@@var{var1}@@@var{var2}@@} if @var{var1} and @var{var2}
+are variable names.
+The substituted value is not rescanned for more output variables;
+occurrences of @samp{@@@var{variable}@@} in the value are inserted
+literally into the output file. (The algorithm uses the special marker
+ at code{|#_!!_#|} internally, so neither the substituted value nor the
+output file may contain @code{|#_!!_#|}.)
+
+If @var{value} is given, in addition assign it to @var{variable}.
+
+The string @var{variable} is passed to @code{m4_pattern_allow}
+(@pxref{Forbidden Patterns}).
+ at end defmac
+
+ at defmac AC_SUBST_FILE (@var{variable})
+ at acindex{SUBST_FILE}
+Another way to create an output variable from a shell variable. Make
+ at code{AC_OUTPUT} insert (without substitutions) the contents of the file
+named by shell variable @var{variable} into output files. This means
+that @code{AC_OUTPUT} replaces instances of
+ at samp{@@@var{variable}@@} in output files (such as @file{Makefile.in})
+with the contents of the file that the shell variable @var{variable}
+names when @code{AC_OUTPUT} is called. Set the variable to
+ at file{/dev/null} for cases that do not have a file to insert.
+This substitution occurs only when the @samp{@@@var{variable}@@} is on a
+line by itself, optionally surrounded by spaces and tabs. The
+substitution replaces the whole line, including the spaces, tabs, and
+the terminating newline.
+
+This macro is useful for inserting makefile fragments containing
+special dependencies or other @command{make} directives for particular host
+or target types into makefiles. For example, @file{configure.ac}
+could contain:
+
+ at example
+AC_SUBST_FILE([host_frag])
+host_frag=$srcdir/conf/sun4.mh
+ at end example
+
+ at noindent
+and then a @file{Makefile.in} could contain:
+
+ at example
+@@host_frag@@
+ at end example
+
+The string @var{variable} is passed to @code{m4_pattern_allow}
+(@pxref{Forbidden Patterns}).
+ at end defmac
+
+ at cindex Precious Variable
+ at cindex Variable, Precious
+Running @command{configure} in varying environments can be extremely
+dangerous. If for instance the user runs @samp{CC=bizarre-cc
+./configure}, then the cache, @file{config.h}, and many other output
+files depend upon @command{bizarre-cc} being the C compiler. If
+for some reason the user runs @command{./configure} again, or if it is
+run via @samp{./config.status --recheck}, (@xref{Automatic Remaking},
+and @pxref{config.status Invocation}), then the configuration can be
+inconsistent, composed of results depending upon two different
+compilers.
+
+Environment variables that affect this situation, such as @samp{CC}
+above, are called @dfn{precious variables}, and can be declared as such
+by @code{AC_ARG_VAR}.
+
+ at defmac AC_ARG_VAR (@var{variable}, @var{description})
+ at acindex{ARG_VAR}
+Declare @var{variable} is a precious variable, and include its
+ at var{description} in the variable section of @samp{./configure --help}.
+
+Being precious means that
+ at itemize @minus
+ at item
+ at var{variable} is substituted via @code{AC_SUBST}.
+
+ at item
+The value of @var{variable} when @command{configure} was launched is
+saved in the cache, including if it was not specified on the command
+line but via the environment. Indeed, while @command{configure} can
+notice the definition of @code{CC} in @samp{./configure CC=bizarre-cc},
+it is impossible to notice it in @samp{CC=bizarre-cc ./configure},
+which, unfortunately, is what most users do.
+
+We emphasize that it is the @emph{initial} value of @var{variable} which
+is saved, not that found during the execution of @command{configure}.
+Indeed, specifying @samp{./configure FOO=foo} and letting
+ at samp{./configure} guess that @code{FOO} is @code{foo} can be two
+different things.
+
+ at item
+ at var{variable} is checked for consistency between two
+ at command{configure} runs. For instance:
+
+ at example
+$ @kbd{./configure --silent --config-cache}
+$ @kbd{CC=cc ./configure --silent --config-cache}
+configure: error: `CC' was not set in the previous run
+configure: error: changes in the environment can compromise \
+the build
+configure: error: run `make distclean' and/or \
+`rm config.cache' and start over
+ at end example
+
+ at noindent
+and similarly if the variable is unset, or if its content is changed.
+If the content has white space changes only, then the error is degraded
+to a warning only, but the old value is reused.
+
+ at item
+ at var{variable} is kept during automatic reconfiguration
+(@pxref{config.status Invocation}) as if it had been passed as a command
+line argument, including when no cache is used:
+
+ at example
+$ @kbd{CC=/usr/bin/cc ./configure var=raboof --silent}
+$ @kbd{./config.status --recheck}
+running CONFIG_SHELL=/bin/sh /bin/sh ./configure var=raboof \
+ CC=/usr/bin/cc --no-create --no-recursion
+ at end example
+ at end itemize
+ at end defmac
+
+ at node Special Chars in Variables
+ at section Special Characters in Output Variables
+ at cindex Output variables, special characters in
+
+Many output variables are intended to be evaluated both by
+ at command{make} and by the shell. Some characters are expanded
+differently in these two contexts, so to avoid confusion these
+variables' values should not contain any of the following characters:
+
+ at example
+" # $ & ' ( ) * ; < > ? [ \ ^ ` |
+ at end example
+
+Also, these variables' values should neither contain newlines, nor start
+with @samp{~}, nor contain white space or @samp{:} immediately followed
+by @samp{~}. The values can contain nonempty sequences of white space
+characters like tabs and spaces, but each such sequence might
+arbitrarily be replaced by a single space during substitution.
+
+These restrictions apply both to the values that @command{configure}
+computes, and to the values set directly by the user. For example, the
+following invocations of @command{configure} are problematic, since they
+attempt to use special characters within @code{CPPFLAGS} and white space
+within @code{$(srcdir)}:
+
+ at example
+CPPFLAGS='-DOUCH="&\"#$*?"' '../My Source/ouch-1.0/configure'
+
+'../My Source/ouch-1.0/configure' CPPFLAGS='-DOUCH="&\"#$*?"'
+ at end example
+
+ at node Caching Results
+ at section Caching Results
+ at cindex Cache
+
+To avoid checking for the same features repeatedly in various
+ at command{configure} scripts (or in repeated runs of one script),
+ at command{configure} can optionally save the results of many checks in a
+ at dfn{cache file} (@pxref{Cache Files}). If a @command{configure} script
+runs with caching enabled and finds a cache file, it reads the results
+of previous runs from the cache and avoids rerunning those checks. As a
+result, @command{configure} can then run much faster than if it had to
+perform all of the checks every time.
+
+ at defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it})
+ at acindex{CACHE_VAL}
+Ensure that the results of the check identified by @var{cache-id} are
+available. If the results of the check were in the cache file that was
+read, and @command{configure} was not given the @option{--quiet} or
+ at option{--silent} option, print a message saying that the result was
+cached; otherwise, run the shell commands @var{commands-to-set-it}. If
+the shell commands are run to determine the value, the value is
+saved in the cache file just before @command{configure} creates its output
+files. @xref{Cache Variable Names}, for how to choose the name of the
+ at var{cache-id} variable.
+
+The @var{commands-to-set-it} @emph{must have no side effects} except for
+setting the variable @var{cache-id}, see below.
+ at end defmac
+
+ at defmac AC_CACHE_CHECK (@var{message}, @var{cache-id}, @
+ @var{commands-to-set-it})
+ at acindex{CACHE_CHECK}
+A wrapper for @code{AC_CACHE_VAL} that takes care of printing the
+messages. This macro provides a convenient shorthand for the most
+common way to use these macros. It calls @code{AC_MSG_CHECKING} for
+ at var{message}, then @code{AC_CACHE_VAL} with the @var{cache-id} and
+ at var{commands} arguments, and @code{AC_MSG_RESULT} with @var{cache-id}.
+
+The @var{commands-to-set-it} @emph{must have no side effects} except for
+setting the variable @var{cache-id}, see below.
+ at end defmac
+
+It is common to find buggy macros using @code{AC_CACHE_VAL} or
+ at code{AC_CACHE_CHECK}, because people are tempted to call
+ at code{AC_DEFINE} in the @var{commands-to-set-it}. Instead, the code that
+ at emph{follows} the call to @code{AC_CACHE_VAL} should call
+ at code{AC_DEFINE}, by examining the value of the cache variable. For
+instance, the following macro is broken:
+
+ at example
+ at c If you change this example, adjust tests/base.at:AC_CACHE_CHECK.
+ at group
+AC_DEFUN([AC_SHELL_TRUE],
+[AC_CACHE_CHECK([whether true(1) works], [my_cv_shell_true_works],
+ [my_cv_shell_true_works=no
+ (true) 2>/dev/null && my_cv_shell_true_works=yes
+ if test "x$my_cv_shell_true_works" = xyes; then
+ AC_DEFINE([TRUE_WORKS], [1],
+ [Define if `true(1)' works properly.])
+ fi])
+])
+ at end group
+ at end example
+
+ at noindent
+This fails if the cache is enabled: the second time this macro is run,
+ at code{TRUE_WORKS} @emph{will not be defined}. The proper implementation
+is:
+
+ at example
+ at c If you change this example, adjust tests/base.at:AC_CACHE_CHECK.
+ at group
+AC_DEFUN([AC_SHELL_TRUE],
+[AC_CACHE_CHECK([whether true(1) works], [my_cv_shell_true_works],
+ [my_cv_shell_true_works=no
+ (true) 2>/dev/null && my_cv_shell_true_works=yes])
+ if test "x$my_cv_shell_true_works" = xyes; then
+ AC_DEFINE([TRUE_WORKS], [1],
+ [Define if `true(1)' works properly.])
+ fi
+])
+ at end group
+ at end example
+
+Also, @var{commands-to-set-it} should not print any messages, for
+example with @code{AC_MSG_CHECKING}; do that before calling
+ at code{AC_CACHE_VAL}, so the messages are printed regardless of whether
+the results of the check are retrieved from the cache or determined by
+running the shell commands.
+
+ at menu
+* Cache Variable Names:: Shell variables used in caches
+* Cache Files:: Files @command{configure} uses for caching
+* Cache Checkpointing:: Loading and saving the cache file
+ at end menu
+
+ at node Cache Variable Names
+ at subsection Cache Variable Names
+ at cindex Cache variable
+
+The names of cache variables should have the following format:
+
+ at example
+ at var{package-prefix}_cv_ at var{value-type}_ at var{specific-value}_ at ovar{additional-options}
+ at end example
+
+ at noindent
+for example, @samp{ac_cv_header_stat_broken} or
+ at samp{ac_cv_prog_gcc_traditional}. The parts of the variable name are:
+
+ at table @asis
+ at item @var{package-prefix}
+An abbreviation for your package or organization; the same prefix you
+begin local Autoconf macros with, except lowercase by convention.
+For cache values used by the distributed Autoconf macros, this value is
+ at samp{ac}.
+
+ at item @code{_cv_}
+Indicates that this shell variable is a cache value. This string
+ at emph{must} be present in the variable name, including the leading
+underscore.
+
+ at item @var{value-type}
+A convention for classifying cache values, to produce a rational naming
+system. The values used in Autoconf are listed in @ref{Macro Names}.
+
+ at item @var{specific-value}
+Which member of the class of cache values this test applies to.
+For example, which function (@samp{alloca}), program (@samp{gcc}), or
+output variable (@samp{INSTALL}).
+
+ at item @var{additional-options}
+Any particular behavior of the specific member that this test applies to.
+For example, @samp{broken} or @samp{set}. This part of the name may
+be omitted if it does not apply.
+ at end table
+
+The values assigned to cache variables may not contain newlines.
+Usually, their values are Boolean (@samp{yes} or @samp{no}) or the
+names of files or functions; so this is not an important restriction.
+ at ref{Cache Variable Index} for an index of cache variables with
+documented semantics.
+
+
+ at node Cache Files
+ at subsection Cache Files
+
+A cache file is a shell script that caches the results of configure
+tests run on one system so they can be shared between configure scripts
+and configure runs. It is not useful on other systems. If its contents
+are invalid for some reason, the user may delete or edit it, or override
+documented cache variables on the @command{configure} command line.
+
+By default, @command{configure} uses no cache file,
+to avoid problems caused by accidental
+use of stale cache files.
+
+To enable caching, @command{configure} accepts @option{--config-cache} (or
+ at option{-C}) to cache results in the file @file{config.cache}.
+Alternatively, @option{--cache-file=@var{file}} specifies that
+ at var{file} be the cache file. The cache file is created if it does not
+exist already. When @command{configure} calls @command{configure} scripts in
+subdirectories, it uses the @option{--cache-file} argument so that they
+share the same cache. @xref{Subdirectories}, for information on
+configuring subdirectories with the @code{AC_CONFIG_SUBDIRS} macro.
+
+ at file{config.status} only pays attention to the cache file if it is
+given the @option{--recheck} option, which makes it rerun
+ at command{configure}.
+
+It is wrong to try to distribute cache files for particular system types.
+There is too much room for error in doing that, and too much
+administrative overhead in maintaining them. For any features that
+can't be guessed automatically, use the standard method of the canonical
+system type and linking files (@pxref{Manual Configuration}).
+
+The site initialization script can specify a site-wide cache file to
+use, instead of the usual per-program cache. In this case, the cache
+file gradually accumulates information whenever someone runs a new
+ at command{configure} script. (Running @command{configure} merges the new cache
+results with the existing cache file.) This may cause problems,
+however, if the system configuration (e.g., the installed libraries or
+compilers) changes and the stale cache file is not deleted.
+
+If @command{configure} is interrupted at the right time when it updates
+a cache file outside of the build directory where the @command{configure}
+script is run, it may leave behind a temporary file named after the
+cache file with digits following it. You may safely delete such a file.
+
+
+ at node Cache Checkpointing
+ at subsection Cache Checkpointing
+
+If your configure script, or a macro called from @file{configure.ac}, happens
+to abort the configure process, it may be useful to checkpoint the cache
+a few times at key points using @code{AC_CACHE_SAVE}. Doing so
+reduces the amount of time it takes to rerun the configure script with
+(hopefully) the error that caused the previous abort corrected.
+
+ at c FIXME: Do we really want to document this guy?
+ at defmac AC_CACHE_LOAD
+ at acindex{CACHE_LOAD}
+Loads values from existing cache file, or creates a new cache file if a
+cache file is not found. Called automatically from @code{AC_INIT}.
+ at end defmac
+
+ at defmac AC_CACHE_SAVE
+ at acindex{CACHE_SAVE}
+Flushes all cached values to the cache file. Called automatically from
+ at code{AC_OUTPUT}, but it can be quite useful to call
+ at code{AC_CACHE_SAVE} at key points in @file{configure.ac}.
+ at end defmac
+
+For instance:
+
+ at example
+ at r{ @dots{} AC_INIT, etc. @dots{}}
+ at group
+# Checks for programs.
+AC_PROG_CC
+AC_PROG_AWK
+ at r{ @dots{} more program checks @dots{}}
+AC_CACHE_SAVE
+ at end group
+
+ at group
+# Checks for libraries.
+AC_CHECK_LIB([nsl], [gethostbyname])
+AC_CHECK_LIB([socket], [connect])
+ at r{ @dots{} more lib checks @dots{}}
+AC_CACHE_SAVE
+ at end group
+
+ at group
+# Might abort at dots{}
+AM_PATH_GTK([1.0.2], [], [AC_MSG_ERROR([GTK not in path])])
+AM_PATH_GTKMM([0.9.5], [], [AC_MSG_ERROR([GTK not in path])])
+ at end group
+ at r{ @dots{} AC_OUTPUT, etc. @dots{}}
+ at end example
+
+ at node Printing Messages
+ at section Printing Messages
+ at cindex Messages, from @command{configure}
+
+ at command{configure} scripts need to give users running them several kinds
+of information. The following macros print messages in ways appropriate
+for each kind. The arguments to all of them get enclosed in shell
+double quotes, so the shell performs variable and back-quote
+substitution on them.
+
+These macros are all wrappers around the @command{echo} shell command.
+They direct output to the appropriate file descriptor (@pxref{File
+Descriptor Macros}).
+ at command{configure} scripts should rarely need to run @command{echo} directly
+to print messages for the user. Using these macros makes it easy to
+change how and when each kind of message is printed; such changes need
+only be made to the macro definitions and all the callers change
+automatically.
+
+To diagnose static issues, i.e., when @command{autoconf} is run, see
+ at ref{Diagnostic Macros}.
+
+ at defmac AC_MSG_CHECKING (@var{feature-description})
+ at acindex{MSG_CHECKING}
+Notify the user that @command{configure} is checking for a particular
+feature. This macro prints a message that starts with @samp{checking }
+and ends with @samp{...} and no newline. It must be followed by a call
+to @code{AC_MSG_RESULT} to print the result of the check and the
+newline. The @var{feature-description} should be something like
+ at samp{whether the Fortran compiler accepts C++ comments} or @samp{for
+c89}.
+
+This macro prints nothing if @command{configure} is run with the
+ at option{--quiet} or @option{--silent} option.
+ at end defmac
+
+ at anchor{AC_MSG_RESULT}
+ at defmac AC_MSG_RESULT (@var{result-description})
+ at acindex{MSG_RESULT}
+Notify the user of the results of a check. @var{result-description} is
+almost always the value of the cache variable for the check, typically
+ at samp{yes}, @samp{no}, or a file name. This macro should follow a call
+to @code{AC_MSG_CHECKING}, and the @var{result-description} should be
+the completion of the message printed by the call to
+ at code{AC_MSG_CHECKING}.
+
+This macro prints nothing if @command{configure} is run with the
+ at option{--quiet} or @option{--silent} option.
+ at end defmac
+
+ at anchor{AC_MSG_NOTICE}
+ at defmac AC_MSG_NOTICE (@var{message})
+ at acindex{MSG_NOTICE}
+Deliver the @var{message} to the user. It is useful mainly to print a
+general description of the overall purpose of a group of feature checks,
+e.g.,
+
+ at example
+AC_MSG_NOTICE([checking if stack overflow is detectable])
+ at end example
+
+This macro prints nothing if @command{configure} is run with the
+ at option{--quiet} or @option{--silent} option.
+ at end defmac
+
+ at anchor{AC_MSG_ERROR}
+ at defmac AC_MSG_ERROR (@var{error-description}, @dvar{exit-status, $?/1})
+ at acindex{MSG_ERROR}
+Notify the user of an error that prevents @command{configure} from
+completing. This macro prints an error message to the standard error
+output and exits @command{configure} with @var{exit-status} (@samp{$?}
+by default, except that @samp{0} is converted to @samp{1}).
+ at var{error-description} should be something like @samp{invalid value
+$HOME for \$HOME}.
+
+The @var{error-description} should start with a lower-case letter, and
+``cannot'' is preferred to ``can't''.
+ at end defmac
+
+ at defmac AC_MSG_FAILURE (@var{error-description}, @ovar{exit-status})
+ at acindex{MSG_FAILURE}
+This @code{AC_MSG_ERROR} wrapper notifies the user of an error that
+prevents @command{configure} from completing @emph{and} that additional
+details are provided in @file{config.log}. This is typically used when
+abnormal results are found during a compilation.
+ at end defmac
+
+ at anchor{AC_MSG_WARN}
+ at defmac AC_MSG_WARN (@var{problem-description})
+ at acindex{MSG_WARN}
+Notify the @command{configure} user of a possible problem. This macro
+prints the message to the standard error output; @command{configure}
+continues running afterward, so macros that call @code{AC_MSG_WARN} should
+provide a default (back-up) behavior for the situations they warn about.
+ at var{problem-description} should be something like @samp{ln -s seems to
+make hard links}.
+ at end defmac
+
+
+
+ at c ====================================================== Programming in M4.
+
+ at node Programming in M4
+ at chapter Programming in M4
+ at cindex M4
+
+Autoconf is written on top of two layers: @dfn{M4sugar}, which provides
+convenient macros for pure M4 programming, and @dfn{M4sh}, which
+provides macros dedicated to shell script generation.
+
+As of this version of Autoconf, these two layers still contain
+experimental macros, whose interface might change in the future. As a
+matter of fact, @emph{anything that is not documented must not be used}.
+
+ at menu
+* 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
+ at end menu
+
+ at node M4 Quotation
+ at section M4 Quotation
+ at cindex M4 quotation
+ at cindex quotation
+
+The most common problem with existing macros is an improper quotation.
+This section, which users of Autoconf can skip, but which macro writers
+ at emph{must} read, first justifies the quotation scheme that was chosen
+for Autoconf and then ends with a rule of thumb. Understanding the
+former helps one to follow the latter.
+
+ at menu
+* 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
+ at end menu
+
+ at node Active Characters
+ at subsection Active Characters
+
+To fully understand where proper quotation is important, you first need
+to know what the special characters are in Autoconf: @samp{#} introduces
+a comment inside which no macro expansion is performed, @samp{,}
+separates arguments, @samp{[} and @samp{]} are the quotes
+themselves at footnote{By itself, M4 uses @samp{`} and @samp{'}; it is the
+M4sugar layer that sets up the preferred quotes of @samp{[} and @samp{]}.},
+ at samp{(} and @samp{)} (which M4 tries to match by pairs), and finally
+ at samp{$} inside a macro definition.
+
+In order to understand the delicate case of macro calls, we first have
+to present some obvious failures. Below they are ``obvious-ified'',
+but when you find them in real life, they are usually in disguise.
+
+Comments, introduced by a hash and running up to the newline, are opaque
+tokens to the top level: active characters are turned off, and there is
+no macro expansion:
+
+ at example
+# define([def], ine)
+ at result{}# define([def], ine)
+ at end example
+
+Each time there can be a macro expansion, there is a quotation
+expansion, i.e., one level of quotes is stripped:
+
+ at example
+int tab[10];
+ at result{}int tab10;
+[int tab[10];]
+ at result{}int tab[10];
+ at end example
+
+Without this in mind, the reader might try hopelessly to use her macro
+ at code{array}:
+
+ at example
+define([array], [int tab[10];])
+array
+ at result{}int tab10;
+[array]
+ at result{}array
+ at end example
+
+ at noindent
+How can you correctly output the intended results at footnote{Using
+ at code{defn}.}?
+
+
+ at node One Macro Call
+ at subsection One Macro Call
+
+Let's proceed on the interaction between active characters and macros
+with this small macro, which just returns its first argument:
+
+ at example
+define([car], [$1])
+ at end example
+
+ at noindent
+The two pairs of quotes above are not part of the arguments of
+ at code{define}; rather, they are understood by the top level when it
+tries to find the arguments of @code{define}. Therefore, assuming
+ at code{car} is not already defined, it is equivalent to write:
+
+ at example
+define(car, $1)
+ at end example
+
+ at noindent
+But, while it is acceptable for a @file{configure.ac} to avoid unnecessary
+quotes, it is bad practice for Autoconf macros which must both be more
+robust and also advocate perfect style.
+
+At the top level, there are only two possibilities: either you
+quote or you don't:
+
+ at example
+car(foo, bar, baz)
+ at result{}foo
+[car(foo, bar, baz)]
+ at result{}car(foo, bar, baz)
+ at end example
+
+Let's pay attention to the special characters:
+
+ at example
+car(#)
+ at error{}EOF in argument list
+ at end example
+
+The closing parenthesis is hidden in the comment; with a hypothetical
+quoting, the top level understood it this way:
+
+ at example
+car([#)]
+ at end example
+
+ at noindent
+Proper quotation, of course, fixes the problem:
+
+ at example
+car([#])
+ at result{}#
+ at end example
+
+Here are more examples:
+
+ at example
+car(foo, bar)
+ at result{}foo
+car([foo, bar])
+ at result{}foo, bar
+car((foo, bar))
+ at result{}(foo, bar)
+car([(foo], [bar)])
+ at result{}(foo
+define([a], [b])
+ at result{}
+car(a)
+ at result{}b
+car([a])
+ at result{}b
+car([[a]])
+ at result{}a
+car([[[a]]])
+ at result{}[a]
+ at end example
+
+ at node Quoting and Parameters
+ at subsection Quoting and Parameters
+
+When M4 encounters @samp{$} within a macro definition, followed
+immediately by a character it recognizes (@samp{0}@dots{}@samp{9},
+ at samp{#}, @samp{@@}, or @samp{*}), it will perform M4 parameter
+expansion. This happens regardless of how many layers of quotes the
+parameter expansion is nested within, or even if it occurs in text that
+will be rescanned as a comment.
+
+ at example
+define([none], [$1])
+ at result{}
+define([one], [[$1]])
+ at result{}
+define([two], [[[$1]]])
+ at result{}
+define([comment], [# $1])
+ at result{}
+define([active], [ACTIVE])
+ at result{}
+none([active])
+ at result{}ACTIVE
+one([active])
+ at result{}active
+two([active])
+ at result{}[active]
+comment([active])
+ at result{}# active
+ at end example
+
+On the other hand, since autoconf generates shell code, you often want
+to output shell variable expansion, rather than performing M4 parameter
+expansion. To do this, you must use M4 quoting to separate the @samp{$}
+from the next character in the definition of your macro. If the macro
+definition occurs in single-quoted text, then insert another level of
+quoting; if the usage is already inside a double-quoted string, then
+split it into concatenated strings.
+
+ at example
+define([single], [a single-quoted $[]1 definition])
+ at result{}
+define([double], [[a double-quoted $][1 definition]])
+ at result{}
+single
+ at result{}a single-quoted $1 definition
+double
+ at result{}a double-quoted $1 definition
+ at end example
+
+Posix states that M4 implementations are free to provide implementation
+extensions when @samp{$@{} is encountered in a macro definition.
+Autoconf reserves the longer sequence @samp{$@{@{} for use with planned
+extensions that will be available in the future GNU M4 2.0,
+but guarantees that all other instances of @samp{$@{} will be output
+literally. Therefore, this idiom can also be used to output shell code
+parameter references:
+
+ at example
+define([first], [$@{1@}])first
+ at result{}$@{1@}
+ at end example
+
+Posix also states that @samp{$11} should expand to the first parameter
+concatenated with a literal @samp{1}, although some versions of
+GNU M4 expand the eleventh parameter instead. For
+portability, you should only use single-digit M4 parameter expansion.
+
+With this in mind, we can explore the cases where macros invoke
+macros at enddots{}
+
+ at node Quotation and Nested Macros
+ at subsection Quotation and Nested Macros
+
+The examples below use the following macros:
+
+ at example
+define([car], [$1])
+define([active], [ACT, IVE])
+define([array], [int tab[10]])
+ at end example
+
+Each additional embedded macro call introduces other possible
+interesting quotations:
+
+ at example
+car(active)
+ at result{}ACT
+car([active])
+ at result{}ACT, IVE
+car([[active]])
+ at result{}active
+ at end example
+
+In the first case, the top level looks for the arguments of @code{car},
+and finds @samp{active}. Because M4 evaluates its arguments
+before applying the macro, @samp{active} is expanded, which results in:
+
+ at example
+car(ACT, IVE)
+ at result{}ACT
+ at end example
+
+ at noindent
+In the second case, the top level gives @samp{active} as first and only
+argument of @code{car}, which results in:
+
+ at example
+active
+ at result{}ACT, IVE
+ at end example
+
+ at noindent
+i.e., the argument is evaluated @emph{after} the macro that invokes it.
+In the third case, @code{car} receives @samp{[active]}, which results in:
+
+ at example
+[active]
+ at result{}active
+ at end example
+
+ at noindent
+exactly as we already saw above.
+
+The example above, applied to a more realistic example, gives:
+
+ at example
+car(int tab[10];)
+ at result{}int tab10;
+car([int tab[10];])
+ at result{}int tab10;
+car([[int tab[10];]])
+ at result{}int tab[10];
+ at end example
+
+ at noindent
+Huh? The first case is easily understood, but why is the second wrong,
+and the third right? To understand that, you must know that after
+M4 expands a macro, the resulting text is immediately subjected
+to macro expansion and quote removal. This means that the quote removal
+occurs twice---first before the argument is passed to the @code{car}
+macro, and second after the @code{car} macro expands to the first
+argument.
+
+As the author of the Autoconf macro @code{car}, you then consider it to
+be incorrect that your users have to double-quote the arguments of
+ at code{car}, so you ``fix'' your macro. Let's call it @code{qar} for
+quoted car:
+
+ at example
+define([qar], [[$1]])
+ at end example
+
+ at noindent
+and check that @code{qar} is properly fixed:
+
+ at example
+qar([int tab[10];])
+ at result{}int tab[10];
+ at end example
+
+ at noindent
+Ahhh! That's much better.
+
+But note what you've done: now that the result of @code{qar} is always
+a literal string, the only time a user can use nested macros is if she
+relies on an @emph{unquoted} macro call:
+
+ at example
+qar(active)
+ at result{}ACT
+qar([active])
+ at result{}active
+ at end example
+
+ at noindent
+leaving no way for her to reproduce what she used to do with @code{car}:
+
+ at example
+car([active])
+ at result{}ACT, IVE
+ at end example
+
+ at noindent
+Worse yet: she wants to use a macro that produces a set of @code{cpp}
+macros:
+
+ at example
+define([my_includes], [#include <stdio.h>])
+car([my_includes])
+ at result{}#include <stdio.h>
+qar(my_includes)
+ at error{}EOF in argument list
+ at end example
+
+This macro, @code{qar}, because it double quotes its arguments, forces
+its users to leave their macro calls unquoted, which is dangerous.
+Commas and other active symbols are interpreted by M4 before
+they are given to the macro, often not in the way the users expect.
+Also, because @code{qar} behaves differently from the other macros,
+it's an exception that should be avoided in Autoconf.
+
+ at node Changequote is Evil
+ at subsection @code{changequote} is Evil
+ at cindex @code{changequote}
+
+The temptation is often high to bypass proper quotation, in particular
+when it's late at night. Then, many experienced Autoconf hackers
+finally surrender to the dark side of the force and use the ultimate
+weapon: @code{changequote}.
+
+The M4 builtin @code{changequote} belongs to a set of primitives that
+allow one to adjust the syntax of the language to adjust it to one's
+needs. For instance, by default M4 uses @samp{`} and @samp{'} as
+quotes, but in the context of shell programming (and actually of most
+programming languages), that's about the worst choice one can make:
+because of strings and back-quoted expressions in shell code (such as
+ at samp{'this'} and @samp{`that`}), and because of literal characters in usual
+programming languages (as in @samp{'0'}), there are many unbalanced
+ at samp{`} and @samp{'}. Proper M4 quotation then becomes a nightmare, if
+not impossible. In order to make M4 useful in such a context, its
+designers have equipped it with @code{changequote}, which makes it
+possible to choose another pair of quotes. M4sugar, M4sh, Autoconf, and
+Autotest all have chosen to use @samp{[} and @samp{]}. Not especially
+because they are unlikely characters, but @emph{because they are
+characters unlikely to be unbalanced}.
+
+There are other magic primitives, such as @code{changecom} to specify
+what syntactic forms are comments (it is common to see
+ at samp{changecom(<!--, -->)} when M4 is used to produce HTML pages),
+ at code{changeword} and @code{changesyntax} to change other syntactic
+details (such as the character to denote the @var{n}th argument, @samp{$} by
+default, the parentheses around arguments, etc.).
+
+These primitives are really meant to make M4 more useful for specific
+domains: they should be considered like command line options:
+ at option{--quotes}, @option{--comments}, @option{--words}, and
+ at option{--syntax}. Nevertheless, they are implemented as M4 builtins, as
+it makes M4 libraries self contained (no need for additional options).
+
+There lies the problem at enddots{}
+
+ at sp 1
+
+The problem is that it is then tempting to use them in the middle of an
+M4 script, as opposed to its initialization. This, if not carefully
+thought out, can lead to disastrous effects: @emph{you are changing the
+language in the middle of the execution}. Changing and restoring the
+syntax is often not enough: if you happened to invoke macros in between,
+these macros are lost, as the current syntax is probably not
+the one they were implemented with.
+
+ at c FIXME: I've been looking for a short, real case example, but I
+ at c lost them all :(
+
+
+ at node Quadrigraphs
+ at subsection Quadrigraphs
+ at cindex quadrigraphs
+ at cindex @samp{@@S|@@}
+ at cindex @samp{@@&t@@}
+ at c Info cannot handle `:' in index entries.
+ at ifnotinfo
+ at cindex @samp{@@<:@@}
+ at cindex @samp{@@:>@@}
+ at cindex @samp{@@%:@@}
+ at cindex @samp{@@@{:@@}
+ at cindex @samp{@@:@}@@}
+ at end ifnotinfo
+
+When writing an Autoconf macro you may occasionally need to generate
+special characters that are difficult to express with the standard
+Autoconf quoting rules. For example, you may need to output the regular
+expression @samp{[^[]}, which matches any character other than @samp{[}.
+This expression contains unbalanced brackets so it cannot be put easily
+into an M4 macro.
+
+Additionally, there are a few m4sugar macros (such as @code{m4_split}
+and @code{m4_expand}) which internally use special markers in addition
+to the regular quoting characters. If the arguments to these macros
+contain the literal strings @samp{-=<@{(} or @samp{)@}>=-}, the macros
+might behave incorrectly.
+
+You can work around these problems by using one of the following
+ at dfn{quadrigraphs}:
+
+ at table @samp
+ at item @@<:@@
+ at samp{[}
+ at item @@:>@@
+ at samp{]}
+ at item @@S|@@
+ at samp{$}
+ at item @@%:@@
+ at samp{#}
+ at item @@@{:@@
+ at samp{(}
+ at item @@:@}@@
+ at samp{)}
+ at item @@&t@@
+Expands to nothing.
+ at end table
+
+Quadrigraphs are replaced at a late stage of the translation process,
+after @command{m4} is run, so they do not get in the way of M4 quoting.
+For example, the string @samp{^@@<:@@}, independently of its quotation,
+appears as @samp{^[} in the output.
+
+The empty quadrigraph can be used:
+
+ at itemize @minus
+ at item to mark trailing spaces explicitly
+
+Trailing spaces are smashed by @command{autom4te}. This is a feature.
+
+ at item to produce quadrigraphs and other strings reserved by m4sugar
+
+For instance @samp{@@<@@&t@@:@@} produces @samp{@@<:@@}. For a more
+contrived example:
+
+ at example
+m4_define([a], [A])m4_define([b], [B])m4_define([c], [C])dnl
+m4_split([a )@}>=- b -=<@{( c])
+ at result{}[a], [], [B], [], [c]
+m4_split([a )@}@@&t@@>=- b -=<@@&t@@@{( c])
+ at result{}[a], [)@}>=-], [b], [-=<@{(], [c]
+ at end example
+
+ at item to escape @emph{occurrences} of forbidden patterns
+
+For instance you might want to mention @code{AC_FOO} in a comment, while
+still being sure that @command{autom4te} still catches unexpanded
+ at samp{AC_*}. Then write @samp{AC@@&t@@_FOO}.
+ at end itemize
+
+The name @samp{@@&t@@} was suggested by Paul Eggert:
+
+ at quotation
+I should give some credit to the @samp{@@&t@@} pun. The @samp{&} is my
+own invention, but the @samp{t} came from the source code of the
+ALGOL68C compiler, written by Steve Bourne (of Bourne shell fame),
+and which used @samp{mt} to denote the empty string. In C, it would
+have looked like something like:
+
+ at example
+char const mt[] = "";
+ at end example
+
+ at noindent
+but of course the source code was written in Algol 68.
+
+I don't know where he got @samp{mt} from: it could have been his own
+invention, and I suppose it could have been a common pun around the
+Cambridge University computer lab at the time.
+ at end quotation
+
+
+ at node Balancing Parentheses
+ at subsection Dealing with unbalanced parentheses
+ at cindex balancing parentheses
+ at cindex parentheses, balancing
+ at cindex unbalanced parentheses, managing
+
+One of the pitfalls of portable shell programming is that @command{case}
+statements require unbalanced parentheses (@pxref{case, , Limitations of
+Shell Builtins}). With syntax highlighting
+editors, the presence of unbalanced @samp{)} can interfere with editors
+that perform syntax highlighting of macro contents based on finding the
+matching @samp{(}. Another concern is how much editing must be done
+when transferring code snippets between shell scripts and macro
+definitions. But most importantly, the presence of unbalanced
+parentheses can introduce expansion bugs.
+
+For an example, here is an underquoted attempt to use the macro
+ at code{my_case}, which happens to expand to a portable @command{case}
+statement:
+
+ at example
+AC_DEFUN([my_case],
+[case $file_name in
+ *.c) echo "C source code";;
+esac])
+AS_IF(:, my_case)
+ at end example
+
+ at noindent
+In the above example, the @code{AS_IF} call underquotes its arguments.
+As a result, the unbalanced @samp{)} generated by the premature
+expansion of @code{my_case} results in expanding @code{AS_IF} with a
+truncated parameter, and the expansion is syntactically invalid:
+
+ at example
+if :; then
+ case $file_name in
+ *.c
+fi echo "C source code";;
+esac)
+ at end example
+
+If nothing else, this should emphasize the importance of the quoting
+arguments to macro calls. On the other hand, there are several
+variations for defining @code{my_case} to be more robust, even when used
+without proper quoting, each with some benefits and some drawbacks.
+
+ at itemize @w{}
+ at item Creative literal shell comment
+ at example
+AC_DEFUN([my_case],
+[case $file_name in #(
+ *.c) echo "C source code";;
+esac])
+ at end example
+ at noindent
+This version provides balanced parentheses to several editors, and can
+be copied and pasted into a terminal as is. Unfortunately, it is still
+unbalanced as an Autoconf argument, since @samp{#(} is an M4 comment
+that masks the normal properties of @samp{(}.
+
+ at item Quadrigraph shell comment
+ at example
+AC_DEFUN([my_case],
+[case $file_name in @@%:@@(
+ *.c) echo "C source code";;
+esac])
+ at end example
+ at noindent
+This version provides balanced parentheses to even more editors, and can
+be used as a balanced Autoconf argument. Unfortunately, it requires
+some editing before it can be copied and pasted into a terminal, and the
+use of the quadrigraph @samp{@@%:@@} for @samp{#} reduces readability.
+
+ at item Quoting just the parenthesis
+ at example
+AC_DEFUN([my_case],
+[case $file_name in
+ *.c[)] echo "C source code";;
+esac])
+ at end example
+ at noindent
+This version quotes the @samp{)}, so that it can be used as a balanced
+Autoconf argument. As written, this is not balanced to an editor, but
+it can be coupled with @samp{[#(]} to meet that need, too. However, it
+still requires some edits before it can be copied and pasted into a
+terminal.
+
+ at item Double-quoting the entire statement
+ at example
+AC_DEFUN([my_case],
+[[case $file_name in #(
+ *.c) echo "C source code";;
+esac]])
+ at end example
+ at noindent
+Since the entire macro is double-quoted, there is no problem with using
+this as an Autoconf argument; and since the double-quoting is over the
+entire statement, this code can be easily copied and pasted into a
+terminal. However, the double quoting prevents the expansion of any
+macros inside the case statement, which may cause its own set of
+problems.
+
+ at item Using @code{AS_CASE}
+ at example
+AC_DEFUN([my_case],
+[AS_CASE([$file_name],
+ [*.c], [echo "C source code"])])
+ at end example
+ at noindent
+This version avoids the balancing issue altogether, by relying on
+ at code{AS_CASE} (@pxref{Common Shell Constructs}); it also allows for the
+expansion of @code{AC_REQUIRE} to occur prior to the entire case
+statement, rather than within a branch of the case statement that might
+not be taken. However, the abstraction comes with a penalty that it is
+no longer a quick copy, paste, and edit to get back to shell code.
+ at end itemize
+
+
+ at node Quotation Rule Of Thumb
+ at subsection Quotation Rule Of Thumb
+
+To conclude, the quotation rule of thumb is:
+
+ at center @emph{One pair of quotes per pair of parentheses.}
+
+Never over-quote, never under-quote, in particular in the definition of
+macros. In the few places where the macros need to use brackets
+(usually in C program text or regular expressions), properly quote
+ at emph{the arguments}!
+
+It is common to read Autoconf programs with snippets like:
+
+ at example
+AC_TRY_LINK(
+changequote(<<, >>)dnl
+<<#include <time.h>
+#ifndef tzname /* For SGI. */
+extern char *tzname[]; /* RS6000 and others reject char **tzname. */
+#endif>>,
+changequote([, ])dnl
+[atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)
+ at end example
+
+ at noindent
+which is incredibly useless since @code{AC_TRY_LINK} is @emph{already}
+double quoting, so you just need:
+
+ at example
+AC_TRY_LINK(
+[#include <time.h>
+#ifndef tzname /* For SGI. */
+extern char *tzname[]; /* RS6000 and others reject char **tzname. */
+#endif],
+ [atoi (*tzname);],
+ [ac_cv_var_tzname=yes],
+ [ac_cv_var_tzname=no])
+ at end example
+
+ at noindent
+The M4-fluent reader might note that these two examples are rigorously
+equivalent, since M4 swallows both the @samp{changequote(<<, >>)}
+and @samp{<<} @samp{>>} when it @dfn{collects} the arguments: these
+quotes are not part of the arguments!
+
+Simplified, the example above is just doing this:
+
+ at example
+changequote(<<, >>)dnl
+<<[]>>
+changequote([, ])dnl
+ at end example
+
+ at noindent
+instead of simply:
+
+ at example
+[[]]
+ at end example
+
+With macros that do not double quote their arguments (which is the
+rule), double-quote the (risky) literals:
+
+ at example
+AC_LINK_IFELSE([AC_LANG_PROGRAM(
+[[#include <time.h>
+#ifndef tzname /* For SGI. */
+extern char *tzname[]; /* RS6000 and others reject char **tzname. */
+#endif]],
+ [atoi (*tzname);])],
+ [ac_cv_var_tzname=yes],
+ [ac_cv_var_tzname=no])
+ at end example
+
+Please note that the macro @code{AC_TRY_LINK} is obsolete, so you really
+should be using @code{AC_LINK_IFELSE} instead.
+
+ at xref{Quadrigraphs}, for what to do if you run into a hopeless case
+where quoting does not suffice.
+
+When you create a @command{configure} script using newly written macros,
+examine it carefully to check whether you need to add more quotes in
+your macros. If one or more words have disappeared in the M4
+output, you need more quotes. When in doubt, quote.
+
+However, it's also possible to put on too many layers of quotes. If
+this happens, the resulting @command{configure} script may contain
+unexpanded macros. The @command{autoconf} program checks for this problem
+by looking for the string @samp{AC_} in @file{configure}. However, this
+heuristic does not work in general: for example, it does not catch
+overquoting in @code{AC_DEFINE} descriptions.
+
+
+ at c ---------------------------------------- Using autom4te
+
+ at node Using autom4te
+ at section Using @command{autom4te}
+
+The Autoconf suite, including M4sugar, M4sh, and Autotest, in addition
+to Autoconf per se, heavily rely on M4. All these different uses
+revealed common needs factored into a layer over M4:
+ at command{autom4te}@footnote{
+ at c
+Yet another great name from Lars J. Aas.
+ at c
+}.
+
+ at command{autom4te} is a preprocessor that is like @command{m4}.
+It supports M4 extensions designed for use in tools like Autoconf.
+
+ at menu
+* autom4te Invocation:: A GNU M4 wrapper
+* Customizing autom4te:: Customizing the Autoconf package
+ at end menu
+
+ at node autom4te Invocation
+ at subsection Invoking @command{autom4te}
+
+The command line arguments are modeled after M4's:
+
+ at example
+autom4te @var{options} @var{files}
+ at end example
+
+ at noindent
+ at evindex M4
+where the @var{files} are directly passed to @command{m4}. By default,
+GNU M4 is found during configuration, but the environment
+variable
+ at env{M4} can be set to tell @command{autom4te} where to look. In addition
+to the regular expansion, it handles the replacement of the quadrigraphs
+(@pxref{Quadrigraphs}), and of @samp{__oline__}, the current line in the
+output. It supports an extended syntax for the @var{files}:
+
+ at table @file
+ at item @var{file}.m4f
+This file is an M4 frozen file. Note that @emph{all the previous files
+are ignored}. See the option @option{--melt} for the rationale.
+
+ at item @var{file}?
+If found in the library path, the @var{file} is included for expansion,
+otherwise it is ignored instead of triggering a failure.
+ at end table
+
+ at sp 1
+
+Of course, it supports the Autoconf common subset of options:
+
+ at table @option
+ at item --help
+ at itemx -h
+Print a summary of the command line options and exit.
+
+ at item --version
+ at itemx -V
+Print the version number of Autoconf and exit.
+
+ at item --verbose
+ at itemx -v
+Report processing steps.
+
+ at item --debug
+ at itemx -d
+Don't remove the temporary files and be even more verbose.
+
+ at item --include=@var{dir}
+ at itemx -I @var{dir}
+Also look for input files in @var{dir}. Multiple invocations
+accumulate.
+
+ at item --output=@var{file}
+ at itemx -o @var{file}
+Save output (script or trace) to @var{file}. The file @option{-} stands
+for the standard output.
+ at end table
+
+ at sp 1
+
+As an extension of @command{m4}, it includes the following options:
+
+ at table @option
+ at item --warnings=@var{category}
+ at itemx -W @var{category}
+ at evindex WARNINGS
+ at c FIXME: Point to the M4sugar macros, not Autoconf's.
+Report the warnings related to @var{category} (which can actually be a
+comma separated list). @xref{Reporting Messages}, macro
+ at code{AC_DIAGNOSE}, for a comprehensive list of categories. Special
+values include:
+
+ at table @samp
+ at item all
+report all the warnings
+
+ at item none
+report none
+
+ at item error
+treats warnings as errors
+
+ at item no- at var{category}
+disable warnings falling into @var{category}
+ at end table
+
+Warnings about @samp{syntax} are enabled by default, and the environment
+variable @env{WARNINGS}, a comma separated list of categories, is
+honored. @samp{autom4te -W @var{category}} actually
+behaves as if you had run:
+
+ at example
+autom4te --warnings=syntax,$WARNINGS, at var{category}
+ at end example
+
+ at noindent
+For example, if you want to disable defaults and @env{WARNINGS}
+of @command{autom4te}, but enable the warnings about obsolete
+constructs, you would use @option{-W none,obsolete}.
+
+ at cindex Back trace
+ at cindex Macro invocation stack
+ at command{autom4te} displays a back trace for errors, but not for
+warnings; if you want them, just pass @option{-W error}.
+
+ at item --melt
+ at itemx -M
+Do not use frozen files. Any argument @code{@var{file}.m4f} is
+replaced by @code{@var{file}.m4}. This helps tracing the macros which
+are executed only when the files are frozen, typically
+ at code{m4_define}. For instance, running:
+
+ at example
+autom4te --melt 1.m4 2.m4f 3.m4 4.m4f input.m4
+ at end example
+
+ at noindent
+is roughly equivalent to running:
+
+ at example
+m4 1.m4 2.m4 3.m4 4.m4 input.m4
+ at end example
+
+ at noindent
+while
+
+ at example
+autom4te 1.m4 2.m4f 3.m4 4.m4f input.m4
+ at end example
+
+ at noindent
+is equivalent to:
+
+ at example
+m4 --reload-state=4.m4f input.m4
+ at end example
+
+ at item --freeze
+ at itemx -F
+Produce a frozen state file. @command{autom4te} freezing is stricter
+than M4's: it must produce no warnings, and no output other than empty
+lines (a line with white space is @emph{not} empty) and comments
+(starting with @samp{#}). Unlike @command{m4}'s similarly-named option,
+this option takes no argument:
+
+ at example
+autom4te 1.m4 2.m4 3.m4 --freeze --output=3.m4f
+ at end example
+
+ at noindent
+corresponds to
+
+ at example
+m4 1.m4 2.m4 3.m4 --freeze-state=3.m4f
+ at end example
+
+ at item --mode=@var{octal-mode}
+ at itemx -m @var{octal-mode}
+Set the mode of the non-traces output to @var{octal-mode}; by default
+ at samp{0666}.
+ at end table
+
+ at sp 1
+
+ at cindex @file{autom4te.cache}
+As another additional feature over @command{m4}, @command{autom4te}
+caches its results. GNU M4 is able to produce a regular
+output and traces at the same time. Traces are heavily used in the
+GNU Build System: @command{autoheader} uses them to build
+ at file{config.h.in}, @command{autoreconf} to determine what
+GNU Build System components are used, @command{automake} to
+``parse'' @file{configure.ac} etc. To avoid recomputation,
+traces are cached while performing regular expansion,
+and conversely. This cache is (actually, the caches are) stored in
+the directory @file{autom4te.cache}. @emph{It can safely be removed}
+at any moment (especially if for some reason @command{autom4te}
+considers it trashed).
+
+ at table @option
+ at item --cache=@var{directory}
+ at itemx -C @var{directory}
+Specify the name of the directory where the result should be cached.
+Passing an empty value disables caching. Be sure to pass a relative
+file name, as for the time being, global caches are not supported.
+
+ at item --no-cache
+Don't cache the results.
+
+ at item --force
+ at itemx -f
+If a cache is used, consider it obsolete (but update it anyway).
+ at end table
+
+ at sp 1
+
+Because traces are so important to the GNU Build System,
+ at command{autom4te} provides high level tracing features as compared to
+M4, and helps exploiting the cache:
+
+ at table @option
+ at item --trace=@var{macro}[:@var{format}]
+ at itemx -t @var{macro}[:@var{format}]
+Trace the invocations of @var{macro} according to the @var{format}.
+Multiple @option{--trace} arguments can be used to list several macros.
+Multiple @option{--trace} arguments for a single macro are not
+cumulative; instead, you should just make @var{format} as long as
+needed.
+
+The @var{format} is a regular string, with newlines if desired, and
+several special escape codes. It defaults to @samp{$f:$l:$n:$%}. It can
+use the following special escapes:
+
+ at table @samp
+ at item $$
+ at c $$ restore font-lock
+The character @samp{$}.
+
+ at item $f
+The file name from which @var{macro} is called.
+
+ at item $l
+The line number from which @var{macro} is called.
+
+ at item $d
+The depth of the @var{macro} call. This is an M4 technical detail that
+you probably don't want to know about.
+
+ at item $n
+The name of the @var{macro}.
+
+ at item $@var{num}
+The @var{num}th argument of the call to @var{macro}.
+
+ at item $@@
+ at itemx $@var{sep}@@
+ at itemx $@{@var{separator}@}@@
+All the arguments passed to @var{macro}, separated by the character
+ at var{sep} or the string @var{separator} (@samp{,} by default). Each
+argument is quoted, i.e., enclosed in a pair of square brackets.
+
+ at item $*
+ at itemx $@var{sep}*
+ at itemx $@{@var{separator}@}*
+As above, but the arguments are not quoted.
+
+ at item $%
+ at itemx $@var{sep}%
+ at itemx $@{@var{separator}@}%
+As above, but the arguments are not quoted, all new line characters in
+the arguments are smashed, and the default separator is @samp{:}.
+
+The escape @samp{$%} produces single-line trace outputs (unless you put
+newlines in the @samp{separator}), while @samp{$@@} and @samp{$*} do
+not.
+ at end table
+
+ at xref{autoconf Invocation}, for examples of trace uses.
+
+ at item --preselect=@var{macro}
+ at itemx -p @var{macro}
+Cache the traces of @var{macro}, but do not enable traces. This is
+especially important to save CPU cycles in the future. For instance,
+when invoked, @command{autoconf} preselects all the macros that
+ at command{autoheader}, @command{automake}, @command{autoreconf}, etc.,
+trace, so that running @command{m4} is not needed to trace them: the
+cache suffices. This results in a huge speed-up.
+ at end table
+
+ at sp 1
+
+ at cindex Autom4te Library
+Finally, @command{autom4te} introduces the concept of @dfn{Autom4te
+libraries}. They consists in a powerful yet extremely simple feature:
+sets of combined command line arguments:
+
+ at table @option
+ at item --language=@var{language}
+ at itemx -l @var{language}
+Use the @var{language} Autom4te library. Current languages include:
+
+ at table @code
+ at item M4sugar
+create M4sugar output.
+
+ at item M4sh
+create M4sh executable shell scripts.
+
+ at item Autotest
+create Autotest executable test suites.
+
+ at item Autoconf-without-aclocal-m4
+create Autoconf executable configure scripts without
+reading @file{aclocal.m4}.
+
+ at item Autoconf
+create Autoconf executable configure scripts. This language inherits
+all the characteristics of @code{Autoconf-without-aclocal-m4} and
+additionally reads @file{aclocal.m4}.
+ at end table
+
+ at item --prepend-include=@var{dir}
+ at itemx -B @var{dir}
+Prepend directory @var{dir} to the search path. This is used to include
+the language-specific files before any third-party macros.
+
+ at end table
+
+ at cindex @file{autom4te.cfg}
+As an example, if Autoconf is installed in its default location,
+ at file{/usr/local}, the command @samp{autom4te -l m4sugar foo.m4} is
+strictly equivalent to the command:
+
+ at example
+autom4te --prepend-include /usr/local/share/autoconf \
+ m4sugar/m4sugar.m4f --warnings syntax foo.m4
+ at end example
+
+ at noindent
+Recursive expansion applies here: the command @samp{autom4te -l m4sh foo.m4}
+is the same as @samp{autom4te --language M4sugar m4sugar/m4sh.m4f
+foo.m4}, i.e.:
+
+ at example
+autom4te --prepend-include /usr/local/share/autoconf \
+ m4sugar/m4sugar.m4f m4sugar/m4sh.m4f --mode 777 foo.m4
+ at end example
+
+ at noindent
+The definition of the languages is stored in @file{autom4te.cfg}.
+
+ at node Customizing autom4te
+ at subsection Customizing @command{autom4te}
+
+One can customize @command{autom4te} via @file{~/.autom4te.cfg} (i.e.,
+as found in the user home directory), and @file{./.autom4te.cfg} (i.e.,
+as found in the directory from which @command{autom4te} is run). The
+order is first reading @file{autom4te.cfg}, then @file{~/.autom4te.cfg},
+then @file{./.autom4te.cfg}, and finally the command line arguments.
+
+In these text files, comments are introduced with @code{#}, and empty
+lines are ignored. Customization is performed on a per-language basis,
+wrapped in between a @samp{begin-language: "@var{language}"},
+ at samp{end-language: "@var{language}"} pair.
+
+Customizing a language stands for appending options (@pxref{autom4te
+Invocation}) to the current definition of the language. Options, and
+more generally arguments, are introduced by @samp{args:
+ at var{arguments}}. You may use the traditional shell syntax to quote the
+ at var{arguments}.
+
+As an example, to disable Autoconf caches (@file{autom4te.cache})
+globally, include the following lines in @file{~/.autom4te.cfg}:
+
+ at verbatim
+## ------------------ ##
+## User Preferences. ##
+## ------------------ ##
+
+begin-language: "Autoconf-without-aclocal-m4"
+args: --no-cache
+end-language: "Autoconf-without-aclocal-m4"
+ at end verbatim
+
+
+ at node Programming in M4sugar
+ at section Programming in M4sugar
+
+ at cindex M4sugar
+M4 by itself provides only a small, but sufficient, set of all-purpose
+macros. M4sugar introduces additional generic macros. Its name was
+coined by Lars J. Aas: ``Readability And Greater Understanding Stands 4
+M4sugar''.
+
+M4sugar reserves the macro namespace @samp{^_m4_} for internal use, and
+the macro namespace @samp{^m4_} for M4sugar macros. You should not
+define your own macros into these namespaces.
+
+ at menu
+* 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
+ at end menu
+
+ at node Redefined M4 Macros
+ at subsection Redefined M4 Macros
+
+ at msindex{builtin}
+ at msindex{changecom}
+ at msindex{changequote}
+ at msindex{debugfile}
+ at msindex{debugmode}
+ at msindex{decr}
+ at msindex{define}
+ at msindex{divnum}
+ at msindex{errprint}
+ at msindex{esyscmd}
+ at msindex{eval}
+ at msindex{format}
+ at msindex{ifdef}
+ at msindex{incr}
+ at msindex{index}
+ at msindex{indir}
+ at msindex{len}
+ at msindex{pushdef}
+ at msindex{shift}
+ at msindex{substr}
+ at msindex{syscmd}
+ at msindex{sysval}
+ at msindex{traceoff}
+ at msindex{traceon}
+ at msindex{translit}
+With a few exceptions, all the M4 native macros are moved in the
+ at samp{m4_} pseudo-namespace, e.g., M4sugar renames @code{define} as
+ at code{m4_define} etc.
+
+The list of macros unchanged from M4, except for their name, is:
+ at itemize @minus
+ at item m4_builtin
+ at item m4_changecom
+ at item m4_changequote
+ at item m4_debugfile
+ at item m4_debugmode
+ at item m4_decr
+ at item m4_define
+ at item m4_divnum
+ at item m4_errprint
+ at item m4_esyscmd
+ at item m4_eval
+ at item m4_format
+ at item m4_ifdef
+ at item m4_incr
+ at item m4_index
+ at item m4_indir
+ at item m4_len
+ at item m4_pushdef
+ at item m4_shift
+ at item m4_substr
+ at item m4_syscmd
+ at item m4_sysval
+ at item m4_traceoff
+ at item m4_traceon
+ at item m4_translit
+ at end itemize
+
+Some M4 macros are redefined, and are slightly incompatible with their
+native equivalent.
+
+ at defmac __file__
+ at defmacx __line__
+ at MSindex __file__
+ at MSindex __line__
+All M4 macros starting with @samp{__} retain their original name: for
+example, no @code{m4__file__} is defined.
+ at end defmac
+
+ at defmac __oline__
+ at MSindex __oline__
+This is not technically a macro, but a feature of Autom4te. The
+sequence @code{__oline__} can be used similarly to the other m4sugar
+location macros, but rather than expanding to the location of the input
+file, it is translated to the line number where it appears in the output
+file after all other M4 expansions.
+ at end defmac
+
+ at defmac dnl
+ at MSindex dnl
+This macro kept its original name: no @code{m4_dnl} is defined.
+ at end defmac
+
+ at defmac m4_bpatsubst (@var{string}, @var{regexp}, @ovar{replacement})
+ at msindex{bpatsubst}
+This macro corresponds to @code{patsubst}. The name @code{m4_patsubst}
+is kept for future versions of M4sugar, once GNU M4 2.0 is
+released and supports extended regular expression syntax.
+ at end defmac
+
+ at defmac m4_bregexp (@var{string}, @var{regexp}, @ovar{replacement})
+ at msindex{bregexp}
+This macro corresponds to @code{regexp}. The name @code{m4_regexp}
+is kept for future versions of M4sugar, once GNU M4 2.0 is
+released and supports extended regular expression syntax.
+ at end defmac
+
+ at defmac m4_copy (@var{source}, @var{dest})
+ at defmacx m4_copy_force (@var{source}, @var{dest})
+ at defmacx m4_rename (@var{source}, @var{dest})
+ at defmacx m4_rename_force (@var{source}, @var{dest})
+ at msindex{copy}
+ at msindex{copy_force}
+ at msindex{rename}
+ at msindex{rename_force}
+These macros aren't directly builtins, but are closely related to
+ at code{m4_pushdef} and @code{m4_defn}. @code{m4_copy} and
+ at code{m4_rename} ensure that @var{dest} is undefined, while
+ at code{m4_copy_force} and @code{m4_rename_force} overwrite any existing
+definition. All four macros then proceed to copy the entire pushdef
+stack of definitions of @var{source} over to @var{dest}. @code{m4_copy}
+and @code{m4_copy_force} preserve the source (including in the special
+case where @var{source} is undefined), while @code{m4_rename} and
+ at code{m4_rename_force} undefine the original macro name (making it an
+error to rename an undefined @var{source}).
+
+Note that attempting to invoke a renamed macro might not work, since the
+macro may have a dependence on helper macros accessed via composition of
+ at samp{$0} but that were not also renamed; likewise, other macros may
+have a hard-coded dependence on @var{source} and could break if
+ at var{source} has been deleted. On the other hand, it is always safe to
+rename a macro to temporarily move it out of the way, then rename it
+back later to restore original semantics.
+ at end defmac
+
+ at defmac m4_defn (@var{macro}@dots{})
+ at msindex{defn}
+This macro fails if @var{macro} is not defined, even when using older
+versions of M4 that did not warn. See @code{m4_undefine}.
+Unfortunately, in order to support these older versions of M4, there are
+some situations involving unbalanced quotes where concatenating multiple
+macros together will work in newer M4 but not in m4sugar; use
+quadrigraphs to work around this.
+ at end defmac
+
+ at defmac m4_divert (@var{diversion})
+ at msindex{divert}
+M4sugar relies heavily on diversions, so rather than behaving as a
+primitive, @code{m4_divert} behaves like:
+ at example
+m4_divert_pop()m4_divert_push([@var{diversion}])
+ at end example
+ at noindent
+ at xref{Diversion support}, for more details about the use of the
+diversion stack. In particular, this implies that @var{diversion}
+should be a named diversion rather than a raw number. But be aware that
+it is seldom necessary to explicitly change the diversion stack, and
+that when done incorrectly, it can lead to syntactically invalid
+scripts.
+ at end defmac
+
+ at defmac m4_dumpdef (@var{name}@dots{})
+ at defmacx m4_dumpdefs (@var{name}@dots{})
+ at msindex{dumpdef}
+ at msindex{dumpdefs}
+ at code{m4_dumpdef} is like the M4 builtin, except that this version
+requires at least one argument, output always goes to standard error
+rather than the current debug file, no sorting is done on multiple
+arguments, and an error is issued if any
+ at var{name} is undefined. @code{m4_dumpdefs} is a convenience macro that
+calls @code{m4_dumpdef} for all of the
+ at code{m4_pushdef} stack of definitions, starting with the current, and
+silently does nothing if @var{name} is undefined.
+
+Unfortunately, due to a limitation in M4 1.4.x, any macro defined as a
+builtin is output as the empty string. This behavior is rectified by
+using M4 1.6 or newer. However, this behavior difference means that
+ at code{m4_dumpdef} should only be used while developing m4sugar macros,
+and never in the final published form of a macro.
+ at end defmac
+
+ at defmac m4_esyscmd_s (@var{command})
+ at msindex{esyscmd_s}
+Like @code{m4_esyscmd}, this macro expands to the result of running
+ at var{command} in a shell. The difference is that any trailing newlines
+are removed, so that the output behaves more like shell command
+substitution.
+ at end defmac
+
+ at defmac m4_exit (@var{exit-status})
+ at msindex{exit}
+This macro corresponds to @code{m4exit}.
+ at end defmac
+
+ at defmac m4_if (@var{comment})
+ at defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @ovar{not-equal})
+ at defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal-1}, @
+ @var{string-3}, @var{string-4}, @var{equal-2}, @dots{}, @ovar{not-equal})
+ at msindex{if}
+This macro corresponds to @code{ifelse}. @var{string-1} and
+ at var{string-2} are compared literally, so usually one of the two
+arguments is passed unquoted. @xref{Conditional constructs}, for more
+conditional idioms.
+ at end defmac
+
+ at defmac m4_include (@var{file})
+ at defmacx m4_sinclude (@var{file})
+ at msindex{include}
+ at msindex{sinclude}
+Like the M4 builtins, but warn against multiple inclusions of @var{file}.
+ at end defmac
+
+ at defmac m4_mkstemp (@var{template})
+ at defmacx m4_maketemp (@var{template})
+ at msindex{maketemp}
+ at msindex{mkstemp}
+Posix requires @code{maketemp} to replace the trailing @samp{X}
+characters in @var{template} with the process id, without regards to the
+existence of a file by that name, but this a security hole. When this
+was pointed out to the Posix folks, they agreed to invent a new macro
+ at code{mkstemp} that always creates a uniquely named file, but not all
+versions of GNU M4 support the new macro. In M4sugar,
+ at code{m4_maketemp} and @code{m4_mkstemp} are synonyms for each other,
+and both have the secure semantics regardless of which macro the
+underlying M4 provides.
+ at end defmac
+
+ at defmac m4_popdef (@var{macro}@dots{})
+ at msindex{popdef}
+This macro fails if @var{macro} is not defined, even when using older
+versions of M4 that did not warn. See @code{m4_undefine}.
+ at end defmac
+
+ at defmac m4_undefine (@var{macro}@dots{})
+ at msindex{undefine}
+This macro fails if @var{macro} is not defined, even when using older
+versions of M4 that did not warn. Use
+
+ at example
+m4_ifdef([@var{macro}], [m4_undefine([@var{macro}])])
+ at end example
+
+ at noindent
+if you are not sure whether @var{macro} is defined.
+ at end defmac
+
+ at defmac m4_undivert (@var{diversion}@dots{})
+ at msindex{undivert}
+Unlike the M4 builtin, at least one @var{diversion} must be specified.
+Also, since the M4sugar diversion stack prefers named
+diversions, the use of @code{m4_undivert} to include files is risky.
+ at xref{Diversion support}, for more details about the use of the
+diversion stack. But be aware that it is seldom necessary to explicitly
+change the diversion stack, and that when done incorrectly, it can lead
+to syntactically invalid scripts.
+ at end defmac
+
+ at defmac m4_wrap (@var{text})
+ at defmacx m4_wrap_lifo (@var{text})
+ at msindex{wrap}
+ at msindex{wrap_lifo}
+These macros correspond to @code{m4wrap}. Posix requires arguments of
+multiple wrap calls to be reprocessed at EOF in the same order
+as the original calls (first-in, first-out). GNU M4 versions
+through 1.4.10, however, reprocess them in reverse order (last-in,
+first-out). Both orders are useful, therefore, you can rely on
+ at code{m4_wrap} to provide FIFO semantics and @code{m4_wrap_lifo} for
+LIFO semantics, regardless of the underlying GNU M4 version.
+
+Unlike the GNU M4 builtin, these macros only recognize one
+argument, and avoid token pasting between consecutive invocations. On
+the other hand, nested calls to @code{m4_wrap} from within wrapped text
+work just as in the builtin.
+ at end defmac
+
+
+ at node Diagnostic Macros
+ at subsection Diagnostic messages from M4sugar
+ at cindex Messages, from @command{M4sugar}
+
+When macros statically diagnose abnormal situations, benign or fatal,
+they should report them using these macros. For issuing dynamic issues,
+i.e., when @command{configure} is run, see @ref{Printing Messages}.
+
+ at defmac m4_assert (@var{expression}, @dvar{exit-status, 1})
+ at msindex{assert}
+Assert that the arithmetic @var{expression} evaluates to non-zero.
+Otherwise, issue a fatal error, and exit @command{autom4te} with
+ at var{exit-status}.
+ at end defmac
+
+ at defmac m4_errprintn (@var{message})
+ at msindex{errprintn}
+Similar to the builtin @code{m4_errprint}, except that a newline is
+guaranteed after @var{message}.
+ at end defmac
+
+ at anchor{m4_fatal}
+ at defmac m4_fatal (@var{message})
+ at msindex{fatal}
+Report a severe error @var{message} prefixed with the current location,
+and have @command{autom4te} die.
+ at end defmac
+
+ at defmac m4_location
+ at msindex{location}
+Useful as a prefix in a message line. Short for:
+ at example
+__file__:__line__
+ at end example
+ at end defmac
+
+ at anchor{m4_warn}
+ at defmac m4_warn (@var{category}, @var{message})
+ at msindex{warn}
+Report @var{message} as a warning (or as an error if requested by the
+user) if warnings of the @var{category} are turned on. If the message
+is emitted, it is prefixed with the current location, and followed by a
+call trace of all macros defined via @code{AC_DEFUN} used to get to the
+current expansion. You are encouraged to use standard categories, which
+currently include:
+
+ at table @samp
+ at item all
+messages that don't fall into one of the following categories. Use of an
+empty @var{category} is equivalent.
+
+ at item cross
+related to cross compilation issues.
+
+ at item obsolete
+use of an obsolete construct.
+
+ at item syntax
+dubious syntactic constructs, incorrectly ordered macro calls.
+ at end table
+ at end defmac
+
+
+ at node Diversion support
+ at subsection Diversion support
+
+M4sugar makes heavy use of diversions under the hood, because it is
+often the case that
+text that must appear early in the output is not discovered until late
+in the input. Additionally, some of the topological sorting algorithms
+used in resolving macro dependencies use diversions. However, most
+macros should not need to change diversions directly, but rather rely on
+higher-level M4sugar macros to manage diversions transparently. If you
+change diversions improperly, you risk generating a syntactically
+invalid script, because an incorrect diversion will violate assumptions
+made by many macros about whether prerequisite text has been previously
+output. In short, if you manually change the diversion, you should not
+expect any macros provided by the Autoconf package to work until you
+have restored the diversion stack back to its original state.
+
+In the rare case that it is necessary to write a macro that explicitly
+outputs text to a different diversion, it is important to be aware of an
+M4 limitation regarding diversions: text only goes to a diversion if it
+is not part of argument collection. Therefore, any macro that changes
+the current diversion cannot be used as an unquoted argument to another
+macro, but must be expanded at the top level. The macro
+ at code{m4_expand} will diagnose any attempt to change diversions, since
+it is generally useful only as an argument to another macro. The
+following example shows what happens when diversion manipulation is
+attempted within macro arguments:
+
+ at example
+m4_do([normal text]
+m4_divert_push([KILL])unwanted[]m4_divert_pop([KILL])
+[m4_divert_push([KILL])discarded[]m4_divert_pop([KILL])])dnl
+ at result{}normal text
+ at result{}unwanted
+ at end example
+
+ at noindent
+Notice that the unquoted text @code{unwanted} is output, even though it
+was processed while the current diversion was @code{KILL}, because it
+was collected as part of the argument to @code{m4_do}. However, the
+text @code{discarded} disappeared as desired, because the diversion
+changes were single-quoted, and were not expanded until the top-level
+rescan of the output of @code{m4_do}.
+
+To make diversion management easier, M4sugar uses the concept of named
+diversions. Rather than using diversion numbers directly, it is nicer
+to associate a name with each diversion. The diversion number associated
+with a particular diversion name is an implementation detail, and a
+syntax warning is issued if a diversion number is used instead of a
+name. In general, you should not output text
+to a named diversion until after calling the appropriate initialization
+routine for your language (@code{m4_init}, @code{AS_INIT},
+ at code{AT_INIT}, @dots{}), although there are some exceptions documented
+below.
+
+M4sugar defines two named diversions.
+ at table @code
+ at item KILL
+Text written to this diversion is discarded. This is the default
+diversion once M4sugar is initialized.
+ at item GROW
+This diversion is used behind the scenes by topological sorting macros,
+such as @code{AC_REQUIRE}.
+ at end table
+
+M4sh adds several more named diversions.
+ at table @code
+ at item BINSH
+This diversion is reserved for the @samp{#!} interpreter line.
+ at item HEADER-REVISION
+This diversion holds text from @code{AC_REVISION}.
+ at item HEADER-COMMENT
+This diversion holds comments about the purpose of a file.
+ at item HEADER-COPYRIGHT
+This diversion is managed by @code{AC_COPYRIGHT}.
+ at item M4SH-SANITIZE
+This diversion contains M4sh sanitization code, used to ensure M4sh is
+executing in a reasonable shell environment.
+ at item M4SH-INIT
+This diversion contains M4sh initialization code, initializing variables
+that are required by other M4sh macros.
+ at item BODY
+This diversion contains the body of the shell code, and is the default
+diversion once M4sh is initialized.
+ at end table
+
+Autotest inherits diversions from M4sh, and changes the default
+diversion from @code{BODY} back to @code{KILL}. It also adds several
+more named diversions, with the following subset designed for developer
+use.
+ at table @code
+ at item PREPARE_TESTS
+This diversion contains initialization sequences which are executed
+after @file{atconfig} and @file{atlocal}, and after all command line
+arguments have been parsed, but prior to running any tests. It can be
+used to set up state that is required across all tests. This diversion
+will work even before @code{AT_INIT}.
+ at end table
+
+Autoconf inherits diversions from M4sh, and adds the following named
+diversions which developers can utilize.
+ at table @code
+ at item DEFAULTS
+This diversion contains shell variable assignments to set defaults that
+must be in place before arguments are parsed. This diversion is placed
+early enough in @file{configure} that it is unsafe to expand any
+autoconf macros into this diversion.
+ at item HELP_ENABLE
+If @code{AC_PRESERVE_HELP_ORDER} was used, then text placed in this
+diversion will be included as part of a quoted here-doc providing all of
+the @option{--help} output of @file{configure} related to options
+created by @code{AC_ARG_WITH} and @code{AC_ARG_ENABLE}.
+ at item INIT_PREPARE
+This diversion occurs after all command line options have been parsed,
+but prior to the main body of the @file{configure} script. This
+diversion is the last chance to insert shell code such as variable
+assignments or shell function declarations that will used by the
+expansion of other macros.
+ at end table
+
+For now, the remaining named diversions of Autoconf, Autoheader, and
+Autotest are not documented. In other words,
+intentionally outputting text into an undocumented diversion is subject
+to breakage in a future release of Autoconf.
+
+ at defmac m4_cleardivert (@var{diversion}@dots{})
+ at msindex{cleardivert}
+Permanently discard any text that has been diverted into
+ at var{diversion}.
+ at end defmac
+
+ at defmac m4_divert_once (@var{diversion}, @ovar{content})
+ at msindex{divert_once}
+Similar to @code{m4_divert_text}, except that @var{content} is only
+output to @var{diversion} if this is the first time that
+ at code{m4_divert_once} has been called with its particular arguments.
+ at end defmac
+
+ at defmac m4_divert_pop (@ovar{diversion})
+ at msindex{divert_pop}
+If provided, check that the current diversion is indeed @var{diversion}.
+Then change to the diversion located earlier on the stack, giving an
+error if an attempt is made to pop beyond the initial m4sugar diversion
+of @code{KILL}.
+ at end defmac
+
+ at defmac m4_divert_push (@var{diversion})
+ at msindex{divert_push}
+Remember the former diversion on the diversion stack, and output
+subsequent text into @var{diversion}. M4sugar maintains a diversion
+stack, and issues an error if there is not a matching pop for every
+push.
+ at end defmac
+
+ at defmac m4_divert_text (@var{diversion}, @ovar{content})
+ at msindex{divert_text}
+Output @var{content} and a newline into @var{diversion}, without
+affecting the current diversion. Shorthand for:
+ at example
+m4_divert_push([@var{diversion}])@var{content}
+m4_divert_pop([@var{diversion}])dnl
+ at end example
+
+One use of @code{m4_divert_text} is to develop two related macros, where
+macro @samp{MY_A} does the work, but adjusts what work is performed
+based on whether the optional macro @samp{MY_B} has also been expanded.
+Of course, it is possible to use @code{AC_BEFORE} within @code{MY_A} to
+require that @samp{MY_B} occurs first, if it occurs at all. But this
+imposes an ordering restriction on the user; it would be nicer if macros
+ at samp{MY_A} and @samp{MY_B} can be invoked in either order. The trick
+is to let @samp{MY_B} leave a breadcrumb in an early diversion, which
+ at samp{MY_A} can then use to determine whether @samp{MY_B} has been
+expanded.
+
+ at example
+AC_DEFUN([MY_A],
+[# various actions
+if test -n "$b_was_used"; then
+ # extra action
+fi])
+AC_DEFUN([MY_B],
+[AC_REQUIRE([MY_A])dnl
+m4_divert_text([INIT_PREPARE], [b_was_used=true])])
+ at end example
+
+ at end defmac
+
+ at defmac m4_init
+ at msindex{init}
+Initialize the M4sugar environment, setting up the default named
+diversion to be @code{KILL}.
+ at end defmac
+
+ at node Conditional constructs
+ at subsection Conditional constructs
+
+The following macros provide additional conditional constructs as
+convenience wrappers around @code{m4_if}.
+
+ at defmac m4_bmatch (@var{string}, @var{regex-1}, @var{value-1}, @
+ @ovar{regex-2}, @ovar{value-2}, @dots{}, @ovar{default})
+ at msindex{bmatch}
+The string @var{string} is repeatedly compared against a series of
+ at var{regex} arguments; if a match is found, the expansion is the
+corresponding @var{value}, otherwise, the macro moves on to the next
+ at var{regex}. If no @var{regex} match, then the result is the optional
+ at var{default}, or nothing.
+ at end defmac
+
+ at defmac m4_bpatsubsts (@var{string}, @var{regex-1}, @var{subst-1}, @
+ @ovar{regex-2}, @ovar{subst-2}, @dots{})
+ at msindex{bpatsubsts}
+The string @var{string} is altered by @var{regex-1} and @var{subst-1},
+as if by:
+ at example
+m4_bpatsubst([[@var{string}]], [@var{regex}], [@var{subst}])
+ at end example
+
+ at noindent
+The result of the substitution is then passed through the next set of
+ at var{regex} and @var{subst}, and so forth. An empty @var{subst} implies
+deletion of any matched portions in the current string. Note that this
+macro over-quotes @var{string}; this behavior is intentional, so that
+the result of each step of the recursion remains as a quoted string.
+However, it means that anchors (@samp{^} and @samp{$} in the @var{regex}
+will line up with the extra quotations, and not the characters of the
+original string. The overquoting is removed after the final
+substitution.
+ at end defmac
+
+ at defmac m4_case (@var{string}, @var{value-1}, @var{if-value-1}, @
+ @ovar{value-2}, @ovar{if-value-2}, @dots{}, @ovar{default})
+ at msindex{case}
+Test @var{string} against multiple @var{value} possibilities, resulting
+in the first @var{if-value} for a match, or in the optional
+ at var{default}. This is shorthand for:
+ at example
+m4_if([@var{string}], [@var{value-1}], [@var{if-value-1}],
+ [@var{string}], [@var{value-2}], [@var{if-value-2}], @dots{},
+ [@var{default}])
+ at end example
+ at end defmac
+
+ at defmac m4_cond (@var{test-1}, @var{value-1}, @var{if-value-1}, @
+ @ovar{test-2}, @ovar{value-2}, @ovar{if-value-2}, @dots{}, @ovar{default})
+ at msindex{cond}
+This macro was introduced in Autoconf 2.62. Similar to @code{m4_if},
+except that each @var{test} is expanded only when it is encountered.
+This is useful for short-circuiting expensive tests; while @code{m4_if}
+requires all its strings to be expanded up front before doing
+comparisons, @code{m4_cond} only expands a @var{test} when all earlier
+tests have failed.
+
+For an example, these two sequences give the same result, but in the
+case where @samp{$1} does not contain a backslash, the @code{m4_cond}
+version only expands @code{m4_index} once, instead of five times, for
+faster computation if this is a common case for @samp{$1}. Notice that
+every third argument is unquoted for @code{m4_if}, and quoted for
+ at code{m4_cond}:
+
+ at example
+m4_if(m4_index([$1], [\]), [-1], [$2],
+ m4_eval(m4_index([$1], [\\]) >= 0), [1], [$2],
+ m4_eval(m4_index([$1], [\$]) >= 0), [1], [$2],
+ m4_eval(m4_index([$1], [\`]) >= 0), [1], [$3],
+ m4_eval(m4_index([$1], [\"]) >= 0), [1], [$3],
+ [$2])
+m4_cond([m4_index([$1], [\])], [-1], [$2],
+ [m4_eval(m4_index([$1], [\\]) >= 0)], [1], [$2],
+ [m4_eval(m4_index([$1], [\$]) >= 0)], [1], [$2],
+ [m4_eval(m4_index([$1], [\`]) >= 0)], [1], [$3],
+ [m4_eval(m4_index([$1], [\"]) >= 0)], [1], [$3],
+ [$2])
+ at end example
+ at end defmac
+
+ at defmac m4_default (@var{expr-1}, @var{expr-2})
+ at defmacx m4_default_quoted (@var{expr-1}, @var{expr-2})
+ at defmacx m4_default_nblank (@var{expr-1}, @ovar{expr-2})
+ at defmacx m4_default_nblank_quoted (@var{expr-1}, @ovar{expr-2})
+ at msindex{default}
+ at msindex{default_quoted}
+ at msindex{default_nblank}
+ at msindex{default_nblank_quoted}
+If @var{expr-1} contains text, use it. Otherwise, select @var{expr-2}.
+ at code{m4_default} expands the result, while @code{m4_default_quoted}
+does not. Useful for providing a fixed default if the expression that
+results in @var{expr-1} would otherwise be empty. The difference
+between @code{m4_default} and @code{m4_default_nblank} is whether an
+argument consisting of just blanks (space, tab, newline) is
+significant. When using the expanding versions, note that an argument
+may contain text but still expand to an empty string.
+
+ at example
+m4_define([active], [ACTIVE])dnl
+m4_define([empty], [])dnl
+m4_define([demo1], [m4_default([$1], [$2])])dnl
+m4_define([demo2], [m4_default_quoted([$1], [$2])])dnl
+m4_define([demo3], [m4_default_nblank([$1], [$2])])dnl
+m4_define([demo4], [m4_default_nblank_quoted([$1], [$2])])dnl
+demo1([active], [default])
+ at result{}ACTIVE
+demo1([], [active])
+ at result{}ACTIVE
+demo1([empty], [text])
+ at result{}
+-demo1([ ], [active])-
+ at result{}- -
+demo2([active], [default])
+ at result{}active
+demo2([], [active])
+ at result{}active
+demo2([empty], [text])
+ at result{}empty
+-demo2([ ], [active])-
+ at result{}- -
+demo3([active], [default])
+ at result{}ACTIVE
+demo3([], [active])
+ at result{}ACTIVE
+demo3([empty], [text])
+ at result{}
+-demo3([ ], [active])-
+ at result{}-ACTIVE-
+demo4([active], [default])
+ at result{}active
+demo4([], [active])
+ at result{}active
+demo4([empty], [text])
+ at result{}empty
+-demo4([ ], [active])-
+ at result{}-active-
+ at end example
+ at end defmac
+
+ at defmac m4_define_default (@var{macro}, @ovar{default-definition})
+ at msindex{define_default}
+If @var{macro} does not already have a definition, then define it to
+ at var{default-definition}.
+ at end defmac
+
+ at defmac m4_ifblank (@var{cond}, @ovar{if-blank}, @ovar{if-text})
+ at defmacx m4_ifnblank (@var{cond}, @ovar{if-text}, @ovar{if-blank})
+ at msindex{ifblank}
+ at msindex{ifnblank}
+If @var{cond} is empty or consists only of blanks (space, tab, newline),
+then expand @var{if-blank}; otherwise, expand @var{if-text}. Two
+variants exist, in order to make it easier to select the correct logical
+sense when using only two parameters. Note that this is more efficient
+than the equivalent behavior of:
+ at example
+m4_ifval(m4_normalize([@var{cond}]), @var{if-text}, @var{if-blank})
+ at end example
+ at end defmac
+
+ at defmac m4_ifndef (@var{macro}, @var{if-not-defined}, @ovar{if-defined})
+ at msindex{ifndef}
+This is shorthand for:
+ at example
+m4_ifdef([@var{macro}], [@var{if-defined}], [@var{if-not-defined}])
+ at end example
+ at end defmac
+
+ at defmac m4_ifset (@var{macro}, @ovar{if-true}, @ovar{if-false})
+ at msindex{ifset}
+If @var{macro} is undefined, or is defined as the empty string, expand
+to @var{if-false}. Otherwise, expands to @var{if-true}. Similar to:
+ at example
+m4_ifval(m4_defn([@var{macro}]), [@var{if-true}], [@var{if-false}])
+ at end example
+ at noindent
+except that it is not an error if @var{macro} is undefined.
+ at end defmac
+
+ at defmac m4_ifval (@var{cond}, @ovar{if-true}, @ovar{if-false})
+ at msindex{ifval}
+Expands to @var{if-true} if @var{cond} is not empty, otherwise to
+ at var{if-false}. This is shorthand for:
+ at example
+m4_if([@var{cond}], [], [@var{if-false}], [@var{if-true}])
+ at end example
+ at end defmac
+
+ at defmac m4_ifvaln (@var{cond}, @ovar{if-true}, @ovar{if-false})
+ at msindex{ifvaln}
+Similar to @code{m4_ifval}, except guarantee that a newline is present
+after any non-empty expansion. Often followed by @code{dnl}.
+ at end defmac
+
+ at defmac m4_n (@var{text})
+ at msindex{n}
+Expand to @var{text}, and add a newline if @var{text} is not empty.
+Often followed by @code{dnl}.
+ at end defmac
+
+
+ at node Looping constructs
+ at subsection Looping constructs
+
+The following macros are useful in implementing recursive algorithms in
+M4, including loop operations. An M4 list is formed by quoting a list
+of quoted elements; generally the lists are comma-separated, although
+ at code{m4_foreach_w} is whitespace-separated. For example, the list
+ at samp{[[a], [b,c]]} contains two elements: @samp{[a]} and @samp{[b,c]}.
+It is common to see lists with unquoted elements when those elements are
+not likely to be macro names, as in @samp{[fputc_unlocked,
+fgetc_unlocked]}.
+
+Although not generally recommended, it is possible for quoted lists to
+have side effects; all side effects are expanded only once, and prior to
+visiting any list element. On the other hand, the fact that unquoted
+macros are expanded exactly once means that macros without side effects
+can be used to generate lists. For example,
+
+ at example
+m4_foreach([i], [[1], [2], [3]m4_errprintn([hi])], [i])
+ at error{}hi
+ at result{}123
+m4_define([list], [[1], [2], [3]])
+ at result{}
+m4_foreach([i], [list], [i])
+ at result{}123
+ at end example
+
+ at defmac m4_argn (@var{n}, @ovar{arg}@dots{})
+ at msindex{argn}
+Extracts argument @var{n} (larger than 0) from the remaining arguments.
+If there are too few arguments, the empty string is used. For any
+ at var{n} besides 1, this is more efficient than the similar
+ at samp{m4_car(m4_shiftn([@var{n}], [], [@var{arg}@dots{}]))}.
+ at end defmac
+
+ at defmac m4_car (@var{arg}@dots{})
+ at msindex{car}
+Expands to the quoted first @var{arg}. Can be used with @code{m4_cdr}
+to recursively iterate
+through a list. Generally, when using quoted lists of quoted elements,
+ at code{m4_car} should be called without any extra quotes.
+ at end defmac
+
+ at defmac m4_cdr (@var{arg}@dots{})
+ at msindex{cdr}
+Expands to a quoted list of all but the first @var{arg}, or the empty
+string if there was only one argument. Generally, when using quoted
+lists of quoted elements, @code{m4_cdr} should be called without any
+extra quotes.
+
+For example, this is a simple implementation of @code{m4_map}; note how
+each iteration checks for the end of recursion, then merely applies the
+first argument to the first element of the list, then repeats with the
+rest of the list. (The actual implementation in M4sugar is a bit more
+involved, to gain some speed and share code with @code{m4_map_sep}, and
+also to avoid expanding side effects in @samp{$2} twice).
+ at example
+m4_define([m4_map], [m4_ifval([$2],
+ [m4_apply([$1], m4_car($2))[]$0([$1], m4_cdr($2))])])dnl
+m4_map([ m4_eval], [[[1]], [[1+1]], [[10],[16]]])
+ at result{} 1 2 a
+ at end example
+ at end defmac
+
+ at defmac m4_for (@var{var}, @var{first}, @var{last}, @ovar{step}, @
+ @var{expression})
+ at msindex{for}
+Loop over the numeric values between @var{first} and @var{last}
+including bounds by increments of @var{step}. For each iteration,
+expand @var{expression} with the numeric value assigned to @var{var}.
+If @var{step} is omitted, it defaults to @samp{1} or @samp{-1} depending
+on the order of the limits. If given, @var{step} has to match this
+order. The number of iterations is determined independently from
+definition of @var{var}; iteration cannot be short-circuited or
+lengthened by modifying @var{var} from within @var{expression}.
+ at end defmac
+
+ at defmac m4_foreach (@var{var}, @var{list}, @var{expression})
+ at msindex{foreach}
+Loop over the comma-separated M4 list @var{list}, assigning each value
+to @var{var}, and expand @var{expression}. The following example
+outputs two lines:
+
+ at example
+m4_foreach([myvar], [[foo], [bar, baz]],
+ [echo myvar
+])dnl
+ at result{}echo foo
+ at result{}echo bar, baz
+ at end example
+
+Note that for some forms of @var{expression}, it may be faster to use
+ at code{m4_map_args}.
+ at end defmac
+
+ at anchor{m4_foreach_w}
+ at defmac m4_foreach_w (@var{var}, @var{list}, @var{expression})
+ at msindex{foreach_w}
+Loop over the white-space-separated list @var{list}, assigning each value
+to @var{var}, and expand @var{expression}. If @var{var} is only
+referenced once in @var{expression}, it is more efficient to use
+ at code{m4_map_args_w}.
+
+The deprecated macro @code{AC_FOREACH} is an alias of
+ at code{m4_foreach_w}.
+ at end defmac
+
+ at defmac m4_map (@var{macro}, @var{list})
+ at defmacx m4_mapall (@var{macro}, @var{list})
+ at defmacx m4_map_sep (@var{macro}, @var{separator}, @var{list})
+ at defmacx m4_mapall_sep (@var{macro}, @var{separator}, @var{list})
+ at msindex{map}
+ at msindex{mapall}
+ at msindex{map_sep}
+ at msindex{mapall_sep}
+Loop over the comma separated quoted list of argument descriptions in
+ at var{list}, and invoke @var{macro} with the arguments. An argument
+description is in turn a comma-separated quoted list of quoted elements,
+suitable for @code{m4_apply}. The macros @code{m4_map} and
+ at code{m4_map_sep} ignore empty argument descriptions, while
+ at code{m4_mapall} and @code{m4_mapall_sep} invoke @var{macro} with no
+arguments. The macros @code{m4_map_sep} and @code{m4_mapall_sep}
+additionally expand @var{separator} between invocations of @var{macro}.
+
+Note that @var{separator} is expanded, unlike in @code{m4_join}. When
+separating output with commas, this means that the map result can be
+used as a series of arguments, by using a single-quoted comma as
+ at var{separator}, or as a single string, by using a double-quoted comma.
+
+ at example
+m4_map([m4_count], [])
+ at result{}
+m4_map([ m4_count], [[],
+ [[1]],
+ [[1], [2]]])
+ at result{} 1 2
+m4_mapall([ m4_count], [[],
+ [[1]],
+ [[1], [2]]])
+ at result{} 0 1 2
+m4_map_sep([m4_eval], [,], [[[1+2]],
+ [[10], [16]]])
+ at result{}3,a
+m4_map_sep([m4_echo], [,], [[[a]], [[b]]])
+ at result{}a,b
+m4_count(m4_map_sep([m4_echo], [,], [[[a]], [[b]]]))
+ at result{}2
+m4_map_sep([m4_echo], [[,]], [[[a]], [[b]]])
+ at result{}a,b
+m4_count(m4_map_sep([m4_echo], [[,]], [[[a]], [[b]]]))
+ at result{}1
+ at end example
+ at end defmac
+
+ at defmac m4_map_args (@var{macro}, @var{arg}@dots{})
+ at msindex{map_args}
+Repeatedly invoke @var{macro} with each successive @var{arg} as its only
+argument. In the following example, three solutions are presented with
+the same expansion; the solution using @code{m4_map_args} is the most
+efficient.
+ at example
+m4_define([active], [ACTIVE])dnl
+m4_foreach([var], [[plain], [active]], [ m4_echo(m4_defn([var]))])
+ at result{} plain active
+m4_map([ m4_echo], [[[plain]], [[active]]])
+ at result{} plain active
+m4_map_args([ m4_echo], [plain], [active])
+ at result{} plain active
+ at end example
+
+In cases where it is useful to operate on additional parameters besides
+the list elements, the macro @code{m4_curry} can be used in @var{macro}
+to supply the argument currying necessary to generate the desired
+argument list. In the following example, @code{list_add_n} is more
+efficient than @code{list_add_x}. On the other hand, using
+ at code{m4_map_args_sep} can be even more efficient.
+
+ at example
+m4_define([list], [[1], [2], [3]])dnl
+m4_define([add], [m4_eval(([$1]) + ([$2]))])dnl
+dnl list_add_n(N, ARG...)
+dnl Output a list consisting of each ARG added to N
+m4_define([list_add_n],
+[m4_shift(m4_map_args([,m4_curry([add], [$1])], m4_shift($@@)))])dnl
+list_add_n([1], list)
+ at result{}2,3,4
+list_add_n([2], list)
+ at result{}3,4,5
+m4_define([list_add_x],
+[m4_shift(m4_foreach([var], m4_dquote(m4_shift($@@)),
+ [,add([$1],m4_defn([var]))]))])dnl
+list_add_x([1], list)
+ at result{}2,3,4
+ at end example
+ at end defmac
+
+ at defmac m4_map_args_pair (@var{macro}, @dvar{macro-end, macro}, @
+ @var{arg}@dots{})
+ at msindex{map_args_pair}
+For every pair of arguments @var{arg}, invoke @var{macro} with two
+arguments. If there is an odd number of arguments, invoke
+ at var{macro-end}, which defaults to @var{macro}, with the remaining
+argument.
+
+ at example
+m4_map_args_pair([, m4_reverse], [], [1], [2], [3])
+ at result{}, 2, 1, 3
+m4_map_args_pair([, m4_reverse], [, m4_dquote], [1], [2], [3])
+ at result{}, 2, 1, [3]
+m4_map_args_pair([, m4_reverse], [, m4_dquote], [1], [2], [3], [4])
+ at result{}, 2, 1, 4, 3
+ at end example
+ at end defmac
+
+ at defmac m4_map_args_sep (@ovar{pre}, @ovar{post}, @ovar{sep}, @var{arg}@dots{})
+ at msindex{map_args_sep}
+Expand the sequence @code{@var{pre}[@var{arg}]@var{post}} for each
+argument, additionally expanding @var{sep} between arguments. One
+common use of this macro is constructing a macro call, where the opening
+and closing parentheses are split between @var{pre} and @var{post}; in
+particular, @code{m4_map_args([@var{macro}], [@var{arg}])} is equivalent
+to @code{m4_map_args_sep([@var{macro}(], [)], [], [@var{arg}])}. This
+macro provides the most efficient means for iterating over an arbitrary
+list of arguments, particularly when repeatedly constructing a macro
+call with more arguments than @var{arg}.
+ at end defmac
+
+ at defmac m4_map_args_w (@var{string}, @ovar{pre}, @ovar{post}, @ovar{sep})
+ at msindex{map_args_w}
+Expand the sequence @code{@var{pre}[word]@var{post}} for each word in
+the whitespace-separated @var{string}, additionally expanding @var{sep}
+between words. This macro provides the most efficient means for
+iterating over a whitespace-separated string. In particular,
+ at code{m4_map_args_w([@var{string}], [@var{action}(], [)])} is more
+efficient than @code{m4_foreach_w([var], [@var{string}],
+[@var{action}(m4_defn([var]))])}.
+ at end defmac
+
+ at defmac m4_shiftn (@var{count}, @dots{})
+ at defmacx m4_shift2 (@dots{})
+ at defmacx m4_shift3 (@dots{})
+ at msindex{shift2}
+ at msindex{shift3}
+ at msindex{shiftn}
+ at code{m4_shiftn} performs @var{count} iterations of @code{m4_shift},
+along with validation that enough arguments were passed in to match the
+shift count, and that the count is positive. @code{m4_shift2} and
+ at code{m4_shift3} are specializations
+of @code{m4_shiftn}, introduced in Autoconf 2.62, and are more efficient
+for two and three shifts, respectively.
+ at end defmac
+
+ at defmac m4_stack_foreach (@var{macro}, @var{action})
+ at defmacx m4_stack_foreach_lifo (@var{macro}, @var{action})
+ at msindex{stack_foreach}
+ at msindex{stack_foreach_lifo}
+For each of the @code{m4_pushdef} definitions of @var{macro}, expand
+ at var{action} with the single argument of a definition of @var{macro}.
+ at code{m4_stack_foreach} starts with the oldest definition, while
+ at code{m4_stack_foreach_lifo} starts with the current definition.
+ at var{action} should not push or pop definitions of @var{macro}, nor is
+there any guarantee that the current definition of @var{macro} matches
+the argument that was passed to @var{action}. The macro @code{m4_curry}
+can be used if @var{action} needs more than one argument, although in
+that case it is more efficient to use @var{m4_stack_foreach_sep}.
+
+Due to technical limitations, there are a few low-level m4sugar
+functions, such as @code{m4_pushdef}, that cannot be used as the
+ at var{macro} argument.
+
+ at example
+m4_pushdef([a], [1])m4_pushdef([a], [2])dnl
+m4_stack_foreach([a], [ m4_incr])
+ at result{} 2 3
+m4_stack_foreach_lifo([a], [ m4_curry([m4_substr], [abcd])])
+ at result{} cd bcd
+ at end example
+ at end defmac
+
+ at defmac m4_stack_foreach_sep (@var{macro}, @ovar{pre}, @ovar{post}, @ovar{sep})
+ at defmacx m4_stack_foreach_sep_lifo (@var{macro}, @ovar{pre}, @ovar{post}, @
+ @ovar{sep})
+ at msindex{stack_foreach_sep}
+ at msindex{stack_foreach_sep_lifo}
+Expand the sequence @code{@var{pre}[definition]@var{post}} for each
+ at code{m4_pushdef} definition of @var{macro}, additionally expanding
+ at var{sep} between definitions. @code{m4_stack_foreach_sep} visits the
+oldest definition first, while @code{m4_stack_foreach_sep_lifo} visits
+the current definition first. This macro provides the most efficient
+means for iterating over a pushdef stack. In particular,
+ at code{m4_stack_foreach([@var{macro}], [@var{action}])} is short for
+ at code{m4_stack_foreach_sep([@var{macro}], [@var{action}(], [)])}.
+ at end defmac
+
+ at node Evaluation Macros
+ at subsection Evaluation Macros
+
+The following macros give some control over the order of the evaluation
+by adding or removing levels of quotes.
+
+ at defmac m4_apply (@var{macro}, @var{list})
+ at msindex{apply}
+Apply the elements of the quoted, comma-separated @var{list} as the
+arguments to @var{macro}. If @var{list} is empty, invoke @var{macro}
+without arguments. Note the difference between @code{m4_indir}, which
+expects its first argument to be a macro name but can use names that are
+otherwise invalid, and @code{m4_apply}, where @var{macro} can contain
+other text, but must end in a valid macro name.
+ at example
+m4_apply([m4_count], [])
+ at result{}0
+m4_apply([m4_count], [[]])
+ at result{}1
+m4_apply([m4_count], [[1], [2]])
+ at result{}2
+m4_apply([m4_join], [[|], [1], [2]])
+ at result{}1|2
+ at end example
+ at end defmac
+
+ at defmac m4_count (@var{arg}, @dots{})
+ at msindex{count}
+This macro returns the decimal count of the number of arguments it was
+passed.
+ at end defmac
+
+ at defmac m4_curry (@var{macro}, @var{arg}@dots{})
+ at msindex{curry}
+This macro performs argument currying. The expansion of this macro is
+another macro name that expects exactly one argument; that argument is
+then appended to the @var{arg} list, and then @var{macro} is expanded
+with the resulting argument list.
+
+ at example
+m4_curry([m4_curry], [m4_reverse], [1])([2])([3])
+ at result{}3, 2, 1
+ at end example
+
+Unfortunately, due to a limitation in M4 1.4.x, it is not possible to
+pass the definition of a builtin macro as the argument to the output of
+ at code{m4_curry}; the empty string is used instead of the builtin token.
+This behavior is rectified by using M4 1.6 or newer.
+ at end defmac
+
+ at defmac m4_do (@var{arg}, @dots{})
+ at msindex{do}
+This macro loops over its arguments and expands each @var{arg} in
+sequence. Its main use is for readability; it allows the use of
+indentation and fewer @code{dnl} to result in the same expansion. This
+macro guarantees that no expansion will be concatenated with subsequent
+text; to achieve full concatenation, use @code{m4_unquote(m4_join([],
+ at var{arg at dots{}}))}.
+
+ at example
+m4_define([ab],[1])m4_define([bc],[2])m4_define([abc],[3])dnl
+m4_do([a],[b])c
+ at result{}abc
+m4_unquote(m4_join([],[a],[b]))c
+ at result{}3
+m4_define([a],[A])m4_define([b],[B])m4_define([c],[C])dnl
+m4_define([AB],[4])m4_define([BC],[5])m4_define([ABC],[6])dnl
+m4_do([a],[b])c
+ at result{}ABC
+m4_unquote(m4_join([],[a],[b]))c
+ at result{}3
+ at end example
+ at end defmac
+
+ at defmac m4_dquote (@var{arg}, @dots{})
+ at msindex{dquote}
+Return the arguments as a quoted list of quoted arguments.
+Conveniently, if there is just one @var{arg}, this effectively adds a
+level of quoting.
+ at end defmac
+
+ at defmac m4_dquote_elt (@var{arg}, @dots{})
+ at msindex{dquote_elt}
+Return the arguments as a series of double-quoted arguments. Whereas
+ at code{m4_dquote} returns a single argument, @code{m4_dquote_elt} returns
+as many arguments as it was passed.
+ at end defmac
+
+ at defmac m4_echo (@var{arg}, @dots{})
+ at msindex{echo}
+Return the arguments, with the same level of quoting. Other than
+discarding whitespace after unquoted commas, this macro is a no-op.
+ at end defmac
+
+ at defmac m4_expand (@var{arg})
+ at msindex{expand}
+Return the expansion of @var{arg} as a quoted string. Whereas
+ at code{m4_quote} is designed to collect expanded text into a single
+argument, @code{m4_expand} is designed to perform one level of expansion
+on quoted text. One distinction is in the treatment of whitespace
+following a comma in the original @var{arg}. Any time multiple
+arguments are collected into one with @code{m4_quote}, the M4 argument
+collection rules discard the whitespace. However, with @code{m4_expand},
+whitespace is preserved, even after the expansion of macros contained in
+ at var{arg}. Additionally, @code{m4_expand} is able to expand text that
+would involve an unterminated comment, whereas expanding that same text
+as the argument to @code{m4_quote} runs into difficulty in finding the
+end of the argument. Since manipulating diversions during argument
+collection is inherently unsafe, @code{m4_expand} issues an error if
+ at var{arg} attempts to change the current diversion (@pxref{Diversion
+support}).
+
+ at example
+m4_define([active], [ACT, IVE])dnl
+m4_define([active2], [[ACT, IVE]])dnl
+m4_quote(active, active)
+ at result{}ACT,IVE,ACT,IVE
+m4_expand([active, active])
+ at result{}ACT, IVE, ACT, IVE
+m4_quote(active2, active2)
+ at result{}ACT, IVE,ACT, IVE
+m4_expand([active2, active2])
+ at result{}ACT, IVE, ACT, IVE
+m4_expand([# m4_echo])
+ at result{}# m4_echo
+m4_quote(# m4_echo)
+)
+ at result{}# m4_echo)
+ at result{}
+ at end example
+
+Note that @code{m4_expand} cannot handle an @var{arg} that expands to
+literal unbalanced quotes, but that quadrigraphs can be used when
+unbalanced output is necessary. Likewise, unbalanced parentheses should
+be supplied with double quoting or a quadrigraph.
+
+ at example
+m4_define([pattern], [[!@@<:@@]])dnl
+m4_define([bar], [BAR])dnl
+m4_expand([case $foo in
+ m4_defn([pattern])@@:@}@@ bar ;;
+ *[)] blah ;;
+esac])
+ at result{}case $foo in
+ at result{} [![]) BAR ;;
+ at result{} *) blah ;;
+ at result{}esac
+ at end example
+ at end defmac
+
+ at defmac m4_ignore (@dots{})
+ at msindex{ignore}
+This macro was introduced in Autoconf 2.62. Expands to nothing,
+ignoring all of its arguments. By itself, this isn't very useful.
+However, it can be used to conditionally ignore an arbitrary number of
+arguments, by deciding which macro name to apply to a list of arguments.
+ at example
+dnl foo outputs a message only if [debug] is defined.
+m4_define([foo],
+[m4_ifdef([debug],[AC_MSG_NOTICE],[m4_ignore])([debug message])])
+ at end example
+
+Note that for earlier versions of Autoconf, the macro @code{__gnu__} can
+serve the same purpose, although it is less readable.
+ at end defmac
+
+ at defmac m4_make_list (@var{arg}, @dots{})
+ at msindex{make_list}
+This macro exists to aid debugging of M4sugar algorithms. Its net
+effect is similar to @code{m4_dquote}---it produces a quoted list of
+quoted arguments, for each @var{arg}. The difference is that this
+version uses a comma-newline separator instead of just comma, to improve
+readability of the list; with the result that it is less efficient than
+ at code{m4_dquote}.
+ at example
+m4_define([zero],[0])m4_define([one],[1])m4_define([two],[2])dnl
+m4_dquote(zero, [one], [[two]])
+ at result{}[0],[one],[[two]]
+m4_make_list(zero, [one], [[two]])
+ at result{}[0],
+ at result{}[one],
+ at result{}[[two]]
+m4_foreach([number], m4_dquote(zero, [one], [[two]]), [ number])
+ at result{} 0 1 two
+m4_foreach([number], m4_make_list(zero, [one], [[two]]), [ number])
+ at result{} 0 1 two
+ at end example
+ at end defmac
+
+ at c m4_noquote is too dangerous to document - it invokes macros that
+ at c probably rely on @samp{[]} nested quoting for proper operation. The
+ at c user should generally prefer m4_unquote instead.
+
+ at defmac m4_quote (@var{arg}, @dots{})
+ at msindex{quote}
+Return the arguments as a single entity, i.e., wrap them into a pair of
+quotes. This effectively collapses multiple arguments into one,
+although it loses whitespace after unquoted commas in the process.
+ at end defmac
+
+ at defmac m4_reverse (@var{arg}, @dots{})
+ at msindex{reverse}
+Outputs each argument with the same level of quoting, but in reverse
+order, and with space following each comma for readability.
+
+ at example
+m4_define([active], [ACT,IVE])
+ at result{}
+m4_reverse(active, [active])
+ at result{}active, IVE, ACT
+ at end example
+ at end defmac
+
+ at defmac m4_unquote (@var{arg}, @dots{})
+ at msindex{unquote}
+This macro was introduced in Autoconf 2.62. Expand each argument,
+separated by commas. For a single @var{arg}, this effectively removes a
+layer of quoting, and @code{m4_unquote([@var{arg}])} is more efficient
+than the equivalent @code{m4_do([@var{arg}])}. For multiple arguments,
+this results in an unquoted list of expansions. This is commonly used
+with @code{m4_split}, in order to convert a single quoted list into a
+series of quoted elements.
+ at end defmac
+
+The following example aims at emphasizing the difference between several
+scenarios: not using these macros, using @code{m4_defn}, using
+ at code{m4_quote}, using @code{m4_dquote}, and using @code{m4_expand}.
+
+ at example
+$ @kbd{cat example.m4}
+dnl Overquote, so that quotes are visible.
+m4_define([show], [$[]1 = [$1], $[]@@ = [$@@]])
+m4_define([a], [A])
+m4_define([mkargs], [1, 2[,] 3])
+m4_define([arg1], [[$1]])
+m4_divert([0])dnl
+show(a, b)
+show([a, b])
+show(m4_quote(a, b))
+show(m4_dquote(a, b))
+show(m4_expand([a, b]))
+
+arg1(mkargs)
+arg1([mkargs])
+arg1(m4_defn([mkargs]))
+arg1(m4_quote(mkargs))
+arg1(m4_dquote(mkargs))
+arg1(m4_expand([mkargs]))
+$ @kbd{autom4te -l m4sugar example.m4}
+$1 = A, $@@ = [A],[b]
+$1 = a, b, $@@ = [a, b]
+$1 = A,b, $@@ = [A,b]
+$1 = [A],[b], $@@ = [[A],[b]]
+$1 = A, b, $@@ = [A, b]
+
+1
+mkargs
+1, 2[,] 3
+1,2, 3
+[1],[2, 3]
+1, 2, 3
+ at end example
+
+
+ at node Text processing Macros
+ at subsection String manipulation in M4
+
+The following macros may be used to manipulate strings in M4. Many of
+the macros in this section intentionally result in quoted strings as
+output, rather than subjecting the arguments to further expansions. As
+a result, if you are manipulating text that contains active M4
+characters, the arguments are passed with single quoting rather than
+double.
+
+ at defmac m4_append (@var{macro-name}, @var{string}, @ovar{separator})
+ at defmacx m4_append_uniq (@var{macro-name}, @var{string}, @ovar{separator} @
+ @ovar{if-uniq}, @ovar{if-duplicate})
+ at msindex{append}
+ at msindex{append_uniq}
+Redefine @var{macro-name} to its former contents with @var{separator}
+and @var{string} added at the end. If @var{macro-name} was undefined
+before (but not if it was defined but empty), then no @var{separator} is
+added. As of Autoconf 2.62, neither @var{string} nor @var{separator}
+are expanded during this macro; instead, they are expanded when
+ at var{macro-name} is invoked.
+
+ at code{m4_append} can be used to grow strings, and @code{m4_append_uniq}
+to grow strings without duplicating substrings. Additionally,
+ at code{m4_append_uniq} takes two optional parameters as of Autoconf 2.62;
+ at var{if-uniq} is expanded if @var{string} was appended, and
+ at var{if-duplicate} is expanded if @var{string} was already present.
+Also, @code{m4_append_uniq} warns if @var{separator} is not empty, but
+occurs within @var{string}, since that can lead to duplicates.
+
+Note that @code{m4_append} can scale linearly in the length of the final
+string, depending on the quality of the underlying M4 implementation,
+while @code{m4_append_uniq} has an inherent quadratic scaling factor.
+If an algorithm can tolerate duplicates in the final string, use the
+former for speed. If duplicates must be avoided, consider using
+ at code{m4_set_add} instead (@pxref{Set manipulation Macros}).
+
+ at example
+m4_define([active], [ACTIVE])dnl
+m4_append([sentence], [This is an])dnl
+m4_append([sentence], [ active ])dnl
+m4_append([sentence], [symbol.])dnl
+sentence
+ at result{}This is an ACTIVE symbol.
+m4_undefine([active])dnl
+ at result{}This is an active symbol.
+m4_append_uniq([list], [one], [, ], [new], [existing])
+ at result{}new
+m4_append_uniq([list], [one], [, ], [new], [existing])
+ at result{}existing
+m4_append_uniq([list], [two], [, ], [new], [existing])
+ at result{}new
+m4_append_uniq([list], [three], [, ], [new], [existing])
+ at result{}new
+m4_append_uniq([list], [two], [, ], [new], [existing])
+ at result{}existing
+list
+ at result{}one, two, three
+m4_dquote(list)
+ at result{}[one],[two],[three]
+m4_append([list2], [one], [[, ]])dnl
+m4_append_uniq([list2], [two], [[, ]])dnl
+m4_append([list2], [three], [[, ]])dnl
+list2
+ at result{}one, two, three
+m4_dquote(list2)
+ at result{}[one, two, three]
+ at end example
+ at end defmac
+
+ at defmac m4_append_uniq_w (@var{macro-name}, @var{strings})
+ at msindex{append_uniq_w}
+This macro was introduced in Autoconf 2.62. It is similar to
+ at code{m4_append_uniq}, but treats @var{strings} as a whitespace
+separated list of words to append, and only appends unique words.
+ at var{macro-name} is updated with a single space between new words.
+ at example
+m4_append_uniq_w([numbers], [1 1 2])dnl
+m4_append_uniq_w([numbers], [ 2 3 ])dnl
+numbers
+ at result{}1 2 3
+ at end example
+ at end defmac
+
+ at defmac m4_chomp (@var{string})
+ at defmacx m4_chomp_all (@var{string})
+ at msindex{chomp}
+ at msindex{chomp_all}
+Output @var{string} in quotes, but without a trailing newline. The
+macro @code{m4_chomp} is slightly faster, and removes at most one
+newline; the macro @code{m4_chomp_all} removes all consecutive trailing
+newlines. Unlike @code{m4_flatten}, embedded newlines are left intact,
+and backslash does not influence the result.
+ at end defmac
+
+ at defmac m4_combine (@ovar{separator}, @var{prefix-list}, @ovar{infix}, @
+ @var{suffix-1}, @ovar{suffix-2}, @dots{})
+ at msindex{combine}
+This macro produces a quoted string containing the pairwise combination
+of every element of the quoted, comma-separated @var{prefix-list}, and
+every element from the @var{suffix} arguments. Each pairwise
+combination is joined with @var{infix} in the middle, and successive
+pairs are joined by @var{separator}. No expansion occurs on any of the
+arguments. No output occurs if either the @var{prefix} or @var{suffix}
+list is empty, but the lists can contain empty elements.
+ at example
+m4_define([a], [oops])dnl
+m4_combine([, ], [[a], [b], [c]], [-], [1], [2], [3])
+ at result{}a-1, a-2, a-3, b-1, b-2, b-3, c-1, c-2, c-3
+m4_combine([, ], [[a], [b]], [-])
+ at result{}
+m4_combine([, ], [[a], [b]], [-], [])
+ at result{}a-, b-
+m4_combine([, ], [], [-], [1], [2])
+ at result{}
+m4_combine([, ], [[]], [-], [1], [2])
+ at result{}-1, -2
+ at end example
+ at end defmac
+
+ at defmac m4_escape (@var{string})
+ at msindex{escape}
+Convert all instances of @samp{[}, @samp{]}, @samp{#}, and @samp{$}
+within @var{string} into their respective quadrigraphs. The result is
+still a quoted string.
+ at end defmac
+
+ at defmac m4_flatten (@var{string})
+ at msindex{flatten}
+Flatten @var{string} into a single line. Delete all backslash-newline
+pairs, and replace all remaining newlines with a space. The result is
+still a quoted string.
+ at end defmac
+
+ at defmac m4_join (@ovar{separator}, @var{args}@dots{})
+ at defmacx m4_joinall (@ovar{separator}, @var{args}@dots{})
+ at msindex{join}
+ at msindex{joinall}
+Concatenate each @var{arg}, separated by @var{separator}.
+ at code{joinall} uses every argument, while @code{join} omits empty
+arguments so that there are no back-to-back separators in the output.
+The result is a quoted string.
+ at example
+m4_define([active], [ACTIVE])dnl
+m4_join([|], [one], [], [active], [two])
+ at result{}one|active|two
+m4_joinall([|], [one], [], [active], [two])
+ at result{}one||active|two
+ at end example
+
+Note that if all you intend to do is join @var{args} with commas between
+them, to form a quoted list suitable for @code{m4_foreach}, it is more
+efficient to use @code{m4_dquote}.
+ at end defmac
+
+ at defmac m4_newline (@ovar{text})
+ at msindex{newline}
+This macro was introduced in Autoconf 2.62, and expands to a newline,
+followed by any @var{text}.
+It is primarily useful for maintaining macro formatting, and ensuring
+that M4 does not discard leading whitespace during argument collection.
+ at end defmac
+
+ at defmac m4_normalize (@var{string})
+ at msindex{normalize}
+Remove leading and trailing spaces and tabs, sequences of
+backslash-then-newline, and replace multiple spaces, tabs, and newlines
+with a single space. This is a combination of @code{m4_flatten} and
+ at code{m4_strip}. To determine if @var{string} consists only of bytes
+that would be removed by @code{m4_normalize}, you can use
+ at code{m4_ifblank}.
+ at end defmac
+
+ at defmac m4_re_escape (@var{string})
+ at msindex{re_escape}
+Backslash-escape all characters in @var{string} that are active in
+regexps.
+ at end defmac
+
+ at c We cannot use @dvar because the macro expansion mistreats backslashes.
+ at defmac m4_split (@var{string}, @r{[}@var{regexp} = @samp{[\t ]+}@r{]})
+ at msindex{split}
+Split @var{string} into an M4 list of elements quoted by @samp{[} and
+ at samp{]}, while keeping white space at the beginning and at the end.
+If @var{regexp} is given, use it instead of @samp{[\t ]+} for splitting.
+If @var{string} is empty, the result is an empty list.
+ at end defmac
+
+ at defmac m4_strip (@var{string})
+ at msindex{strip}
+Strip whitespace from @var{string}. Sequences of spaces and tabs are
+reduced to a single space, then leading and trailing spaces are removed.
+The result is still a quoted string. Note that this does not interfere
+with newlines; if you want newlines stripped as well, consider
+ at code{m4_flatten}, or do it all at once with @code{m4_normalize}. To
+quickly test if @var{string} has only whitespace, use @code{m4_ifblank}.
+ at end defmac
+
+ at defmac m4_text_box (@var{message}, @dvar{frame, -})
+ at msindex{text_box}
+Add a text box around @var{message}, using @var{frame} as the border
+character above and below the message. The @var{frame} argument must be
+a single byte, and does not support quadrigraphs.
+The frame correctly accounts for
+the subsequent expansion of @var{message}. For example:
+ at example
+m4_define([macro], [abc])dnl
+m4_text_box([macro])
+ at result{}## --- ##
+ at result{}## abc ##
+ at result{}## --- ##
+ at end example
+
+The @var{message} must contain balanced quotes and parentheses, although
+quadrigraphs can be used to work around this.
+ at end defmac
+
+ at defmac m4_text_wrap (@var{string}, @ovar{prefix}, @
+ @dvar{prefix1, @var{prefix}}, @dvar{width, 79})
+ at msindex{text_wrap}
+Break @var{string} into a series of whitespace-separated words, then
+output those words separated by spaces, and wrapping lines any time the
+output would exceed @var{width} columns. If given, @var{prefix1} begins
+the first line, and @var{prefix} begins all wrapped lines. If
+ at var{prefix1} is longer than @var{prefix}, then the first line consists
+of just @var{prefix1}. If @var{prefix} is longer than @var{prefix1},
+padding is inserted so that the first word of @var{string} begins at the
+same indentation as all wrapped lines. Note that using literal tab
+characters in any of the arguments will interfere with the calculation
+of width. No expansions occur on @var{prefix}, @var{prefix1}, or the
+words of @var{string}, although quadrigraphs are recognized.
+
+For some examples:
+ at example
+m4_text_wrap([Short string */], [ ], [/* ], [20])
+ at result{}/* Short string */
+m4_text_wrap([Much longer string */], [ ], [/* ], [20])
+ at result{}/* Much longer
+ at result{} string */
+m4_text_wrap([Short doc.], [ ], [ --short ], [30])
+ at result{} --short Short doc.
+m4_text_wrap([Short doc.], [ ], [ --too-wide ], [30])
+ at result{} --too-wide
+ at result{} Short doc.
+m4_text_wrap([Super long documentation.], [ ],
+ [ --too-wide ], 30)
+ at result{} --too-wide
+ at result{} Super long
+ at result{} documentation.
+ at end example
+ at end defmac
+
+ at defmac m4_tolower (@var{string})
+ at defmacx m4_toupper (@var{string})
+ at msindex{tolower}
+ at msindex{toupper}
+Return @var{string} with letters converted to upper or lower case,
+respectively.
+ at end defmac
+
+ at node Number processing Macros
+ at subsection Arithmetic computation in M4
+
+The following macros facilitate integer arithmetic operations.
+Where a parameter is documented as taking an arithmetic expression, you
+can use anything that can be parsed by @code{m4_eval}.
+
+ at defmac m4_cmp (@var{expr-1}, @var{expr-2})
+ at msindex{cmp}
+Compare the arithmetic expressions @var{expr-1} and @var{expr-2}, and
+expand to @samp{-1} if @var{expr-1} is smaller, @samp{0} if they are
+equal, and @samp{1} if @var{expr-1} is larger.
+ at end defmac
+
+ at defmac m4_list_cmp (@var{list-1}, @var{list-2})
+ at msindex{list_cmp}
+Compare the two M4 lists consisting of comma-separated arithmetic
+expressions, left to right. Expand to @samp{-1} for the first element
+pairing where the value from @var{list-1} is smaller, @samp{1} where the
+value from @var{list-2} is smaller, or @samp{0} if both lists have the
+same values. If one list is shorter than the other, the remaining
+elements of the longer list are compared against zero.
+ at example
+m4_list_cmp([1, 0], [1])
+ at result{}0
+m4_list_cmp([1, [1 * 0]], [1, 0])
+ at result{}0
+m4_list_cmp([1, 2], [1, 0])
+ at result{}1
+m4_list_cmp([1, [1+1], 3],[1, 2])
+ at result{}1
+m4_list_cmp([1, 2, -3], [1, 2])
+ at result{}-1
+m4_list_cmp([1, 0], [1, 2])
+ at result{}-1
+m4_list_cmp([1], [1, 2])
+ at result{}-1
+ at end example
+ at end defmac
+
+ at defmac m4_max (@var{arg}, @dots{})
+ at msindex{max}
+This macro was introduced in Autoconf 2.62. Expand to the decimal value
+of the maximum arithmetic expression among all the arguments.
+ at end defmac
+
+ at defmac m4_min (@var{arg}, @dots{})
+ at msindex{min}
+This macro was introduced in Autoconf 2.62. Expand to the decimal value
+of the minimum arithmetic expression among all the arguments.
+ at end defmac
+
+ at defmac m4_sign (@var{expr})
+ at msindex{sign}
+Expand to @samp{-1} if the arithmetic expression @var{expr} is negative,
+ at samp{1} if it is positive, and @samp{0} if it is zero.
+ at end defmac
+
+ at anchor{m4_version_compare}
+ at defmac m4_version_compare (@var{version-1}, @var{version-2})
+ at msindex{version_compare}
+This macro was introduced in Autoconf 2.53, but had a number of
+usability limitations that were not lifted until Autoconf 2.62. Compare
+the version strings @var{version-1} and @var{version-2}, and expand to
+ at samp{-1} if @var{version-1} is smaller, @samp{0} if they are the same,
+or @samp{1} @var{version-2} is smaller. Version strings must be a list
+of elements separated by @samp{.}, @samp{,} or @samp{-}, where each
+element is a number along with optional case-insensitive letters
+designating beta releases. The comparison stops at the leftmost element
+that contains a difference, although a 0 element compares equal to a
+missing element.
+
+It is permissible to include commit identifiers in @var{version}, such
+as an abbreviated SHA1 of the commit, provided there is still a
+monotonically increasing prefix to allow for accurate version-based
+comparisons. For example, this paragraph was written when the
+development snapshot of autoconf claimed to be at version
+ at samp{2.61a-248-dc51}, or 248 commits after the 2.61a release, with an
+abbreviated commit identification of @samp{dc51}.
+
+ at example
+m4_version_compare([1.1], [2.0])
+ at result{}-1
+m4_version_compare([2.0b], [2.0a])
+ at result{}1
+m4_version_compare([1.1.1], [1.1.1a])
+ at result{}-1
+m4_version_compare([1.2], [1.1.1a])
+ at result{}1
+m4_version_compare([1.0], [1])
+ at result{}0
+m4_version_compare([1.1pre], [1.1PRE])
+ at result{}0
+m4_version_compare([1.1a], [1,10])
+ at result{}-1
+m4_version_compare([2.61a], [2.61a-248-dc51])
+ at result{}-1
+m4_version_compare([2.61b], [2.61a-248-dc51])
+ at result{}1
+ at end example
+ at end defmac
+
+ at defmac m4_version_prereq (@var{version}, @ovar{if-new-enough}, @
+ @dvar{if-old, m4_fatal})
+ at msindex{version_prereq}
+Compares @var{version} against the version of Autoconf currently
+running. If the running version is at @var{version} or newer, expand
+ at var{if-new-enough}, but if @var{version} is larger than the version
+currently executing, expand @var{if-old}, which defaults to printing an
+error message and exiting m4sugar with status 63. When given only one
+argument, this behaves like @code{AC_PREREQ} (@pxref{Versioning}).
+Remember that the autoconf philosophy favors feature checks over version
+checks.
+ at end defmac
+
+ at node Set manipulation Macros
+ at subsection Set manipulation in M4
+ at cindex Set manipulation
+ at cindex Data structure, set
+ at cindex Unordered set manipulation
+
+Sometimes, it is necessary to track a set of data, where the order does
+not matter and where there are no duplicates in the set. The following
+macros facilitate set manipulations. Each set is an opaque object,
+which can only be accessed via these basic operations. The underlying
+implementation guarantees linear scaling for set creation, which is more
+efficient than using the quadratic @code{m4_append_uniq}. Both set
+names and values can be arbitrary strings, except for unbalanced quotes.
+This implementation ties up memory for removed elements until the next
+operation that must traverse all the elements of a set; and although
+that may slow down some operations until the memory for removed elements
+is pruned, it still guarantees linear performance.
+
+ at defmac m4_set_add (@var{set}, @var{value}, @ovar{if-uniq}, @ovar{if-dup})
+ at msindex{set_add}
+Adds the string @var{value} as a member of set @var{set}. Expand
+ at var{if-uniq} if the element was added, or @var{if-dup} if it was
+previously in the set. Operates in amortized constant time, so that set
+creation scales linearly.
+ at end defmac
+
+ at defmac m4_set_add_all (@var{set}, @var{value}@dots{})
+ at msindex{set_add_all}
+Adds each @var{value} to the set @var{set}. This is slightly more
+efficient than repeatedly invoking @code{m4_set_add}.
+ at end defmac
+
+ at defmac m4_set_contains (@var{set}, @var{value}, @ovar{if-present}, @
+ @ovar{if-absent})
+ at msindex{set_contains}
+Expands @var{if-present} if the string @var{value} is a member of
+ at var{set}, otherwise @var{if-absent}.
+
+ at example
+m4_set_contains([a], [1], [yes], [no])
+ at result{}no
+m4_set_add([a], [1], [added], [dup])
+ at result{}added
+m4_set_add([a], [1], [added], [dup])
+ at result{}dup
+m4_set_contains([a], [1], [yes], [no])
+ at result{}yes
+m4_set_remove([a], [1], [removed], [missing])
+ at result{}removed
+m4_set_contains([a], [1], [yes], [no])
+ at result{}no
+m4_set_remove([a], [1], [removed], [missing])
+ at result{}missing
+ at end example
+ at end defmac
+
+ at defmac m4_set_contents (@var{set}, @ovar{sep})
+ at defmacx m4_set_dump (@var{set}, @ovar{sep})
+ at msindex{set_contents}
+ at msindex{set_dump}
+Expands to a single string consisting of all the members of the set
+ at var{set}, each separated by @var{sep}, which is not expanded.
+ at code{m4_set_contents} leaves the elements in @var{set} but reclaims any
+memory occupied by removed elements, while @code{m4_set_dump} is a
+faster one-shot action that also deletes the set. No provision is made
+for disambiguating members that contain a non-empty @var{sep} as a
+substring; use @code{m4_set_empty} to distinguish between an empty set
+and the set containing only the empty string. The order of the output
+is unspecified; in the current implementation, part of the speed of
+ at code{m4_set_dump} results from using a different output order than
+ at code{m4_set_contents}. These macros scale linearly in the size of the
+set before memory pruning, and @code{m4_set_contents([@var{set}],
+[@var{sep}])} is faster than
+ at code{m4_joinall([@var{sep}]m4_set_listc([@var{set}]))}.
+
+ at example
+m4_set_add_all([a], [1], [2], [3])
+ at result{}
+m4_set_contents([a], [-])
+ at result{}1-2-3
+m4_joinall([-]m4_set_listc([a]))
+ at result{}1-2-3
+m4_set_dump([a], [-])
+ at result{}3-2-1
+m4_set_contents([a])
+ at result{}
+m4_set_add([a], [])
+ at result{}
+m4_set_contents([a], [-])
+ at result{}
+ at end example
+ at end defmac
+
+ at defmac m4_set_delete (@var{set})
+ at msindex{set_delete}
+Delete all elements and memory associated with @var{set}. This is
+linear in the set size, and faster than removing one element at a time.
+ at end defmac
+
+ at defmac m4_set_difference (@var{seta}, @var{setb})
+ at defmacx m4_set_intersection (@var{seta}, @var{setb})
+ at defmacx m4_set_union (@var{seta}, @var{setb})
+ at msindex{set_difference}
+ at msindex{set_intersection}
+ at msindex{set_union}
+Compute the relation between @var{seta} and @var{setb}, and output the
+result as a list of quoted arguments without duplicates and with a
+leading comma. Set difference selects the elements in @var{seta} but
+not @var{setb}, intersection selects only elements in both sets, and
+union selects elements in either set. These actions are linear in the
+sum of the set sizes. The leading comma is necessary to distinguish
+between no elements and the empty string as the only element.
+
+ at example
+m4_set_add_all([a], [1], [2], [3])
+ at result{}
+m4_set_add_all([b], [3], [], [4])
+ at result{}
+m4_set_difference([a], [b])
+ at result{},1,2
+m4_set_difference([b], [a])
+ at result{},,4
+m4_set_intersection([a], [b])
+ at result{},3
+m4_set_union([a], [b])
+ at result{},1,2,3,,4
+ at end example
+ at end defmac
+
+ at defmac m4_set_empty (@var{set}, @ovar{if-empty}, @ovar{if-elements})
+ at msindex{set_empty}
+Expand @var{if-empty} if the set @var{set} has no elements, otherwise
+expand @var{if-elements}. This macro operates in constant time. Using
+this macro can help disambiguate output from @code{m4_set_contents} or
+ at code{m4_set_list}.
+ at end defmac
+
+ at defmac m4_set_foreach (@var{set}, @var{variable}, @var{action})
+ at msindex{set_foreach}
+For each element in the set @var{set}, expand @var{action} with the
+macro @var{variable} defined as the set element. Behavior is
+unspecified if @var{action} recursively lists the contents of @var{set}
+(although listing other sets is acceptable), or if it modifies the set
+in any way other than removing the element currently contained in
+ at var{variable}. This macro is faster than the corresponding
+ at code{m4_foreach([@var{variable}],
+m4_indir([m4_dquote]m4_set_listc([@var{set}])), [@var{action}])},
+although @code{m4_set_map} might be faster still.
+
+ at example
+m4_set_add_all([a]m4_for([i], [1], [5], [], [,i]))
+ at result{}
+m4_set_contents([a])
+ at result{}12345
+m4_set_foreach([a], [i],
+ [m4_if(m4_eval(i&1), [0], [m4_set_remove([a], i, [i])])])
+ at result{}24
+m4_set_contents([a])
+ at result{}135
+ at end example
+ at end defmac
+
+ at defmac m4_set_list (@var{set})
+ at defmacx m4_set_listc (@var{set})
+ at msindex{set_list}
+ at msindex{set_listc}
+Produce a list of arguments, where each argument is a quoted element
+from the set @var{set}. The variant @code{m4_set_listc} is unambiguous,
+by adding a leading comma if there are any set elements, whereas the
+variant @code{m4_set_list} cannot distinguish between an empty set and a
+set containing only the empty string. These can be directly used in
+macros that take multiple arguments, such as @code{m4_join} or
+ at code{m4_set_add_all}, or wrapped by @code{m4_dquote} for macros that
+take a quoted list, such as @code{m4_map} or @code{m4_foreach}. Any
+memory occupied by removed elements is reclaimed during these macros.
+
+ at example
+m4_set_add_all([a], [1], [2], [3])
+ at result{}
+m4_set_list([a])
+ at result{}1,2,3
+m4_set_list([b])
+ at result{}
+m4_set_listc([b])
+ at result{}
+m4_count(m4_set_list([b]))
+ at result{}1
+m4_set_empty([b], [0], [m4_count(m4_set_list([b]))])
+ at result{}0
+m4_set_add([b], [])
+ at result{}
+m4_set_list([b])
+ at result{}
+m4_set_listc([b])
+ at result{},
+m4_count(m4_set_list([b]))
+ at result{}1
+m4_set_empty([b], [0], [m4_count(m4_set_list([b]))])
+ at result{}1
+ at end example
+ at end defmac
+
+ at defmac m4_set_map (@var{set}, @var{action})
+ at msindex{set_map}
+For each element in the set @var{set}, expand @var{action} with a single
+argument of the set element. Behavior is unspecified if @var{action}
+recursively lists the contents of @var{set} (although listing other sets
+is acceptable), or if it modifies the set in any way other than removing
+the element passed as an argument. This macro is faster than either
+corresponding counterpart of
+ at code{m4_map_args([@var{action}]m4_set_listc([@var{set}]))} or
+ at code{m4_set_foreach([@var{set}], [var],
+[@var{action}(m4_defn([var]))])}. It is possible to use @code{m4_curry}
+if more than one argument is needed for @var{action}, although it is
+more efficient to use @code{m4_set_map_sep} in that case.
+ at end defmac
+
+ at defmac m4_set_map_sep (@var{set}, @ovar{pre}, @ovar{post}, @ovar{sep})
+ at msindex{set_map_sep}
+For each element in the set @var{set}, expand
+ at code{@var{pre}[element]@var{post}}, additionally expanding @var{sep}
+between elements. Behavior is unspecified if the expansion recursively
+lists the contents of @var{set} (although listing other sets
+is acceptable), or if it modifies the set in any way other than removing
+the element visited by the expansion. This macro provides the most
+efficient means for non-destructively visiting the elements of a set; in
+particular, @code{m4_set_map([@var{set}], [@var{action}])} is equivalent
+to @code{m4_set_map_sep([@var{set}], [@var{action}(], [)])}.
+ at end defmac
+
+ at defmac m4_set_remove (@var{set}, @var{value}, @ovar{if-present}, @
+ @ovar{if-absent})
+ at msindex{set_remove}
+If @var{value} is an element in the set @var{set}, then remove it and
+expand @var{if-present}. Otherwise expand @var{if-absent}. This macro
+operates in constant time so that multiple removals will scale linearly
+rather than quadratically; but when used outside of
+ at code{m4_set_foreach} or @code{m4_set_map}, it leaves memory occupied
+until the set is later
+compacted by @code{m4_set_contents} or @code{m4_set_list}. Several
+other set operations are then less efficient between the time of element
+removal and subsequent memory compaction, but still maintain their
+guaranteed scaling performance.
+ at end defmac
+
+ at defmac m4_set_size (@var{set})
+ at msindex{set_size}
+Expand to the size of the set @var{set}. This implementation operates
+in constant time, and is thus more efficient than
+ at code{m4_eval(m4_count(m4_set_listc([set])) - 1)}.
+ at end defmac
+
+
+ at node Forbidden Patterns
+ at subsection Forbidden Patterns
+ at cindex Forbidden patterns
+ at cindex Patterns, forbidden
+
+M4sugar provides a means to define suspicious patterns, patterns
+describing tokens which should not be found in the output. For
+instance, if an Autoconf @file{configure} script includes tokens such as
+ at samp{AC_DEFINE}, or @samp{dnl}, then most probably something went
+wrong (typically a macro was not evaluated because of overquotation).
+
+M4sugar forbids all the tokens matching @samp{^_?m4_} and @samp{^dnl$}.
+Additional layers, such as M4sh and Autoconf, add additional forbidden
+patterns to the list.
+
+ at defmac m4_pattern_forbid (@var{pattern})
+ at msindex{pattern_forbid}
+Declare that no token matching @var{pattern} must be found in the output.
+Comments are not checked; this can be a problem if, for instance, you
+have some macro left unexpanded after an @samp{#include}. No consensus
+is currently found in the Autoconf community, as some people consider it
+should be valid to name macros in comments (which doesn't make sense to
+the authors of this documentation: input, such as macros, should be
+documented by @samp{dnl} comments; reserving @samp{#}-comments to
+document the output).
+ at end defmac
+
+Of course, you might encounter exceptions to these generic rules, for
+instance you might have to refer to @samp{$m4_flags}.
+
+ at defmac m4_pattern_allow (@var{pattern})
+ at msindex{pattern_allow}
+Any token matching @var{pattern} is allowed, including if it matches an
+ at code{m4_pattern_forbid} pattern.
+ at end defmac
+
+ at node Debugging via autom4te
+ at section Debugging via autom4te
+ at cindex debugging tips
+ at cindex autom4te debugging tips
+ at cindex m4sugar debugging tips
+At times, it is desirable to see what was happening inside m4, to see
+why output was not matching expectations. However, post-processing done
+by @command{autom4te} means that directly using the m4 builtin
+ at code{m4_traceon} is likely to interfere with operation. Also, frequent
+diversion changes and the concept of forbidden tokens make it difficult
+to use @code{m4_defn} to generate inline comments in the final output.
+
+There are a couple of tools to help with this. One is the use of the
+ at option{--trace} option provided by @command{autom4te} (as well as each
+of the programs that wrap @command{autom4te}, such as
+ at command{autoconf}), in order to inspect when a macro is called and with
+which arguments. For example, when this paragraph was written, the
+autoconf version could be found by:
+
+ at example
+$ @kbd{autoconf --trace=AC_INIT}
+configure.ac:23:AC_INIT:GNU Autoconf:2.63b.95-3963:bug-autoconf@@gnu.org
+$ @kbd{autoconf --trace='AC_INIT:version is $2'}
+version is 2.63b.95-3963
+ at end example
+
+Another trick is to print out the expansion of various m4 expressions to
+standard error or to an independent file, with no further m4 expansion,
+and without interfering with diversion changes or the post-processing
+done to standard output. @code{m4_errprintn} shows a given expression
+on standard error. For example, if you want to see the expansion of an
+autoconf primitive or of one of your autoconf macros, you can do it like
+this:
+
+ at example
+$ @kbd{cat <<\EOF > configure.ac}
+AC_INIT
+m4_errprintn([The definition of AC_DEFINE_UNQUOTED:])
+m4_errprintn(m4_defn([AC_DEFINE_UNQUOTED]))
+AC_OUTPUT
+EOF
+$ @kbd{autoconf}
+ at error{}The definition of AC_DEFINE_UNQUOTED:
+ at error{}_AC_DEFINE_Q([], $@@)
+ at end example
+
+ at node Programming in M4sh
+ at chapter Programming in M4sh
+
+M4sh, pronounced ``mash'', is aiming at producing portable Bourne shell
+scripts. This name was coined by Lars J. Aas, who notes that,
+according to the Webster's Revised Unabridged Dictionary (1913):
+
+ at quotation
+Mash \Mash\, n. [Akin to G. meisch, maisch, meische, maische, mash,
+wash, and prob.@: to AS. miscian to mix. See ``Mix''.]
+
+ at enumerate 1
+ at item
+A mass of mixed ingredients reduced to a soft pulpy state by beating or
+pressure at enddots{}
+
+ at item
+A mixture of meal or bran and water fed to animals.
+
+ at item
+A mess; trouble. [Obs.] --Beau.@: & Fl.
+ at end enumerate
+ at end quotation
+
+M4sh reserves the M4 macro namespace @samp{^_AS_} for internal use, and
+the namespace @samp{^AS_} for M4sh macros. It also reserves the shell
+and environment variable namespace @samp{^as_}, and the here-document
+delimiter namespace @samp{^_AS[A-Z]} in the output file. You should not
+define your own macros or output shell code that conflicts with these
+namespaces.
+
+ at menu
+* 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
+ at end menu
+
+ at node Common Shell Constructs
+ at section Common Shell Constructs
+
+M4sh provides portable alternatives for some common shell constructs
+that unfortunately are not portable in practice.
+
+ at c Deprecated, to be replaced by a better API
+ at ignore
+ at defmac AS_BASENAME (@var{file-name})
+ at asindex{BASENAME}
+Output the non-directory portion of @var{file-name}. For example,
+if @code{$file} is @samp{/one/two/three}, the command
+ at code{base=`AS_BASENAME(["$file"])`} sets @code{base} to @samp{three}.
+ at end defmac
+ at end ignore
+
+ at defmac AS_BOX (@var{text}, @dvar{char, -})
+ at asindex{BOX}
+Expand into shell code that will output @var{text} surrounded by a box
+with @var{char} in the top and bottom border. @var{text} should not
+contain a newline, but may contain shell expansions valid for unquoted
+here-documents. @var{char} defaults to @samp{-}, but can be any
+character except @samp{/}, @samp{'}, @samp{"}, @samp{\},
+ at samp{&}, or @samp{`}. This is useful for outputting a comment box into
+log files to separate distinct phases of script operation.
+ at end defmac
+
+ at defmac AS_CASE (@var{word}, @ovar{pattern1}, @ovar{if-matched1}, @
+ @dots{}, @ovar{default})
+ at asindex{CASE}
+Expand into a shell @samp{case} statement, where @var{word} is matched
+against one or more patterns. @var{if-matched} is run if the
+corresponding pattern matched @var{word}, else @var{default} is run.
+Avoids several portability issues (@pxref{case, , Limitations of Shell
+Builtins}).
+ at end defmac
+
+ at c Deprecated, to be replaced by a better API
+ at defmac AS_DIRNAME (@var{file-name})
+ at asindex{DIRNAME}
+Output the directory portion of @var{file-name}. For example,
+if @code{$file} is @samp{/one/two/three}, the command
+ at code{dir=`AS_DIRNAME(["$file"])`} sets @code{dir} to @samp{/one/two}.
+
+This interface may be improved in the future to avoid forks and losing
+trailing newlines.
+ at end defmac
+
+ at defmac AS_ECHO (@var{word})
+ at asindex{ECHO}
+Emits @var{word} to the standard output, followed by a newline. @var{word}
+must be a single shell word (typically a quoted string). The bytes of
+ at var{word} are output as-is, even if it starts with "-" or contains "\".
+Redirections can be placed outside the macro invocation. This is much
+more portable than using @command{echo} (@pxref{echo, , Limitations of
+Shell Builtins}).
+ at end defmac
+
+ at defmac AS_ECHO_N (@var{word})
+ at asindex{ECHO_N}
+Emits @var{word} to the standard output, without a following newline.
+ at var{word} must be a single shell word (typically a quoted string) and,
+for portability, should not include more than one newline. The bytes of
+ at var{word} are output as-is, even if it starts with "-" or contains "\".
+Redirections can be placed outside the macro invocation.
+ at end defmac
+
+ at c We cannot use @dvar because the macro expansion mistreats backslashes.
+ at defmac AS_ESCAPE (@var{string}, @r{[}@var{chars} = @samp{`\"$}@r{]})
+ at asindex{ESCAPE}
+Expands to @var{string}, with any characters in @var{chars} escaped with
+a backslash (@samp{\}). @var{chars} should be at most four bytes long,
+and only contain characters from the set @samp{`\"$}; however,
+characters may be safely listed more than once in @var{chars} for the
+sake of syntax highlighting editors. The current implementation expands
+ at var{string} after adding escapes; if @var{string} contains macro calls
+that in turn expand to text needing shell quoting, you can use
+ at code{AS_ESCAPE(m4_dquote(m4_expand([string])))}.
+
+The default for @var{chars} (@samp{\"$`}) is the set of characters
+needing escapes when @var{string} will be used literally within double
+quotes. One common variant is the set of characters to protect when
+ at var{string} will be used literally within back-ticks or an unquoted
+here-document (@samp{\$`}). Another common variant is @samp{""}, which can
+be used to form a double-quoted string containing the same expansions
+that would have occurred if @var{string} were expanded in an unquoted
+here-document; however, when using this variant, care must be taken that
+ at var{string} does not use double quotes within complex variable
+expansions (such as @samp{$@{foo-`echo "hi"`@}}) that would be broken
+with improper escapes.
+
+This macro is often used with @code{AS_ECHO}. For an example, observe
+the output generated by the shell code generated from this snippet:
+
+ at example
+foo=bar
+AS_ECHO(["AS_ESCAPE(["$foo" = ])AS_ESCAPE(["$foo"], [""])"])
+ at result{}"$foo" = "bar"
+m4_define([macro], [a, [\b]])
+AS_ECHO(["AS_ESCAPE([[macro]])"])
+ at result{}macro
+AS_ECHO(["AS_ESCAPE([macro])"])
+ at result{}a, b
+AS_ECHO(["AS_ESCAPE(m4_dquote(m4_expand([macro])))"])
+ at result{}a, \b
+ at end example
+
+ at comment Should we add AS_ESCAPE_SINGLE? If we do, we can optimize in
+ at comment the case of @var{string} that does not contain '.
+To escape a string that will be placed within single quotes, use:
+
+ at example
+m4_bpatsubst([[@var{string}]], ['], ['\\''])
+ at end example
+ at end defmac
+
+ at defmac AS_EXECUTABLE_P (@var{file})
+ at asindex{EXECUTABLE_P}
+Emit code to probe whether @var{file} is a regular file with executable
+permissions (and not a directory with search permissions). The caller
+is responsible for quoting @var{file}.
+ at end defmac
+
+ at defmac AS_EXIT (@dvar{status, $?})
+ at asindex{EXIT}
+Emit code to exit the shell with @var{status}, defaulting to @samp{$?}.
+This macro
+works around shells that see the exit status of the command prior to
+ at code{exit} inside a @samp{trap 0} handler (@pxref{trap, , Limitations
+of Shell Builtins}).
+ at end defmac
+
+ at defmac AS_IF (@var{test1}, @ovar{run-if-true1}, @dots{}, @ovar{run-if-false})
+ at asindex{IF}
+Run shell code @var{test1}. If @var{test1} exits with a zero status then
+run shell code @var{run-if-true1}, else examine further tests. If no test
+exits with a zero status, run shell code @var{run-if-false}, with
+simplifications if either @var{run-if-true1} or @var{run-if-false}
+is empty. For example,
+
+ at example
+AS_IF([test "x$foo" = xyes], [HANDLE_FOO([yes])],
+ [test "x$foo" != xno], [HANDLE_FOO([maybe])],
+ [echo foo not specified])
+ at end example
+
+ at noindent
+ensures any required macros of @code{HANDLE_FOO}
+are expanded before the first test.
+ at end defmac
+
+ at defmac AS_MKDIR_P (@var{file-name})
+ at asindex{MKDIR_P}
+Make the directory @var{file-name}, including intervening directories
+as necessary. This is equivalent to @samp{mkdir -p -- @var{file-name}},
+except that it is portable to older versions of @command{mkdir} that
+lack support for the @option{-p} option or for the @option{--}
+delimiter (@pxref{mkdir, , Limitations of Usual Tools}). Also,
+ at code{AS_MKDIR_P}
+succeeds if @var{file-name} is a symbolic link to an existing directory,
+even though Posix is unclear whether @samp{mkdir -p} should
+succeed in that case. If creation of @var{file-name} fails, exit the
+script.
+
+Also see the @code{AC_PROG_MKDIR_P} macro (@pxref{Particular Programs}).
+ at end defmac
+
+ at defmac AS_SET_STATUS (@var{status})
+ at asindex{SET_STATUS}
+Emit shell code to set the value of @samp{$?} to @var{status}, as
+efficiently as possible. However, this is not guaranteed to abort a
+shell running with @code{set -e} (@pxref{set, , Limitations of Shell
+Builtins}). This should also be used at the end of a complex shell
+function instead of @samp{return} (@pxref{Shell Functions}) to avoid
+a DJGPP shell bug.
+ at end defmac
+
+ at defmac AS_TR_CPP (@var{expression})
+ at asindex{TR_CPP}
+Transform @var{expression} into a valid right-hand side for a C @code{#define}.
+For example:
+
+ at example
+# This outputs "#define HAVE_CHAR_P 1".
+# Notice the m4 quoting around #, to prevent an m4 comment
+type="char *"
+echo "[#]define AS_TR_CPP([HAVE_$type]) 1"
+ at end example
+ at end defmac
+
+ at defmac AS_TR_SH (@var{expression})
+ at asindex{TR_SH}
+Transform @var{expression} into shell code that generates a valid shell
+variable name. The result is literal when possible at m4 time, but must
+be used with @code{eval} if @var{expression} causes shell indirections.
+For example:
+
+ at example
+# This outputs "Have it!".
+header="sys/some file.h"
+eval AS_TR_SH([HAVE_$header])=yes
+if test "x$HAVE_sys_some_file_h" = xyes; then echo "Have it!"; fi
+ at end example
+ at end defmac
+
+ at defmac AS_SET_CATFILE (@var{var}, @var{dir}, @var{file})
+ at asindex{SET_CATFILE}
+Set the polymorphic shell variable @var{var} to @var{dir}/@var{file},
+but optimizing the common cases (@var{dir} or @var{file} is @samp{.},
+ at var{file} is absolute, etc.).
+ at end defmac
+
+ at defmac AS_UNSET (@var{var})
+ at asindex{UNSET}
+Unsets the shell variable @var{var}, working around bugs in older
+shells (@pxref{unset, , Limitations of Shell
+Builtins}). @var{var} can be a literal or indirect variable name.
+ at end defmac
+
+ at defmac AS_VERSION_COMPARE (@var{version-1}, @var{version-2}, @
+ @ovar{action-if-less}, @ovar{action-if-equal}, @ovar{action-if-greater})
+ at asindex{VERSION_COMPARE}
+Compare two strings @var{version-1} and @var{version-2}, possibly
+containing shell variables, as version strings, and expand
+ at var{action-if-less}, @var{action-if-equal}, or @var{action-if-greater}
+depending upon the result.
+The algorithm to compare is similar to the one used by strverscmp in
+glibc (@pxref{String/Array Comparison, , String/Array Comparison, libc,
+The GNU C Library}).
+ at end defmac
+
+ at node Polymorphic Variables
+ at section Support for indirect variable names
+ at cindex variable name indirection
+ at cindex polymorphic variable name
+ at cindex indirection, variable name
+
+Often, it is convenient to write a macro that will emit shell code
+operating on a shell variable. The simplest case is when the variable
+name is known. But a more powerful idiom is writing shell code that can
+work through an indirection, where another variable or command
+substitution produces the name of the variable to actually manipulate.
+M4sh supports the notion of polymorphic shell variables, making it easy
+to write a macro that can deal with either literal or indirect variable
+names and output shell code appropriate for both use cases. Behavior is
+undefined if expansion of an indirect variable does not result in a
+literal variable name.
+
+ at defmac AS_LITERAL_IF (@var{expression}, @ovar{if-literal}, @ovar{if-not}, @
+ @dvar{if-simple-ref, @var{if-not}})
+ at defmacx AS_LITERAL_WORD_IF (@var{expression}, @ovar{if-literal}, @
+ @ovar{if-not}, @dvar{if-simple-ref, @var{if-not}})
+ at asindex{LITERAL_IF}
+ at asindex{LITERAL_WORD_IF}
+If the expansion of @var{expression} is definitely a shell literal,
+expand @var{if-literal}. If the expansion of @var{expression} looks
+like it might contain shell indirections (such as @code{$var} or
+ at code{`expr`}), then @var{if-not} is expanded. Sometimes, it is
+possible to output optimized code if @var{expression} consists only of
+shell variable expansions (such as @code{$@{var@}}), in which case
+ at var{if-simple-ref} can be provided; but defaulting to @var{if-not}
+should always be safe. @code{AS_LITERAL_WORD_IF} only expands
+ at var{if-literal} if @var{expression} looks like a single shell word,
+containing no whitespace; while @code{AS_LITERAL_IF} allows whitespace
+in @var{expression}.
+
+In order to reduce the time spent recognizing whether an
+ at var{expression} qualifies as a literal or a simple indirection, the
+implementation is somewhat conservative: @var{expression} must be a
+single shell word (possibly after stripping whitespace), consisting only
+of bytes that would have the same meaning whether unquoted or enclosed
+in double quotes (for example, @samp{a.b} results in @var{if-literal},
+even though it is not a valid shell variable name; while both @samp{'a'}
+and @samp{[$]} result in @var{if-not}, because they behave differently
+than @samp{"'a'"} and @samp{"[$]"}). This macro can be used in contexts
+for recognizing portable file names (such as in the implementation of
+ at code{AC_LIBSOURCE}), or coupled with some transliterations for forming
+valid variable names (such as in the implementation of @code{AS_TR_SH},
+which uses an additional @code{m4_translit} to convert @samp{.} to
+ at samp{_}).
+
+This example shows how to read the contents of the shell variable
+ at code{bar}, exercising all three arguments to @code{AS_LITERAL_IF}. It
+results in a script that will output the line @samp{hello} three times.
+
+ at example
+AC_DEFUN([MY_ACTION],
+[AS_LITERAL_IF([$1],
+ [echo "$$1"],
+ at c $$
+ [AS_VAR_COPY([var], [$1])
+ echo "$var"],
+ [eval 'echo "$'"$1"\"])])
+foo=bar bar=hello
+MY_ACTION([bar])
+MY_ACTION([`echo bar`])
+MY_ACTION([$foo])
+ at end example
+ at end defmac
+
+ at defmac AS_VAR_APPEND (@var{var}, @var{text})
+ at asindex{VAR_APPEND}
+Emit shell code to append the shell expansion of @var{text} to the end
+of the current contents of the polymorphic shell variable @var{var},
+taking advantage of shells that provide the @samp{+=} extension for more
+efficient scaling.
+
+For situations where the final contents of @var{var} are relatively
+short (less than 256 bytes), it is more efficient to use the simpler
+code sequence of @code{@var{var}=$@{@var{var}@}@var{text}} (or its
+polymorphic equivalent of @code{AS_VAR_COPY([t], [@var{var}])} and
+ at code{AS_VAR_SET([@var{var}], ["$t"@var{text}])}). But in the case
+when the script will be repeatedly appending text into @code{var},
+issues of scaling start to become apparent. A naive implementation
+requires execution time linear to the length of the current contents of
+ at var{var} as well as the length of @var{text} for a single append, for
+an overall quadratic scaling with multiple appends. This macro takes
+advantage of shells which provide the extension
+ at code{@var{var}+=@var{text}}, which can provide amortized constant time
+for a single append, for an overall linear scaling with multiple
+appends. Note that unlike @code{AS_VAR_SET}, this macro requires that
+ at var{text} be quoted properly to avoid field splitting and file name
+expansion.
+ at end defmac
+
+ at defmac AS_VAR_ARITH (@var{var}, @var{expression})
+ at asindex{VAR_ARITH}
+Emit shell code to compute the arithmetic expansion of @var{expression},
+assigning the result as the contents of the polymorphic shell variable
+ at var{var}. The code takes advantage of shells that provide @samp{$(())}
+for fewer forks, but uses @command{expr} as a fallback. Therefore, the
+syntax for a valid @var{expression} is rather limited: all operators
+must occur as separate shell arguments and with proper quoting, there is
+no portable equality operator, all variables containing numeric values
+must be expanded prior to the computation, all numeric values must be
+provided in decimal without leading zeroes, and the first shell argument
+should not be a negative number. In the following example, this snippet
+will print @samp{(2+3)*4 == 20}.
+
+ at example
+bar=3
+AS_VAR_ARITH([foo], [\( 2 + $bar \) \* 4])
+echo "(2+$bar)*4 == $foo"
+ at end example
+ at end defmac
+
+ at defmac AS_VAR_COPY (@var{dest}, @var{source})
+ at asindex{VAR_COPY}
+Emit shell code to assign the contents of the polymorphic shell variable
+ at var{source} to the polymorphic shell variable @var{dest}. For example,
+executing this M4sh snippet will output @samp{bar hi}:
+
+ at example
+foo=bar bar=hi
+AS_VAR_COPY([a], [foo])
+AS_VAR_COPY([b], [$foo])
+echo "$a $b"
+ at end example
+
+When it is necessary to access the contents of an indirect variable
+inside a shell double-quoted context, the recommended idiom is to first
+copy the contents into a temporary literal shell variable.
+
+ at smallexample
+for header in stdint_h inttypes_h ; do
+ AS_VAR_COPY([var], [ac_cv_header_$header])
+ echo "$header detected: $var"
+done
+ at end smallexample
+ at end defmac
+
+ at comment AS_VAR_GET is intentionally undocumented; it can't handle
+ at comment trailing newlines uniformly, and forks too much.
+
+ at defmac AS_VAR_IF (@var{var}, @ovar{word}, @ovar{if-equal}, @
+ @ovar{if-not-equal})
+ at asindex{VAR_IF}
+Output a shell conditional statement. If the contents of the
+polymorphic shell variable @var{var} match the string @var{word},
+execute @var{if-equal}; otherwise execute @var{if-not-equal}. @var{word}
+must be a single shell word (typically a quoted string). Avoids
+shell bugs if an interrupt signal arrives while a command substitution
+in @var{var} is being expanded.
+ at end defmac
+
+ at defmac AS_VAR_PUSHDEF (@var{m4-name}, @var{value})
+ at defmacx AS_VAR_POPDEF (@var{m4-name})
+ at asindex{VAR_PUSHDEF}
+ at asindex{VAR_POPDEF}
+ at cindex composing variable names
+ at cindex variable names, composing
+A common M4sh idiom involves composing shell variable names from an m4
+argument (for example, writing a macro that uses a cache variable).
+ at var{value} can be an arbitrary string, which will be transliterated
+into a valid shell name by @code{AS_TR_SH}. In order to access the
+composed variable name based on @var{value}, it is easier to declare a
+temporary m4 macro @var{m4-name} with @code{AS_VAR_PUSHDEF}, then use
+that macro as the argument to subsequent @code{AS_VAR} macros as a
+polymorphic variable name, and finally free the temporary macro with
+ at code{AS_VAR_POPDEF}. These macros are often followed with @code{dnl},
+to avoid excess newlines in the output.
+
+Here is an involved example, that shows the power of writing macros that
+can handle composed shell variable names:
+
+ at example
+m4_define([MY_CHECK_HEADER],
+[AS_VAR_PUSHDEF([my_Header], [ac_cv_header_$1])dnl
+AS_VAR_IF([my_Header], [yes], [echo "header $1 detected"])dnl
+AS_VAR_POPDEF([my_Header])dnl
+])
+MY_CHECK_HEADER([stdint.h])
+for header in inttypes.h stdlib.h ; do
+ MY_CHECK_HEADER([$header])
+done
+ at end example
+
+ at noindent
+In the above example, @code{MY_CHECK_HEADER} can operate on polymorphic
+variable names. In the first invocation, the m4 argument is
+ at code{stdint.h}, which transliterates into a literal @code{stdint_h}.
+As a result, the temporary macro @code{my_Header} expands to the literal
+shell name @samp{ac_cv_header_stdint_h}. In the second invocation, the
+m4 argument to @code{MY_CHECK_HEADER} is @code{$header}, and the
+temporary macro @code{my_Header} expands to the indirect shell name
+ at samp{$as_my_Header}. During the shell execution of the for loop, when
+ at samp{$header} contains @samp{inttypes.h}, then @samp{$as_my_Header}
+contains @samp{ac_cv_header_inttypes_h}. If this script is then run on a
+platform where all three headers have been previously detected, the
+output of the script will include:
+
+ at smallexample
+header stdint.h detected
+header inttypes.h detected
+header stdlib.h detected
+ at end smallexample
+ at end defmac
+
+ at defmac AS_VAR_SET (@var{var}, @ovar{value})
+ at asindex{VAR_SET}
+Emit shell code to assign the contents of the polymorphic shell variable
+ at var{var} to the shell expansion of @var{value}. @var{value} is not
+subject to field splitting or file name expansion, so if command
+substitution is used, it may be done with @samp{`""`} rather than using
+an intermediate variable (@pxref{Shell Substitutions}). However,
+ at var{value} does undergo rescanning for additional macro names; behavior
+is unspecified if late expansion results in any shell meta-characters.
+ at end defmac
+
+ at defmac AS_VAR_SET_IF (@var{var}, @ovar{if-set}, @ovar{if-undef})
+ at asindex{VAR_SET_IF}
+Emit a shell conditional statement, which executes @var{if-set} if the
+polymorphic shell variable @code{var} is set to any value, and
+ at var{if-undef} otherwise.
+ at end defmac
+
+ at defmac AS_VAR_TEST_SET (@var{var})
+ at asindex{VAR_TEST_SET}
+Emit a shell statement that results in a successful exit status only if
+the polymorphic shell variable @code{var} is set.
+ at end defmac
+
+ at node Initialization Macros
+ at section Initialization Macros
+
+ at defmac AS_BOURNE_COMPATIBLE
+ at asindex{BOURNE_COMPATIBLE}
+Set up the shell to be more compatible with the Bourne shell as
+standardized by Posix, if possible. This may involve setting
+environment variables, or setting options, or similar
+implementation-specific actions. This macro is deprecated, since
+ at code{AS_INIT} already invokes it.
+ at end defmac
+
+ at defmac AS_INIT
+ at asindex{INIT}
+ at evindex LC_ALL
+ at evindex SHELL
+Initialize the M4sh environment. This macro calls @code{m4_init}, then
+outputs the @code{#! /bin/sh} line, a notice about where the output was
+generated from, and code to sanitize the environment for the rest of the
+script. Among other initializations, this sets @env{SHELL} to the shell
+chosen to run the script (@pxref{CONFIG_SHELL}), and @env{LC_ALL} to
+ensure the C locale. Finally, it changes the current diversion to
+ at code{BODY}. @code{AS_INIT} is called automatically by @code{AC_INIT}
+and @code{AT_INIT}, so shell code in @file{configure},
+ at file{config.status}, and @file{testsuite} all benefit from a sanitized
+shell environment.
+ at end defmac
+
+ at defmac AS_INIT_GENERATED (@var{file}, @ovar{comment})
+ at asindex{INIT_GENERATED}
+Emit shell code to start the creation of a subsidiary shell script in
+ at var{file}, including changing @var{file} to be executable. This macro
+populates the child script with information learned from the parent
+(thus, the emitted code is equivalent in effect, but more efficient,
+than the code output by @code{AS_INIT}, @code{AS_BOURNE_COMPATIBLE}, and
+ at code{AS_SHELL_SANITIZE}). If present, @var{comment} is output near the
+beginning of the child, prior to the shell initialization code, and is
+subject to parameter expansion, command substitution, and backslash
+quote removal. The
+parent script should check the exit status after this macro, in case
+ at var{file} could not be properly created (for example, if the disk was
+full). If successfully created, the parent script can then proceed to
+append additional M4sh constructs into the child script.
+
+Note that the child script starts life without a log file open, so if
+the parent script uses logging (@pxref{AS_MESSAGE_LOG_FD}), you
+must temporarily disable any attempts to use the log file until after
+emitting code to open a log within the child. On the other hand, if the
+parent script has @code{AS_MESSAGE_FD} redirected somewhere besides
+ at samp{1}, then the child script already has code that copies stdout to
+that descriptor. Currently, the suggested
+idiom for writing a M4sh shell script from within another script is:
+
+ at example
+AS_INIT_GENERATED([@var{file}], [[# My child script.
+]]) || @{ AS_ECHO(["Failed to create child script"]); AS_EXIT; @}
+m4_pushdef([AS_MESSAGE_LOG_FD])dnl
+cat >> "@var{file}" <<\__EOF__
+# Code to initialize AS_MESSAGE_LOG_FD
+m4_popdef([AS_MESSAGE_LOG_FD])dnl
+# Additional code
+__EOF__
+ at end example
+
+This, however, may change in the future as the M4sh interface is
+stabilized further.
+
+Also, be aware that use of @env{LINENO} within the child script may
+report line numbers relative to their location in the parent script,
+even when using @code{AS_LINENO_PREPARE}, if the parent script was
+unable to locate a shell with working @env{LINENO} support.
+ at end defmac
+
+ at defmac AS_LINENO_PREPARE
+ at asindex{LINENO_PREPARE}
+ at evindex LINENO
+Find a shell that supports the special variable @env{LINENO}, which
+contains the number of the currently executing line. This macro is
+automatically invoked by @code{AC_INIT} in configure scripts.
+ at end defmac
+
+ at defmac AS_ME_PREPARE
+ at asindex{ME_PREPARE}
+Set up variable @env{as_me} to be the basename of the currently executing
+script. This macro is automatically invoked by @code{AC_INIT} in
+configure scripts.
+ at end defmac
+
+ at defmac AS_TMPDIR (@var{prefix}, @dvar{dir, $@{TMPDIR:=/tmp@}})
+ at asindex{TMPDIR}
+ at evindex TMPDIR
+ at ovindex tmp
+Create, as safely as possible, a temporary sub-directory within
+ at var{dir} with a name starting with @var{prefix}. @var{prefix} should
+be 2-4 characters, to make it slightly easier to identify the owner of
+the directory. If @var{dir} is omitted, then the value of @env{TMPDIR}
+will be used (defaulting to @samp{/tmp}). On success, the name of the
+newly created directory is stored in the shell variable @code{tmp}. On
+error, the script is aborted.
+
+Typically, this macro is coupled with some exit traps to delete the created
+directory and its contents on exit or interrupt. However, there is a
+slight window between when the directory is created and when the name is
+actually known to the shell, so an interrupt at the right moment might
+leave the temporary directory behind. Hence it is important to use a
+ at var{prefix} that makes it easier to determine if a leftover temporary
+directory from an interrupted script is safe to delete.
+
+The use of the output variable @samp{$tmp} rather than something in the
+ at samp{as_} namespace is historical; it has the unfortunate consequence
+that reusing this otherwise common name for any other purpose inside
+your script has the potential to break any cleanup traps designed to
+remove the temporary directory.
+ at end defmac
+
+ at defmac AS_SHELL_SANITIZE
+ at asindex{SHELL_SANITIZE}
+Initialize the shell suitably for @command{configure} scripts. This has
+the effect of @code{AS_BOURNE_COMPATIBLE}, and sets some other
+environment variables for predictable results from configuration tests.
+For example, it sets @env{LC_ALL} to change to the default C locale.
+ at xref{Special Shell Variables}. This macro is deprecated, since
+ at code{AS_INIT} already invokes it.
+ at end defmac
+
+
+ at node File Descriptor Macros
+ at section File Descriptor Macros
+ at cindex input
+ at cindex standard input
+ at cindex file descriptors
+ at cindex descriptors
+ at cindex low-level output
+ at cindex output, low-level
+
+The following macros define file descriptors used to output messages
+(or input values) from @file{configure} scripts.
+For example:
+
+ at example
+echo "$wombats found" >&AS_MESSAGE_LOG_FD
+echo 'Enter desired kangaroo count:' >&AS_MESSAGE_FD
+read kangaroos <&AS_ORIGINAL_STDIN_FD`
+ at end example
+
+ at noindent
+However doing so is seldom needed, because Autoconf provides higher
+level macros as described below.
+
+ at defmac AS_MESSAGE_FD
+ at asindex{MESSAGE_FD}
+The file descriptor for @samp{checking for...} messages and results.
+By default, @code{AS_INIT} sets this to @samp{1} for standalone M4sh
+clients. However, @code{AC_INIT} shuffles things around to another file
+descriptor, in order to allow the @option{-q} option of
+ at command{configure} to choose whether messages should go to the script's
+standard output or be discarded.
+
+If you want to display some messages, consider using one of the printing
+macros (@pxref{Printing Messages}) instead. Copies of messages output
+via these macros are also recorded in @file{config.log}.
+ at end defmac
+
+ at anchor{AS_MESSAGE_LOG_FD}
+ at defmac AS_MESSAGE_LOG_FD
+ at asindex{MESSAGE_LOG_FD}
+This must either be empty, or expand to a file descriptor for log
+messages. By default, @code{AS_INIT} sets this macro to the empty
+string for standalone M4sh clients, thus disabling logging. However,
+ at code{AC_INIT} shuffles things around so that both @command{configure}
+and @command{config.status} use @file{config.log} for log messages.
+Macros that run tools, like @code{AC_COMPILE_IFELSE} (@pxref{Running the
+Compiler}), redirect all output to this descriptor. You may want to do
+so if you develop such a low-level macro.
+ at end defmac
+
+ at defmac AS_ORIGINAL_STDIN_FD
+ at asindex{ORIGINAL_STDIN_FD}
+This must expand to a file descriptor for the original standard input.
+By default, @code{AS_INIT} sets this macro to @samp{0} for standalone
+M4sh clients. However, @code{AC_INIT} shuffles things around for
+safety.
+
+When @command{configure} runs, it may accidentally execute an
+interactive command that has the same name as the non-interactive meant
+to be used or checked. If the standard input was the terminal, such
+interactive programs would cause @command{configure} to stop, pending
+some user input. Therefore @command{configure} redirects its standard
+input from @file{/dev/null} during its initialization. This is not
+normally a problem, since @command{configure} normally does not need
+user input.
+
+In the extreme case where your @file{configure} script really needs to
+obtain some values from the original standard input, you can read them
+explicitly from @code{AS_ORIGINAL_STDIN_FD}.
+ at end defmac
+
+
+ at c =================================================== Writing Autoconf Macros.
+
+ at node Writing Autoconf Macros
+ at chapter Writing Autoconf Macros
+
+When you write a feature test that could be applicable to more than one
+software package, the best thing to do is encapsulate it in a new macro.
+Here are some instructions and guidelines for writing Autoconf macros.
+
+ at menu
+* Macro Definitions:: Basic format of an Autoconf macro
+* Macro Names:: What to call your new macros
+* Reporting Messages:: Notifying @command{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
+ at end menu
+
+ at node Macro Definitions
+ at section Macro Definitions
+
+ at defmac AC_DEFUN (@var{name}, @ovar{body})
+ at acindex{DEFUN}
+Autoconf macros are defined using the @code{AC_DEFUN} macro, which is
+similar to the M4 builtin @code{m4_define} macro; this creates a macro
+named @var{name} and with @var{body} as its expansion. In addition to
+defining a macro, @code{AC_DEFUN} adds to it some code that is used to
+constrain the order in which macros are called, while avoiding redundant
+output (@pxref{Prerequisite Macros}).
+ at end defmac
+
+An Autoconf macro definition looks like this:
+
+ at example
+AC_DEFUN(@var{macro-name}, @var{macro-body})
+ at end example
+
+You can refer to any arguments passed to the macro as @samp{$1},
+ at samp{$2}, etc. @xref{Definitions, , How to define new macros, m4.info,
+GNU M4}, for more complete information on writing M4 macros.
+
+Most macros fall in one of two general categories. The first category
+includes macros which take arguments, in order to generate output
+parameterized by those arguments. Macros in this category are designed
+to be directly expanded, often multiple times, and should not be used as
+the argument to @code{AC_REQUIRE}. The other category includes macros
+which are shorthand for a fixed block of text, and therefore do not take
+arguments. For this category of macros, directly expanding the macro
+multiple times results in redundant output, so it is more common to use
+the macro as the argument to @code{AC_REQUIRE}, or to declare the macro
+with @code{AC_DEFUN_ONCE} (@pxref{One-Shot Macros}).
+
+Be sure to properly quote both the @var{macro-body} @emph{and} the
+ at var{macro-name} to avoid any problems if the macro happens to have
+been previously defined.
+
+Each macro should have a header comment that gives its prototype, and a
+brief description. When arguments have default values, display them in
+the prototype. For example:
+
+ at example
+# AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1])
+# --------------------------------------
+m4_define([AC_MSG_ERROR],
+ [@{ AS_MESSAGE([error: $1], [2])
+ exit m4_default([$2], [1]); @}])
+ at end example
+
+Comments about the macro should be left in the header comment. Most
+other comments make their way into @file{configure}, so just keep
+using @samp{#} to introduce comments.
+
+ at cindex @code{dnl}
+If you have some special comments about pure M4 code, comments
+that make no sense in @file{configure} and in the header comment, then
+use the builtin @code{dnl}: it causes M4 to discard the text
+through the next newline.
+
+Keep in mind that @code{dnl} is rarely needed to introduce comments;
+ at code{dnl} is more useful to get rid of the newlines following macros
+that produce no output, such as @code{AC_REQUIRE}.
+
+Public third-party macros need to use @code{AC_DEFUN}, and not
+ at code{m4_define}, in order to be found by @command{aclocal}
+(@pxref{Extending aclocal,,, automake, GNU Automake}).
+Additionally, if it is ever determined that a macro should be made
+obsolete, it is easy to convert from @code{AC_DEFUN} to @code{AU_DEFUN}
+in order to have @command{autoupdate} assist the user in choosing a
+better alternative, but there is no corresponding way to make
+ at code{m4_define} issue an upgrade notice (@pxref{AU_DEFUN}).
+
+There is another subtle, but important, difference between using
+ at code{m4_define} and @code{AC_DEFUN}: only the former is unaffected by
+ at code{AC_REQUIRE}. When writing a file, it is always safe to replace a
+block of text with a @code{m4_define} macro that will expand to the same
+text. But replacing a block of text with an @code{AC_DEFUN} macro with
+the same content does not necessarily give the same results, because it
+changes the location where any embedded but unsatisfied
+ at code{AC_REQUIRE} invocations within the block will be expanded. For an
+example of this, see @ref{Expanded Before Required}.
+
+ at node Macro Names
+ at section Macro Names
+
+All of the public Autoconf macros have all-uppercase names in the
+namespace @samp{^AC_} to prevent them from accidentally conflicting with
+other text; Autoconf also reserves the namespace @samp{^_AC_} for
+internal macros. All shell variables that they use for internal
+purposes have mostly-lowercase names starting with @samp{ac_}. Autoconf
+also uses here-document delimiters in the namespace @samp{^_AC[A-Z]}. During
+ at command{configure}, files produced by Autoconf make heavy use of the
+file system namespace @samp{^conf}.
+
+Since Autoconf is built on top of M4sugar (@pxref{Programming in
+M4sugar}) and M4sh (@pxref{Programming in M4sh}), you must also be aware
+of those namespaces (@samp{^_?\(m4\|AS\)_}). And since
+ at file{configure.ac} is also designed to be scanned by Autoheader,
+Autoscan, Autoupdate, and Automake, you should be aware of the
+ at samp{^_?A[HNUM]_} namespaces. In general, you @emph{should not use}
+the namespace of a package that does not own the macro or shell code you
+are writing.
+
+To ensure that your macros don't conflict with present or future
+Autoconf macros, you should prefix your own macro names and any shell
+variables they use with some other sequence. Possibilities include your
+initials, or an abbreviation for the name of your organization or
+software package. Historically, people have not always followed the
+rule of using a namespace appropriate for their package, and this has
+made it difficult for determining the origin of a macro (and where to
+report bugs about that macro), as well as difficult for the true
+namespace owner to add new macros without interference from pre-existing
+uses of third-party macros. Perhaps the best example of this confusion
+is the @code{AM_GNU_GETTEXT} macro, which belongs, not to Automake, but
+to Gettext.
+
+Most of the Autoconf macros' names follow a structured naming convention
+that indicates the kind of feature check by the name. The macro names
+consist of several words, separated by underscores, going from most
+general to most specific. The names of their cache variables use the
+same convention (@pxref{Cache Variable Names}, for more information on
+them).
+
+The first word of the name after the namespace initials (such as
+ at samp{AC_}) usually tells the category
+of the feature being tested. Here are the categories used in Autoconf for
+specific test macros, the kind of macro that you are more likely to
+write. They are also used for cache variables, in all-lowercase. Use
+them where applicable; where they're not, invent your own categories.
+
+ at table @code
+ at item C
+C language builtin features.
+ at item DECL
+Declarations of C variables in header files.
+ at item FUNC
+Functions in libraries.
+ at item GROUP
+Posix group owners of files.
+ at item HEADER
+Header files.
+ at item LIB
+C libraries.
+ at item PROG
+The base names of programs.
+ at item MEMBER
+Members of aggregates.
+ at item SYS
+Operating system features.
+ at item TYPE
+C builtin or declared types.
+ at item VAR
+C variables in libraries.
+ at end table
+
+After the category comes the name of the particular feature being
+tested. Any further words in the macro name indicate particular aspects
+of the feature. For example, @code{AC_PROG_CC_STDC} checks whether the
+C compiler supports ISO Standard C.
+
+An internal macro should have a name that starts with an underscore;
+Autoconf internals should therefore start with @samp{_AC_}.
+Additionally, a macro that is an internal subroutine of another macro
+should have a name that starts with an underscore and the name of that
+other macro, followed by one or more words saying what the internal
+macro does. For example, @code{AC_PATH_X} has internal macros
+ at code{_AC_PATH_X_XMKMF} and @code{_AC_PATH_X_DIRECT}.
+
+ at node Reporting Messages
+ at section Reporting Messages
+ at cindex Messages, from @command{autoconf}
+
+When macros statically diagnose abnormal situations, benign or fatal, it
+is possible to make @command{autoconf} detect the problem, and refuse to
+create @file{configure} in the case of an error. The macros in this
+section are considered obsolescent, and new code should use M4sugar
+macros for this purpose, see @ref{Diagnostic Macros}.
+
+On the other hand, it is possible to want to detect errors when
+ at command{configure} is run, which are dependent on the environment of
+the user rather than the maintainer. For dynamic diagnostics, see
+ at ref{Printing Messages}.
+
+ at defmac AC_DIAGNOSE (@var{category}, @var{message})
+ at acindex{DIAGNOSE}
+Report @var{message} as a warning (or as an error if requested by the
+user) if warnings of the @var{category} are turned on. This macro is
+obsolescent; you are encouraged to use:
+ at example
+m4_warn([@var{category}], [@var{message}])
+ at end example
+ at noindent
+instead. @xref{m4_warn}, for more details, including valid
+ at var{category} names.
+ at end defmac
+
+ at defmac AC_WARNING (@var{message})
+ at acindex{WARNING}
+Report @var{message} as a syntax warning. This macro is obsolescent;
+you are encouraged to use:
+ at example
+m4_warn([syntax], [@var{message}])
+ at end example
+ at noindent
+instead. @xref{m4_warn}, for more details, as well as better
+finer-grained categories of warnings (not all problems have to do with
+syntax).
+ at end defmac
+
+ at defmac AC_FATAL (@var{message})
+ at acindex{FATAL}
+Report a severe error @var{message}, and have @command{autoconf} die.
+This macro is obsolescent; you are encouraged to use:
+ at example
+m4_fatal([@var{message}])
+ at end example
+ at noindent
+instead. @xref{m4_fatal}, for more details.
+ at end defmac
+
+When the user runs @samp{autoconf -W error}, warnings from
+ at code{m4_warn} (including those issued through @code{AC_DIAGNOSE} and
+ at code{AC_WARNING}) are reported as errors, see @ref{autoconf Invocation}.
+
+ at node Dependencies Between Macros
+ at section Dependencies Between Macros
+ at cindex Dependencies between macros
+
+Some Autoconf macros depend on other macros having been called first in
+order to work correctly. Autoconf provides a way to ensure that certain
+macros are called if needed and a way to warn the user if macros are
+called in an order that might cause incorrect operation.
+
+ at menu
+* Prerequisite Macros:: Ensuring required information
+* Suggested Ordering:: Warning about possible ordering problems
+* One-Shot Macros:: Ensuring a macro is called only once
+ at end menu
+
+ at node Prerequisite Macros
+ at subsection Prerequisite Macros
+ at cindex Prerequisite macros
+ at cindex Macros, prerequisites
+
+A macro that you write might need to use values that have previously
+been computed by other macros. For example, @code{AC_DECL_YYTEXT}
+examines the output of @code{flex} or @code{lex}, so it depends on
+ at code{AC_PROG_LEX} having been called first to set the shell variable
+ at code{LEX}.
+
+Rather than forcing the user of the macros to keep track of the
+dependencies between them, you can use the @code{AC_REQUIRE} macro to do
+it automatically. @code{AC_REQUIRE} can ensure that a macro is only
+called if it is needed, and only called once.
+
+ at defmac AC_REQUIRE (@var{macro-name})
+ at acindex{REQUIRE}
+If the M4 macro @var{macro-name} has not already been called, call it
+(without any arguments). Make sure to quote @var{macro-name} with
+square brackets. @var{macro-name} must have been defined using
+ at code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
+that it has been called.
+
+ at code{AC_REQUIRE} must be used inside a macro defined by @code{AC_DEFUN}; it
+must not be called from the top level. Also, it does not make sense to
+require a macro that takes parameters.
+ at end defmac
+
+ at code{AC_REQUIRE} is often misunderstood. It really implements
+dependencies between macros in the sense that if one macro depends upon
+another, the latter is expanded @emph{before} the body of the
+former. To be more precise, the required macro is expanded before
+the outermost defined macro in the current expansion stack.
+In particular, @samp{AC_REQUIRE([FOO])} is not replaced with the body of
+ at code{FOO}. For instance, this definition of macros:
+
+ at example
+ at group
+AC_DEFUN([TRAVOLTA],
+[test "$body_temperature_in_celsius" -gt "38" &&
+ dance_floor=occupied])
+AC_DEFUN([NEWTON_JOHN],
+[test "x$hair_style" = xcurly &&
+ dance_floor=occupied])
+ at end group
+
+ at group
+AC_DEFUN([RESERVE_DANCE_FLOOR],
+[if date | grep '^Sat.*pm' >/dev/null 2>&1; then
+ AC_REQUIRE([TRAVOLTA])
+ AC_REQUIRE([NEWTON_JOHN])
+fi])
+ at end group
+ at end example
+
+ at noindent
+with this @file{configure.ac}
+
+ at example
+AC_INIT([Dance Manager], [1.0], [bug-dance@@example.org])
+RESERVE_DANCE_FLOOR
+if test "x$dance_floor" = xoccupied; then
+ AC_MSG_ERROR([cannot pick up here, let's move])
+fi
+ at end example
+
+ at noindent
+does not leave you with a better chance to meet a kindred soul at
+other times than Saturday night since it expands into:
+
+ at example
+ at group
+test "$body_temperature_in_Celsius" -gt "38" &&
+ dance_floor=occupied
+test "x$hair_style" = xcurly &&
+ dance_floor=occupied
+fi
+if date | grep '^Sat.*pm' >/dev/null 2>&1; then
+
+
+fi
+ at end group
+ at end example
+
+This behavior was chosen on purpose: (i) it prevents messages in
+required macros from interrupting the messages in the requiring macros;
+(ii) it avoids bad surprises when shell conditionals are used, as in:
+
+ at example
+ at group
+if @dots{}; then
+ AC_REQUIRE([SOME_CHECK])
+fi
+ at dots{}
+SOME_CHECK
+ at end group
+ at end example
+
+However, this implementation can lead to another class of problems.
+Consider the case where an outer macro first expands, then indirectly
+requires, an inner macro:
+
+ at example
+AC_DEFUN([TESTA], [[echo in A
+if test -n "$SEEN_A" ; then echo duplicate ; fi
+SEEN_A=:]])
+AC_DEFUN([TESTB], [AC_REQUIRE([TESTA])[echo in B
+if test -z "$SEEN_A" ; then echo bug ; fi]])
+AC_DEFUN([TESTC], [AC_REQUIRE([TESTB])[echo in C]])
+AC_DEFUN([OUTER], [[echo in OUTER]
+TESTA
+TESTC])
+OUTER
+ at end example
+
+ at noindent
+Prior to Autoconf 2.64, the implementation of @code{AC_REQUIRE}
+recognized that @code{TESTB} needed to be hoisted prior to the expansion
+of @code{OUTER}, but because @code{TESTA} had already been directly
+expanded, it failed to hoist @code{TESTA}. Therefore, the expansion of
+ at code{TESTB} occurs prior to its prerequisites, leading to the following
+output:
+
+ at example
+in B
+bug
+in OUTER
+in A
+in C
+ at end example
+
+ at noindent
+Newer Autoconf is smart enough to recognize this situation, and hoists
+ at code{TESTA} even though it has already been expanded, but issues a
+syntax warning in the process. This is because the hoisted expansion of
+ at code{TESTA} defeats the purpose of using @code{AC_REQUIRE} to avoid
+redundant code, and causes its own set of problems if the hoisted macro
+is not idempotent:
+
+ at example
+in A
+in B
+in OUTER
+in A
+duplicate
+in C
+ at end example
+
+The bug is not in Autoconf, but in the macro definitions. If you ever
+pass a particular macro name to @code{AC_REQUIRE}, then you are implying
+that the macro only needs to be expanded once. But to enforce this,
+either the macro must be declared with @code{AC_DEFUN_ONCE} (although
+this only helps in Autoconf 2.64 or newer), or all
+uses of that macro should be through @code{AC_REQUIRE}; directly
+expanding the macro defeats the point of using @code{AC_REQUIRE} to
+eliminate redundant expansion. In the example, this rule of thumb was
+violated because @code{TESTB} requires @code{TESTA} while @code{OUTER}
+directly expands it. One way of fixing the bug is to factor
+ at code{TESTA} into two macros, the portion designed for direct and
+repeated use (here, named @code{TESTA}), and the portion designed for
+one-shot output and used only inside @code{AC_REQUIRE} (here, named
+ at code{TESTA_PREREQ}). Then, by fixing all clients to use the correct
+calling convention according to their needs:
+
+ at example
+AC_DEFUN([TESTA], [AC_REQUIRE([TESTA_PREREQ])[echo in A]])
+AC_DEFUN([TESTA_PREREQ], [[echo in A_PREREQ
+if test -n "$SEEN_A" ; then echo duplicate ; fi
+SEEN_A=:]])
+AC_DEFUN([TESTB], [AC_REQUIRE([TESTA_PREREQ])[echo in B
+if test -z "$SEEN_A" ; then echo bug ; fi]])
+AC_DEFUN([TESTC], [AC_REQUIRE([TESTB])[echo in C]])
+AC_DEFUN([OUTER], [[echo in OUTER]
+TESTA
+TESTC])
+OUTER
+ at end example
+
+ at noindent
+the resulting output will then obey all dependency rules and avoid any
+syntax warnings, whether the script is built with old or new Autoconf
+versions:
+
+ at example
+in A_PREREQ
+in B
+in OUTER
+in A
+in C
+ at end example
+
+The helper macros @code{AS_IF} and @code{AS_CASE} may be used to
+enforce expansion of required macros outside of shell conditional
+constructs. You are furthermore encouraged, although not required, to
+put all @code{AC_REQUIRE} calls
+at the beginning of a macro. You can use @code{dnl} to avoid the empty
+lines they leave.
+
+ at node Suggested Ordering
+ at subsection Suggested Ordering
+ at cindex Macros, ordering
+ at cindex Ordering macros
+
+Some macros should be run before another macro if both are called, but
+neither @emph{requires} that the other be called. For example, a macro
+that changes the behavior of the C compiler should be called before any
+macros that run the C compiler. Many of these dependencies are noted in
+the documentation.
+
+Autoconf provides the @code{AC_BEFORE} macro to warn users when macros
+with this kind of dependency appear out of order in a
+ at file{configure.ac} file. The warning occurs when creating
+ at command{configure} from @file{configure.ac}, not when running
+ at command{configure}.
+
+For example, @code{AC_PROG_CPP} checks whether the C compiler
+can run the C preprocessor when given the @option{-E} option. It should
+therefore be called after any macros that change which C compiler is
+being used, such as @code{AC_PROG_CC}. So @code{AC_PROG_CC} contains:
+
+ at example
+AC_BEFORE([$0], [AC_PROG_CPP])dnl
+ at end example
+
+ at noindent
+This warns the user if a call to @code{AC_PROG_CPP} has already occurred
+when @code{AC_PROG_CC} is called.
+
+ at defmac AC_BEFORE (@var{this-macro-name}, @var{called-macro-name})
+ at acindex{BEFORE}
+Make M4 print a warning message to the standard error output if
+ at var{called-macro-name} has already been called. @var{this-macro-name}
+should be the name of the macro that is calling @code{AC_BEFORE}. The
+macro @var{called-macro-name} must have been defined using
+ at code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
+that it has been called.
+ at end defmac
+
+ at node One-Shot Macros
+ at subsection One-Shot Macros
+ at cindex One-shot macros
+ at cindex Macros, called once
+
+Some macros should be called only once, either because calling them
+multiple time is unsafe, or because it is bad style. For instance
+Autoconf ensures that @code{AC_CANONICAL_BUILD} and cousins
+(@pxref{Canonicalizing}) are evaluated only once, because it makes no
+sense to run these expensive checks more than once. Such one-shot
+macros can be defined using @code{AC_DEFUN_ONCE}.
+
+ at defmac AC_DEFUN_ONCE (@var{macro-name}, @var{macro-body})
+ at acindex{DEFUN_ONCE}
+Declare macro @var{macro-name} like @code{AC_DEFUN} would (@pxref{Macro
+Definitions}), but add additional logic that guarantees that only the
+first use of the macro (whether by direct expansion or
+ at code{AC_REQUIRE}) causes an expansion of @var{macro-body}; the
+expansion will occur before the start of any enclosing macro defined by
+ at code{AC_DEFUN}. Subsequent expansions are silently ignored.
+Generally, it does not make sense for @var{macro-body} to use parameters
+such as @code{$1}.
+ at end defmac
+
+Prior to Autoconf 2.64, a macro defined by @code{AC_DEFUN_ONCE} would
+emit a warning if it was directly expanded a second time, so for
+portability, it is better to use @code{AC_REQUIRE} than direct
+invocation of @var{macro-name} inside a macro defined by @code{AC_DEFUN}
+(@pxref{Prerequisite Macros}).
+
+ at node Obsoleting Macros
+ at section Obsoleting Macros
+ at cindex Obsoleting macros
+ at cindex Macros, obsoleting
+
+Configuration and portability technology has evolved over the years.
+Often better ways of solving a particular problem are developed, or
+ad-hoc approaches are systematized. This process has occurred in many
+parts of Autoconf. One result is that some of the macros are now
+considered @dfn{obsolete}; they still work, but are no longer considered
+the best thing to do, hence they should be replaced with more modern
+macros. Ideally, @command{autoupdate} should replace the old macro calls
+with their modern implementation.
+
+Autoconf provides a simple means to obsolete a macro.
+
+ at anchor{AU_DEFUN}
+ at defmac AU_DEFUN (@var{old-macro}, @var{implementation}, @ovar{message})
+ at auindex{DEFUN}
+Define @var{old-macro} as @var{implementation}. The only difference
+with @code{AC_DEFUN} is that the user is warned that
+ at var{old-macro} is now obsolete.
+
+If she then uses @command{autoupdate}, the call to @var{old-macro} is
+replaced by the modern @var{implementation}. @var{message} should
+include information on what to do after running @command{autoupdate};
+ at command{autoupdate} prints it as a warning, and includes it
+in the updated @file{configure.ac} file.
+
+The details of this macro are hairy: if @command{autoconf} encounters an
+ at code{AU_DEFUN}ed macro, all macros inside its second argument are expanded
+as usual. However, when @command{autoupdate} is run, only M4 and M4sugar
+macros are expanded here, while all other macros are disabled and
+appear literally in the updated @file{configure.ac}.
+ at end defmac
+
+ at defmac AU_ALIAS (@var{old-name}, @var{new-name})
+ at auindex{ALIAS}
+Used if the @var{old-name} is to be replaced by a call to @var{new-macro}
+with the same parameters. This happens for example if the macro was renamed.
+ at end defmac
+
+ at node Coding Style
+ at section Coding Style
+ at cindex Coding style
+
+The Autoconf macros follow a strict coding style. You are encouraged to
+follow this style, especially if you intend to distribute your macro,
+either by contributing it to Autoconf itself or the
+ at uref{http://@/www.gnu.org/@/software/@/autoconf-archive/, Autoconf Macro
+Archive}, or by other means.
+
+The first requirement is to pay great attention to the quotation. For
+more details, see @ref{Autoconf Language}, and @ref{M4 Quotation}.
+
+Do not try to invent new interfaces. It is likely that there is a macro
+in Autoconf that resembles the macro you are defining: try to stick to
+this existing interface (order of arguments, default values, etc.). We
+ at emph{are} conscious that some of these interfaces are not perfect;
+nevertheless, when harmless, homogeneity should be preferred over
+creativity.
+
+Be careful about clashes both between M4 symbols and between shell
+variables.
+
+If you stick to the suggested M4 naming scheme (@pxref{Macro Names}),
+you are unlikely to generate conflicts. Nevertheless, when you need to
+set a special value, @emph{avoid using a regular macro name}; rather,
+use an ``impossible'' name. For instance, up to version 2.13, the macro
+ at code{AC_SUBST} used to remember what @var{symbol} macros were already defined
+by setting @code{AC_SUBST_ at var{symbol}}, which is a regular macro name.
+But since there is a macro named @code{AC_SUBST_FILE}, it was just
+impossible to @samp{AC_SUBST(FILE)}! In this case,
+ at code{AC_SUBST(@var{symbol})} or @code{_AC_SUBST(@var{symbol})} should
+have been used (yes, with the parentheses).
+ at c or better yet, high-level macros such as @code{m4_expand_once}
+
+No Autoconf macro should ever enter the user-variable name space; i.e.,
+except for the variables that are the actual result of running the
+macro, all shell variables should start with @code{ac_}. In
+addition, small macros or any macro that is likely to be embedded in
+other macros should be careful not to use obvious names.
+
+ at cindex @code{dnl}
+Do not use @code{dnl} to introduce comments: most of the comments you
+are likely to write are either header comments which are not output
+anyway, or comments that should make their way into @file{configure}.
+There are exceptional cases where you do want to comment special M4
+constructs, in which case @code{dnl} is right, but keep in mind that it
+is unlikely.
+
+M4 ignores the leading blanks and newlines before each argument.
+Use this feature to
+indent in such a way that arguments are (more or less) aligned with the
+opening parenthesis of the macro being called. For instance, instead of
+
+ at example
+AC_CACHE_CHECK(for EMX OS/2 environment,
+ac_cv_emxos2,
+[AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])],
+[ac_cv_emxos2=yes], [ac_cv_emxos2=no])])
+ at end example
+
+ at noindent
+write
+
+ at example
+AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
+[AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
+ [ac_cv_emxos2=yes],
+ [ac_cv_emxos2=no])])
+ at end example
+
+ at noindent
+or even
+
+ at example
+AC_CACHE_CHECK([for EMX OS/2 environment],
+ [ac_cv_emxos2],
+ [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([],
+ [return __EMX__;])],
+ [ac_cv_emxos2=yes],
+ [ac_cv_emxos2=no])])
+ at end example
+
+When using @code{AC_RUN_IFELSE} or any macro that cannot work when
+cross-compiling, provide a pessimistic value (typically @samp{no}).
+
+Feel free to use various tricks to prevent auxiliary tools, such as
+syntax-highlighting editors, from behaving improperly. For instance,
+instead of:
+
+ at example
+m4_bpatsubst([$1], [$"])
+ at end example
+
+ at noindent
+use
+
+ at example
+m4_bpatsubst([$1], [$""])
+ at end example
+
+ at noindent
+so that Emacsen do not open an endless ``string'' at the first quote.
+For the same reasons, avoid:
+
+ at example
+test $[#] != 0
+ at end example
+
+ at noindent
+and use:
+
+ at example
+test $[@@%:@@] != 0
+ at end example
+
+ at noindent
+Otherwise, the closing bracket would be hidden inside a @samp{#}-comment,
+breaking the bracket-matching highlighting from Emacsen. Note the
+preferred style to escape from M4: @samp{$[1]}, @samp{$[@@]}, etc. Do
+not escape when it is unnecessary. Common examples of useless quotation
+are @samp{[$]$1} (write @samp{$$1}), @samp{[$]var} (use @samp{$var}),
+etc. If you add portability issues to the picture, you'll prefer
+ at samp{$@{1+"$[@@]"@}} to @samp{"[$]@@"}, and you'll prefer do something
+better than hacking Autoconf @code{:-)}.
+
+When using @command{sed}, don't use @option{-e} except for indenting
+purposes. With the @code{s} and @code{y} commands, the preferred
+separator is @samp{/} unless @samp{/} itself might appear in the pattern
+or replacement, in which case you should use @samp{|}, or optionally
+ at samp{,} if you know the pattern and replacement cannot contain a file
+name. If none of these characters will do, choose a printable character
+that cannot appear in the pattern or replacement. Characters from the
+set @samp{"#$&'()*;<=>?`|~} are good choices if the pattern or
+replacement might contain a file name, since they have special meaning
+to the shell and are less likely to occur in file names.
+
+ at xref{Macro Definitions}, for details on how to define a macro. If a
+macro doesn't use @code{AC_REQUIRE}, is expected to never be the object
+of an @code{AC_REQUIRE} directive, and macros required by other macros
+inside arguments do not need to be expanded before this macro, then
+use @code{m4_define}. In case of doubt, use @code{AC_DEFUN}.
+Also take into account that public third-party macros need to use
+ at code{AC_DEFUN} in order to be found by @command{aclocal}
+(@pxref{Extending aclocal,,, automake, GNU Automake}).
+All the @code{AC_REQUIRE} statements should be at the beginning of the
+macro, and each statement should be followed by @code{dnl}.
+
+You should not rely on the number of arguments: instead of checking
+whether an argument is missing, test that it is not empty. It provides
+both a simpler and a more predictable interface to the user, and saves
+room for further arguments.
+
+Unless the macro is short, try to leave the closing @samp{])} at the
+beginning of a line, followed by a comment that repeats the name of the
+macro being defined. This introduces an additional newline in
+ at command{configure}; normally, that is not a problem, but if you want to
+remove it you can use @samp{[]dnl} on the last line. You can similarly
+use @samp{[]dnl} after a macro call to remove its newline. @samp{[]dnl}
+is recommended instead of @samp{dnl} to ensure that M4 does not
+interpret the @samp{dnl} as being attached to the preceding text or
+macro output. For example, instead of:
+
+ at example
+AC_DEFUN([AC_PATH_X],
+[AC_MSG_CHECKING([for X])
+AC_REQUIRE_CPP()
+ at r{# @dots{}omitted at dots{}}
+ AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
+fi])
+ at end example
+
+ at noindent
+you would write:
+
+ at example
+AC_DEFUN([AC_PATH_X],
+[AC_REQUIRE_CPP()[]dnl
+AC_MSG_CHECKING([for X])
+ at r{# @dots{}omitted at dots{}}
+ AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
+fi[]dnl
+])# AC_PATH_X
+ at end example
+
+If the macro is long, try to split it into logical chunks. Typically,
+macros that check for a bug in a function and prepare its
+ at code{AC_LIBOBJ} replacement should have an auxiliary macro to perform
+this setup. Do not hesitate to introduce auxiliary macros to factor
+your code.
+
+In order to highlight the recommended coding style, here is a macro
+written the old way:
+
+ at example
+dnl Check for EMX on OS/2.
+dnl _AC_EMXOS2
+AC_DEFUN(_AC_EMXOS2,
+[AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2,
+[AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)],
+ac_cv_emxos2=yes, ac_cv_emxos2=no)])
+test "x$ac_cv_emxos2" = xyes && EMXOS2=yes])
+ at end example
+
+ at noindent
+and the new way:
+
+ at example
+# _AC_EMXOS2
+# ----------
+# Check for EMX on OS/2.
+m4_define([_AC_EMXOS2],
+[AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
+[AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
+ [ac_cv_emxos2=yes],
+ [ac_cv_emxos2=no])])
+test "x$ac_cv_emxos2" = xyes && EMXOS2=yes[]dnl
+])# _AC_EMXOS2
+ at end example
+
+
+
+
+ at c ============================================= Portable Shell Programming
+
+ at node Portable Shell
+ at chapter Portable Shell Programming
+ at cindex Portable shell programming
+
+When writing your own checks, there are some shell-script programming
+techniques you should avoid in order to make your code portable. The
+Bourne shell and upward-compatible shells like the Korn shell and Bash
+have evolved over the years, and many features added to the original
+System7 shell are now supported on all interesting porting targets.
+However, the following discussion between Russ Allbery and Robert Lipe
+is worth reading:
+
+ at noindent
+Russ Allbery:
+
+ at quotation
+The GNU assumption that @command{/bin/sh} is the one and only shell
+leads to a permanent deadlock. Vendors don't want to break users'
+existing shell scripts, and there are some corner cases in the Bourne
+shell that are not completely compatible with a Posix shell. Thus,
+vendors who have taken this route will @emph{never} (OK at dots{}``never say
+never'') replace the Bourne shell (as @command{/bin/sh}) with a
+Posix shell.
+ at end quotation
+
+ at noindent
+Robert Lipe:
+
+ at quotation
+This is exactly the problem. While most (at least most System V's) do
+have a Bourne shell that accepts shell functions most vendor
+ at command{/bin/sh} programs are not the Posix shell.
+
+So while most modern systems do have a shell @emph{somewhere} that meets the
+Posix standard, the challenge is to find it.
+ at end quotation
+
+For this reason, part of the job of M4sh (@pxref{Programming in M4sh})
+is to find such a shell. But to prevent trouble, if you're not using
+M4sh you should not take advantage of features that were added after Unix
+version 7, circa 1977 (@pxref{Systemology}); you should not use aliases,
+negated character classes, or even @command{unset}. @code{#} comments,
+while not in Unix version 7, were retrofitted in the original Bourne
+shell and can be assumed to be part of the least common denominator.
+
+On the other hand, if you're using M4sh you can assume that the shell
+has the features that were added in SVR2 (circa 1984), including shell
+functions,
+ at command{return}, @command{unset}, and I/O redirection for builtins. For
+more information, refer to @uref{http://@/www.in-ulm.de/@/~mascheck/@/bourne/}.
+However, some pitfalls have to be avoided for portable use of these
+constructs; these will be documented in the rest of this chapter.
+See in particular @ref{Shell Functions} and @ref{Limitations of
+Builtins, , Limitations of Shell Builtins}.
+
+Some ancient systems have quite
+small limits on the length of the @samp{#!} line; for instance, 32
+bytes (not including the newline) on SunOS 4.
+However, these ancient systems are no longer of practical concern.
+
+The set of external programs you should run in a @command{configure} script
+is fairly small. @xref{Utilities in Makefiles, , Utilities in
+Makefiles, standards, The GNU Coding Standards}, for the list. This
+restriction allows users to start out with a fairly small set of
+programs and build the rest, avoiding too many interdependencies between
+packages.
+
+Some of these external utilities have a portable subset of features; see
+ at ref{Limitations of Usual Tools}.
+
+There are other sources of documentation about shells. The
+specification for the Posix
+ at uref{http://@/www.opengroup.org/@/susv3/@/utilities/@/xcu_chap02@/.html, Shell
+Command Language}, though more generous than the restrictive shell
+subset described above, is fairly portable nowadays. Also please see
+ at uref{http://@/www.faqs.org/@/faqs/@/unix-faq/@/shell/, the Shell FAQs}.
+
+ at menu
+* 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
+ at end menu
+
+ at node Shellology
+ at section Shellology
+ at cindex Shellology
+
+There are several families of shells, most prominently the Bourne family
+and the C shell family which are deeply incompatible. If you want to
+write portable shell scripts, avoid members of the C shell family. The
+ at uref{http://@/www.faqs.org/@/faqs/@/unix-faq/@/shell/@/shell-differences/, the
+Shell difference FAQ} includes a small history of Posix shells, and a
+comparison between several of them.
+
+Below we describe some of the members of the Bourne shell family.
+
+ at table @asis
+ at item Ash
+ at cindex Ash
+Ash is often used on GNU/Linux and BSD
+systems as a light-weight Bourne-compatible shell. Ash 0.2 has some
+bugs that are fixed in the 0.3.x series, but portable shell scripts
+should work around them, since version 0.2 is still shipped with many
+GNU/Linux distributions.
+
+To be compatible with Ash 0.2:
+
+ at itemize @minus
+ at item
+don't use @samp{$?} after expanding empty or unset variables,
+or at the start of an @command{eval}:
+
+ at example
+foo=
+false
+$foo
+echo "Do not use it: $?"
+false
+eval 'echo "Do not use it: $?"'
+ at end example
+
+ at item
+don't use command substitution within variable expansion:
+
+ at example
+cat $@{FOO=`bar`@}
+ at end example
+
+ at item
+beware that single builtin substitutions are not performed by a
+subshell, hence their effect applies to the current shell! @xref{Shell
+Substitutions}, item ``Command Substitution''.
+ at end itemize
+
+ at item Bash
+ at cindex Bash
+To detect whether you are running Bash, test whether
+ at code{BASH_VERSION} is set. To require
+Posix compatibility, run @samp{set -o posix}. @xref{Bash POSIX
+Mode, , Bash Posix Mode, bash, The GNU Bash Reference
+Manual}, for details.
+
+ at item Bash 2.05 and later
+ at cindex Bash 2.05 and later
+Versions 2.05 and later of Bash use a different format for the
+output of the @command{set} builtin, designed to make evaluating its
+output easier. However, this output is not compatible with earlier
+versions of Bash (or with many other shells, probably). So if
+you use Bash 2.05 or higher to execute @command{configure},
+you'll need to use Bash 2.05 for all other build tasks as well.
+
+ at item Ksh
+ at cindex Ksh
+ at cindex Korn shell
+ at prindex @samp{ksh}
+ at prindex @samp{ksh88}
+ at prindex @samp{ksh93}
+The Korn shell is compatible with the Bourne family and it mostly
+conforms to Posix. It has two major variants commonly
+called @samp{ksh88} and @samp{ksh93}, named after the years of initial
+release. It is usually called @command{ksh}, but is called @command{sh}
+on some hosts if you set your path appropriately.
+
+Solaris systems have three variants:
+ at prindex @command{/usr/bin/ksh} on Solaris
+ at command{/usr/bin/ksh} is @samp{ksh88}; it is
+standard on Solaris 2.0 and later.
+ at prindex @command{/usr/xpg4/bin/sh} on Solaris
+ at command{/usr/xpg4/bin/sh} is a Posix-compliant variant of
+ at samp{ksh88}; it is standard on Solaris 9 and later.
+ at prindex @command{/usr/dt/bin/dtksh} on Solaris
+ at command{/usr/dt/bin/dtksh} is @samp{ksh93}.
+Variants that are not standard may be parts of optional
+packages. There is no extra charge for these packages, but they are
+not part of a minimal OS install and therefore some installations may
+not have it.
+
+Starting with Tru64 Version 4.0, the Korn shell @command{/usr/bin/ksh}
+is also available as @command{/usr/bin/posix/sh}. If the environment
+variable @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of
+the standard shell conform to Posix.
+
+ at item Pdksh
+ at prindex @samp{pdksh}
+A public-domain clone of the Korn shell called @command{pdksh} is widely
+available: it has most of the @samp{ksh88} features along with a few of
+its own. It usually sets @code{KSH_VERSION}, except if invoked as
+ at command{/bin/sh} on OpenBSD, and similarly to Bash you can require
+Posix compatibility by running @samp{set -o posix}. Unfortunately, with
+ at command{pdksh} 5.2.14 (the latest stable version as of January 2007)
+Posix mode is buggy and causes @command{pdksh} to depart from Posix in
+at least one respect, see @ref{Shell Substitutions}.
+
+ at item Zsh
+ at cindex Zsh
+To detect whether you are running @command{zsh}, test whether
+ at code{ZSH_VERSION} is set. By default @command{zsh} is @emph{not}
+compatible with the Bourne shell: you must execute @samp{emulate sh},
+and for @command{zsh} versions before 3.1.6-dev-18 you must also
+set @code{NULLCMD} to @samp{:}. @xref{Compatibility, , Compatibility,
+zsh, The Z Shell Manual}, for details.
+
+The default Mac OS X @command{sh} was originally Zsh; it was changed to
+Bash in Mac OS X 10.2.
+ at end table
+
+ at node Invoking the Shell
+ at section Invoking the Shell
+ at cindex invoking the shell
+ at cindex shell invocation
+
+The Korn shell (up to at least version M-12/28/93d) has a bug when
+invoked on a file whose name does not contain a slash. It first
+searches for the file's name in @env{PATH}, and if found it executes
+that rather than the original file. For example, assuming there is a
+binary executable @file{/usr/bin/script} in your @env{PATH}, the last
+command in the following example fails because the Korn shell finds
+ at file{/usr/bin/script} and refuses to execute it as a shell script:
+
+ at example
+$ @kbd{touch xxyzzyz script}
+$ @kbd{ksh xxyzzyz}
+$ @kbd{ksh ./script}
+$ @kbd{ksh script}
+ksh: script: cannot execute
+ at end example
+
+Bash 2.03 has a bug when invoked with the @option{-c} option: if the
+option-argument ends in backslash-newline, Bash incorrectly reports a
+syntax error. The problem does not occur if a character follows the
+backslash:
+
+ at example
+$ @kbd{$ bash -c 'echo foo \}
+> @kbd{'}
+bash: -c: line 2: syntax error: unexpected end of file
+$ @kbd{bash -c 'echo foo \}
+> @kbd{ '}
+foo
+ at end example
+
+ at noindent
+ at xref{Backslash-Newline-Empty}, for how this can cause problems in makefiles.
+
+ at node Here-Documents
+ at section Here-Documents
+ at cindex Here-documents
+ at cindex Shell here-documents
+
+Don't rely on @samp{\} being preserved just because it has no special
+meaning together with the next symbol. In the native @command{sh}
+on OpenBSD 2.7 @samp{\"} expands to @samp{"} in here-documents with
+unquoted delimiter. As a general rule, if @samp{\\} expands to @samp{\}
+use @samp{\\} to get @samp{\}.
+
+With OpenBSD 2.7's @command{sh}
+
+ at example
+ at group
+$ @kbd{cat <<EOF
+> \" \\
+> EOF}
+" \
+ at end group
+ at end example
+
+ at noindent
+and with Bash:
+
+ at example
+ at group
+bash-2.04$ @kbd{cat <<EOF
+> \" \\
+> EOF}
+\" \
+ at end group
+ at end example
+
+Using command substitutions in a here-document that is fed to a shell
+function is not portable. For example, with Solaris 10 @command{/bin/sh}:
+
+ at example
+$ @kbd{kitty () @{ cat; @}}
+$ @kbd{kitty <<EOF
+> `echo ok`
+> EOF}
+/tmp/sh199886: cannot open
+$ @kbd{echo $?}
+1
+ at end example
+
+Some shells mishandle large here-documents: for example,
+Solaris 10 @command{dtksh} and the UnixWare 7.1.1 Posix shell, which are
+derived from Korn shell version M-12/28/93d, mishandle braced variable
+expansion that crosses a 1024- or 4096-byte buffer boundary
+within a here-document. Only the part of the variable name after the boundary
+is used. For example, @code{$@{variable@}} could be replaced by the expansion
+of @code{$@{ble@}}. If the end of the variable name is aligned with the block
+boundary, the shell reports an error, as if you used @code{$@{@}}.
+Instead of @code{$@{variable-default@}}, the shell may expand
+ at code{$@{riable-default@}}, or even @code{$@{fault@}}. This bug can often
+be worked around by omitting the braces: @code{$variable}. The bug was
+fixed in
+ at samp{ksh93g} (1998-04-30) but as of 2006 many operating systems were
+still shipping older versions with the bug.
+
+Empty here-documents are not portable either; with the following code,
+ at command{zsh} up to at least version 4.3.10 creates a file with a single
+newline, whereas other shells create an empty file:
+
+ at example
+cat >file <<EOF
+EOF
+ at end example
+
+Many shells (including the Bourne shell) implement here-documents
+inefficiently. In particular, some shells can be extremely inefficient when
+a single statement contains many here-documents. For instance if your
+ at file{configure.ac} includes something like:
+
+ at example
+ at group
+if <cross_compiling>; then
+ assume this and that
+else
+ check this
+ check that
+ check something else
+ @dots{}
+ on and on forever
+ @dots{}
+fi
+ at end group
+ at end example
+
+A shell parses the whole @code{if}/@code{fi} construct, creating
+temporary files for each here-document in it. Some shells create links
+for such here-documents on every @code{fork}, so that the clean-up code
+they had installed correctly removes them. It is creating the links
+that can take the shell forever.
+
+Moving the tests out of the @code{if}/@code{fi}, or creating multiple
+ at code{if}/@code{fi} constructs, would improve the performance
+significantly. Anyway, this kind of construct is not exactly the
+typical use of Autoconf. In fact, it's even not recommended, because M4
+macros can't look into shell conditionals, so we may fail to expand a
+macro when it was expanded before in a conditional path, and the
+condition turned out to be false at runtime, and we end up not
+executing the macro at all.
+
+Be careful with the use of @samp{<<-} to unindent here-documents. The
+behavior is only portable for stripping leading @key{TAB}s, and things
+can silently break if an overzealous editor converts to using leading
+spaces (not all shells are nice enough to warn about unterminated
+here-documents).
+
+ at example
+$ @kbd{printf 'cat <<-x\n\t1\n\t 2\n\tx\n' | bash && echo done}
+1
+ 2
+done
+$ @kbd{printf 'cat <<-x\n 1\n 2\n x\n' | bash-3.2 && echo done}
+ 1
+ 2
+ x
+done
+ at end example
+
+ at node File Descriptors
+ at section File Descriptors
+ at cindex Descriptors
+ at cindex File descriptors
+ at cindex Shell file descriptors
+
+Most shells, if not all (including Bash, Zsh, Ash), output traces on
+stderr, even for subshells. This might result in undesirable content
+if you meant to capture the standard-error output of the inner command:
+
+ at example
+$ @kbd{ash -x -c '(eval "echo foo >&2") 2>stderr'}
+$ @kbd{cat stderr}
++ eval echo foo >&2
++ echo foo
+foo
+$ @kbd{bash -x -c '(eval "echo foo >&2") 2>stderr'}
+$ @kbd{cat stderr}
++ eval 'echo foo >&2'
+++ echo foo
+foo
+$ @kbd{zsh -x -c '(eval "echo foo >&2") 2>stderr'}
+ at i{# Traces on startup files deleted here.}
+$ @kbd{cat stderr}
++zsh:1> eval echo foo >&2
++zsh:1> echo foo
+foo
+ at end example
+
+ at noindent
+One workaround is to grep out uninteresting lines, hoping not to remove
+good ones.
+
+If you intend to redirect both standard error and standard output,
+redirect standard output first. This works better with HP-UX,
+since its shell mishandles tracing if standard error is redirected
+first:
+
+ at example
+$ @kbd{sh -x -c ': 2>err >out'}
++ :
++ 2> err $ @kbd{cat err}
+1> out
+ at end example
+
+Don't try to redirect the standard error of a command substitution. It
+must be done @emph{inside} the command substitution. When running
+ at samp{: `cd /zorglub` 2>/dev/null} expect the error message to
+escape, while @samp{: `cd /zorglub 2>/dev/null`} works properly.
+
+On the other hand, some shells, such as Solaris or FreeBSD
+ at command{/bin/sh}, warn about missing programs before performing
+redirections. Therefore, to silently check whether a program exists, it
+is necessary to perform redirections on a subshell or brace group:
+ at example
+$ @kbd{/bin/sh -c 'nosuch 2>/dev/null'}
+nosuch: not found
+$ @kbd{/bin/sh -c '(nosuch) 2>/dev/null'}
+$ @kbd{/bin/sh -c '@{ nosuch; @} 2>/dev/null'}
+$ @kbd{bash -c 'nosuch 2>/dev/null'}
+ at end example
+
+FreeBSD 6.2 sh may mix the trace output lines from the statements in a
+shell pipeline.
+
+It is worth noting that Zsh (but not Ash nor Bash) makes it possible
+in assignments though: @samp{foo=`cd /zorglub` 2>/dev/null}.
+
+Some shells, like @command{ash}, don't recognize bi-directional
+redirection (@samp{<>}). And even on shells that recognize it, it is
+not portable to use on fifos: Posix does not require read-write support
+for named pipes, and Cygwin does not support it:
+
+ at example
+$ @kbd{mkfifo fifo}
+$ @kbd{exec 5<>fifo}
+$ @kbd{echo hi >&5}
+bash: echo: write error: Communication error on send
+ at end example
+
+ at noindent
+Furthermore, versions of @command{dash} before 0.5.6 mistakenly truncate
+regular files when using @samp{<>}:
+
+ at example
+$ @kbd{echo a > file}
+$ @kbd{bash -c ': 1<>file'; cat file}
+a
+$ @kbd{dash -c ': 1<>file'; cat file}
+$ rm a
+ at end example
+
+When catering to old systems, don't redirect the same file descriptor
+several times, as you are doomed to failure under Ultrix.
+
+ at example
+ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995
+UWS V4.4 (Rev. 11)
+$ @kbd{eval 'echo matter >fullness' >void}
+illegal io
+$ @kbd{eval '(echo matter >fullness)' >void}
+illegal io
+$ @kbd{(eval '(echo matter >fullness)') >void}
+Ambiguous output redirect.
+ at end example
+
+ at noindent
+In each case the expected result is of course @file{fullness} containing
+ at samp{matter} and @file{void} being empty. However, this bug is
+probably not of practical concern to modern platforms.
+
+Solaris 10 @command{sh} will try to optimize away a @command{:} command
+(even if it is redirected) in a loop after the first iteration, or in a
+shell function after the first call:
+
+ at example
+$ @kbd{for i in 1 2 3 ; do : >x$i; done}
+$ @kbd{ls x*}
+x1
+$ @kbd{f () @{ : >$1; @}; f y1; f y2; f y3;}
+$ @kbd{ls y*}
+y1
+ at end example
+
+ at noindent
+As a workaround, @command{echo} or @command{eval} can be used.
+
+Don't rely on file descriptors 0, 1, and 2 remaining closed in a
+subsidiary program. If any of these descriptors is closed, the
+operating system may open an unspecified file for the descriptor in the
+new process image. Posix 2008 says this may be done only if the
+subsidiary program is set-user-ID or set-group-ID, but HP-UX 11.23 does
+it even for ordinary programs, and the next version of Posix will allow
+HP-UX behavior.
+
+If you want a file descriptor above 2 to be inherited into a child
+process, then you must use redirections specific to that command or a
+containing subshell or command group, rather than relying on
+ at command{exec} in the shell. In @command{ksh} as well as HP-UX
+ at command{sh}, file descriptors above 2 which are opened using
+ at samp{exec @var{n}>file} are closed by a subsequent @samp{exec} (such as
+that involved in the fork-and-exec which runs a program or script):
+
+ at example
+$ @kbd{echo 'echo hello >&5' >k}
+$ @kbd{/bin/sh -c 'exec 5>t; ksh ./k; exec 5>&-; cat t}
+hello
+$ @kbd{bash -c 'exec 5>t; ksh ./k; exec 5>&-; cat t}
+hello
+$ @kbd{ksh -c 'exec 5>t; ksh ./k; exec 5>&-; cat t}
+./k[1]: 5: cannot open [Bad file number]
+$ @kbd{ksh -c '(ksh ./k) 5>t; cat t'}
+hello
+$ @kbd{ksh -c '@{ ksh ./k; @} 5>t; cat t'}
+hello
+$ @kbd{ksh -c '5>t ksh ./k; cat t}
+hello
+ at end example
+
+Don't rely on duplicating a closed file descriptor to cause an
+error. With Solaris @command{/bin/sh}, failed duplication is silently
+ignored, which can cause unintended leaks to the original file
+descriptor. In this example, observe the leak to standard output:
+
+ at example
+$ @kbd{bash -c 'echo hi >&3' 3>&-; echo $?}
+bash: 3: Bad file descriptor
+1
+$ @kbd{/bin/sh -c 'echo hi >&3' 3>&-; echo $?}
+hi
+0
+ at end example
+
+Fortunately, an attempt to close an already closed file descriptor will
+portably succeed. Likewise, it is safe to use either style of
+ at samp{@var{n}<&-} or @samp{@var{n}>&-} for closing a file descriptor,
+even if it doesn't match the read/write mode that the file descriptor
+was opened with.
+
+DOS variants cannot rename or remove open files, such as in
+ at samp{mv foo bar >foo} or @samp{rm foo >foo}, even though this is
+perfectly portable among Posix hosts.
+
+A few ancient systems reserved some file descriptors. By convention,
+file descriptor 3 was opened to @file{/dev/tty} when you logged into
+Eighth Edition (1985) through Tenth Edition Unix (1989). File
+descriptor 4 had a special use on the Stardent/Kubota Titan (circa
+1990), though we don't now remember what it was. Both these systems are
+obsolete, so it's now safe to treat file descriptors 3 and 4 like any
+other file descriptors.
+
+On the other hand, you can't portably use multi-digit file descriptors.
+Solaris @command{ksh} doesn't understand any file descriptor larger than
+ at samp{9}:
+
+ at example
+$ @kbd{bash -c 'exec 10>&-'; echo $?}
+0
+$ @kbd{ksh -c 'exec 9>&-'; echo $?}
+0
+$ @kbd{ksh -c 'exec 10>&-'; echo $?}
+ksh[1]: exec: 10: not found
+127
+ at end example
+
+ at c <http://lists.gnu.org/archive/html/bug-autoconf/2011-09/msg00004.html>
+ at node Signal Handling
+ at section Signal Handling
+ at cindex Signal handling in the shell
+ at cindex Signals, shells and
+
+Portable handling of signals within the shell is another major source of
+headaches. This is worsened by the fact that various different, mutually
+incompatible approaches are possible in this area, each with its
+distinctive merits and demerits. A detailed description of these possible
+approaches, as well as of their pros and cons, can be found in
+ at uref{http://www.cons.org/cracauer/sigint.html, this article}.
+
+Solaris 10 @command{/bin/sh} automatically traps most signals by default;
+ at c See: <http://dbaspot.com/shell/396118-bourne-shell-exit-code-term.html>
+the shell still exits with error upon termination by one of those signals,
+but in such a case the exit status might be somewhat unexpected (even if
+allowed by POSIX, strictly speaking):
+
+ at example
+$ @kbd{bash -c 'kill -1 $$'; echo $?} # Will exit 128 + (signal number).
+Hangup
+129
+$ @kbd{/bin/ksh -c 'kill -15 $$'; echo $?} # Likewise.
+Terminated
+143
+$ @kbd{for sig in 1 2 3 15; do}
+> @kbd{ echo $sig:}
+> @kbd{ /bin/sh -c "kill -$s \$\$"; echo $?}
+> @kbd{done}
+signal 1:
+Hangup
+129
+signal 2:
+208
+signal 3:
+208
+signal 15:
+208
+ at end example
+
+This gets even worse if one is using the POSIX `wait' interface to get
+details about the shell process terminations: it will result in the shell
+having exited normally, rather than by receiving a signal.
+
+ at example
+$ @kbd{cat > foo.c <<'END'}
+#include <stdio.h> /* for printf */
+#include <stdlib.h> /* for system */
+#include <sys/wait.h> /* for WIF* macros */
+int main(void)
+@{
+ int status = system ("kill -15 $$");
+ printf ("Terminated by signal: %s\n",
+ WIFSIGNALED (status) ? "yes" : "no");
+ printf ("Exited normally: %s\n",
+ WIFEXITED (status) ? "yes" : "no");
+ return 0;
+@}
+END
+ at c $$ font-lock
+$ @kbd{cc -o foo foo.c}
+$ @kbd{./a.out} # On GNU/Linux
+Terminated by signal: no
+Exited normally: yes
+$ @kbd{./a.out} # On Solaris 10
+Terminated by signal: yes
+Exited normally: no
+ at end example
+
+Various shells seem to handle @code{SIGQUIT} specially: they ignore it even
+if it is not blocked, and even if the shell is not running interactively
+(in fact, even if the shell has no attached tty); among these shells
+are at least Bash (from version 2 onwards), Zsh 4.3.12, Solaris 10
+ at code{/bin/ksh} and @code{/usr/xpg4/bin/sh}, and AT&T @code{ksh93} (2011).
+Still, @code{SIGQUIT} seems to be trappable quite portably within all
+these shells. OTOH, some other shells doesn't special-case the handling
+of @code{SIGQUIT}; among these shells are at least @code{pdksh} 5.2.14,
+Solaris 10 and NetBSD 5.1 @code{/bin/sh}, and the Almquist Shell 0.5.5.1.
+
+ at c See: <http://mail.opensolaris.org/pipermail/ksh93-integration-discuss/2009-February/004121.html>
+Some shells (especially Korn shells and derivatives) might try to
+propagate to themselves a signal that has killed a child process; this is
+not a bug, but a conscious design choice (although its overall value might
+be debatable). The exact details of how this is attained vary from shell
+to shell. For example, upon running @code{perl -e 'kill 2, $$'}, after
+the perl process has been interrupted AT&T @code{ksh93} (2011) will
+proceed to send itself a @code{SIGINT}, while Solaris 10 @code{/bin/ksh}
+and @code{/usr/xpg4/bin/sh} will proceed to exit with status 130 (i.e.,
+128 + 2). In any case, if there is an active trap associated with
+ at code{SIGINT}, those shells will correctly execute it.
+
+ at c See: <http://www.austingroupbugs.net/view.php?id=51>
+Some Korn shells, when a child process die due receiving a signal with
+signal number @var{n}, can leave in @samp{$?} an exit status of
+256+ at var{n} instead of the more common 128+ at var{n}. Observe the
+difference between AT&T @code{ksh93} (2011) and @code{bash} 4.1.5 on
+Debian:
+
+ at example
+$ @kbd{/bin/ksh -c 'sh -c "kill -1 \$\$"; echo $?'}
+/bin/ksh: line 1: 7837: Hangup
+257
+$ @kbd{/bin/bash -c 'sh -c "kill -1 \$\$"; echo $?'}
+/bin/bash: line 1: 7861 Hangup (sh -c "kill -1 \$\$")
+129
+ at end example
+
+ at noindent
+This @command{ksh} behavior is allowed by POSIX, if implemented with
+due care; see this @uref{http://www.austingroupbugs.net/view.php?id=51,
+Austin Group discussion} for more background. However, if it is not
+implemented with proper care, such a behavior might cause problems
+in some corner cases. To see why, assume we have a ``wrapper'' script
+like this:
+
+ at example
+#!/bin/sh
+# Ignore some signals in the shell only, not in its child processes.
+trap : 1 2 13 15
+wrapped_command "$@@"
+ret=$?
+other_command
+exit $ret
+ at end example
+
+ at noindent
+If @command{wrapped_command} is interrupted by a @code{SIGHUP} (which
+has signal number 1), @code{ret} will be set to 257. Unless the
+ at command{exit} shell builtin is smart enough to understand that such
+a value can only have originated from a signal, and adjust the final
+wait status of the shell appropriately, the value 257 will just get
+truncated to 1 by the closing @code{exit} call, so that a caller of
+the script will have no way to determine that termination by a signal
+was involved. Observe the different behavior of AT&T @code{ksh93}
+(2011) and @code{bash} 4.1.5 on Debian:
+
+ at example
+$ @kbd{cat foo.sh}
+#!/bin/sh
+sh -c 'kill -1 $$'
+ret=$?
+echo $ret
+exit $ret
+$ @kbd{/bin/ksh foo.sh; echo $?}
+foo.sh: line 2: 12479: Hangup
+257
+1
+$ @kbd{/bin/bash foo.sh; echo $?}
+foo.sh: line 2: 12487 Hangup (sh -c 'kill -1 $$')
+129
+129
+ at end example
+
+ at node File System Conventions
+ at section File System Conventions
+ at cindex File system conventions
+
+Autoconf uses shell-script processing extensively, so the file names
+that it processes should not contain characters that are special to the
+shell. Special characters include space, tab, newline, NUL, and
+the following:
+
+ at example
+" # $ & ' ( ) * ; < = > ? [ \ ` |
+ at end example
+
+Also, file names should not begin with @samp{~} or @samp{-}, and should
+contain neither @samp{-} immediately after @samp{/} nor @samp{~}
+immediately after @samp{:}. On Posix-like platforms, directory names
+should not contain @samp{:}, as this runs afoul of @samp{:} used as the
+path separator.
+
+These restrictions apply not only to the files that you distribute, but
+also to the absolute file names of your source, build, and destination
+directories.
+
+On some Posix-like platforms, @samp{!} and @samp{^} are special too, so
+they should be avoided.
+
+Posix lets implementations treat leading @file{//} specially, but
+requires leading @file{///} and beyond to be equivalent to @file{/}.
+Most Unix variants treat @file{//} like @file{/}. However, some treat
+ at file{//} as a ``super-root'' that can provide access to files that are
+not otherwise reachable from @file{/}. The super-root tradition began
+with Apollo Domain/OS, which died out long ago, but unfortunately Cygwin
+has revived it.
+
+While @command{autoconf} and friends are usually run on some Posix
+variety, they can be used on other systems, most notably DOS
+variants. This impacts several assumptions regarding file names.
+
+ at noindent
+For example, the following code:
+
+ at example
+case $foo_dir in
+ /*) # Absolute
+ ;;
+ *)
+ foo_dir=$dots$foo_dir ;;
+esac
+ at end example
+
+ at noindent
+fails to properly detect absolute file names on those systems, because
+they can use a drivespec, and usually use a backslash as directory
+separator. If you want to be portable to DOS variants (at the
+price of rejecting valid but oddball Posix file names like @file{a:\b}),
+you can check for absolute file names like this:
+
+ at cindex absolute file names, detect
+ at example
+case $foo_dir in
+ [\\/]* | ?:[\\/]* ) # Absolute
+ ;;
+ *)
+ foo_dir=$dots$foo_dir ;;
+esac
+ at end example
+
+ at noindent
+Make sure you quote the brackets if appropriate and keep the backslash as
+first character (@pxref{case, , Limitations of Shell Builtins}).
+
+Also, because the colon is used as part of a drivespec, these systems don't
+use it as path separator. When creating or accessing paths, you can use the
+ at code{PATH_SEPARATOR} output variable instead. @command{configure} sets this
+to the appropriate value for the build system (@samp{:} or @samp{;}) when it
+starts up.
+
+File names need extra care as well. While DOS variants
+that are Posixy enough to run @command{autoconf} (such as DJGPP)
+are usually able to handle long file names properly, there are still
+limitations that can seriously break packages. Several of these issues
+can be easily detected by the
+ at uref{ftp://@/ftp.gnu.org/@/gnu/@/non-gnu/@/doschk/@/doschk-1.1.tar.gz, doschk}
+package.
+
+A short overview follows; problems are marked with SFN/LFN to
+indicate where they apply: SFN means the issues are only relevant to
+plain DOS, not to DOS under Microsoft Windows
+variants, while LFN identifies problems that exist even under
+Microsoft Windows variants.
+
+ at table @asis
+ at item No multiple dots (SFN)
+DOS cannot handle multiple dots in file names. This is an especially
+important thing to remember when building a portable configure script,
+as @command{autoconf} uses a .in suffix for template files.
+
+This is perfectly OK on Posix variants:
+
+ at example
+AC_CONFIG_HEADERS([config.h])
+AC_CONFIG_FILES([source.c foo.bar])
+AC_OUTPUT
+ at end example
+
+ at noindent
+but it causes problems on DOS, as it requires @samp{config.h.in},
+ at samp{source.c.in} and @samp{foo.bar.in}. To make your package more portable
+to DOS-based environments, you should use this instead:
+
+ at example
+AC_CONFIG_HEADERS([config.h:config.hin])
+AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in])
+AC_OUTPUT
+ at end example
+
+ at item No leading dot (SFN)
+DOS cannot handle file names that start with a dot. This is usually
+not important for @command{autoconf}.
+
+ at item Case insensitivity (LFN)
+DOS is case insensitive, so you cannot, for example, have both a
+file called @samp{INSTALL} and a directory called @samp{install}. This
+also affects @command{make}; if there's a file called @samp{INSTALL} in
+the directory, @samp{make install} does nothing (unless the
+ at samp{install} target is marked as PHONY).
+
+ at item The 8+3 limit (SFN)
+Because the DOS file system only stores the first 8 characters of
+the file name and the first 3 of the extension, those must be unique.
+That means that @file{foobar-part1.c}, @file{foobar-part2.c} and
+ at file{foobar-prettybird.c} all resolve to the same file name
+(@file{FOOBAR-P.C}). The same goes for @file{foo.bar} and
+ at file{foo.bartender}.
+
+The 8+3 limit is not usually a problem under Microsoft Windows, as it
+uses numeric
+tails in the short version of file names to make them unique. However, a
+registry setting can turn this behavior off. While this makes it
+possible to share file trees containing long file names between SFN
+and LFN environments, it also means the above problem applies there
+as well.
+
+ at item Invalid characters (LFN)
+Some characters are invalid in DOS file names, and should therefore
+be avoided. In a LFN environment, these are @samp{/}, @samp{\},
+ at samp{?}, @samp{*}, @samp{:}, @samp{<}, @samp{>}, @samp{|} and @samp{"}.
+In a SFN environment, other characters are also invalid. These
+include @samp{+}, @samp{,}, @samp{[} and @samp{]}.
+
+ at item Invalid names (LFN)
+Some DOS file names are reserved, and cause problems if you
+try to use files with those names. These names include @file{CON},
+ at file{AUX}, @file{COM1}, @file{COM2}, @file{COM3}, @file{COM4},
+ at file{LPT1}, @file{LPT2}, @file{LPT3}, @file{NUL}, and @file{PRN}.
+File names are case insensitive, so even names like
+ at file{aux/config.guess} are disallowed.
+
+ at end table
+
+ at node Shell Pattern Matching
+ at section Shell Pattern Matching
+ at cindex Shell pattern matching
+
+Nowadays portable patterns can use negated character classes like
+ at samp{[!-aeiou]}. The older syntax @samp{[^-aeiou]} is supported by
+some shells but not others; hence portable scripts should never use
+ at samp{^} as the first character of a bracket pattern.
+
+Outside the C locale, patterns like @samp{[a-z]} are problematic since
+they may match characters that are not lower-case letters.
+
+ at node Shell Substitutions
+ at section Shell Substitutions
+ at cindex Shell substitutions
+
+Contrary to a persistent urban legend, the Bourne shell does not
+systematically split variables and back-quoted expressions, in particular
+on the right-hand side of assignments and in the argument of @code{case}.
+For instance, the following code:
+
+ at example
+case "$given_srcdir" in
+.) top_srcdir="`echo "$dots" | sed 's|/$||'`" ;;
+*) top_srcdir="$dots$given_srcdir" ;;
+esac
+ at end example
+
+ at noindent
+is more readable when written as:
+
+ at example
+case $given_srcdir in
+.) top_srcdir=`echo "$dots" | sed 's|/$||'` ;;
+*) top_srcdir=$dots$given_srcdir ;;
+esac
+ at end example
+
+ at noindent
+and in fact it is even @emph{more} portable: in the first case of the
+first attempt, the computation of @code{top_srcdir} is not portable,
+since not all shells properly understand @code{"`@dots{}"@dots{}"@dots{}`"},
+for example Solaris 10 ksh:
+
+ at example
+$ @kbd{foo="`echo " bar" | sed 's, ,,'`"}
+ksh: : cannot execute
+ksh: bar | sed 's, ,,': cannot execute
+ at end example
+
+ at noindent
+Posix does not specify behavior for this sequence. On the other hand,
+behavior for @code{"`@dots{}\"@dots{}\"@dots{}`"} is specified by Posix,
+but in practice, not all shells understand it the same way: pdksh 5.2.14
+prints spurious quotes when in Posix mode:
+
+ at example
+$ @kbd{echo "`echo \"hello\"`"}
+hello
+$ @kbd{set -o posix}
+$ @kbd{echo "`echo \"hello\"`"}
+"hello"
+ at end example
+
+ at noindent
+There is just no portable way to use double-quoted strings inside
+double-quoted back-quoted expressions (pfew!).
+
+Bash 4.1 has a bug where quoted empty strings adjacent to unquoted
+parameter expansions are elided during word splitting. Meanwhile, zsh
+does not perform word splitting except when in Bourne compatibility
+mode. In the example below, the correct behavior is to have five
+arguments to the function, and exactly two spaces on either side of the
+middle @samp{-}, since word splitting collapses multiple spaces in
+ at samp{$f} but leaves empty arguments intact.
+
+ at example
+$ @kbd{bash -c 'n() @{ echo "$#$@@"; @}; f=" - "; n - ""$f"" -'}
+3- - -
+$ @kbd{ksh -c 'n() @{ echo "$#$@@"; @}; f=" - "; n - ""$f"" -'}
+5- - -
+$ @kbd{zsh -c 'n() @{ echo "$#$@@"; @}; f=" - "; n - ""$f"" -'}
+3- - -
+$ @kbd{zsh -c 'emulate sh;}
+> @kbd{n() @{ echo "$#$@@"; @}; f=" - "; n - ""$f"" -'}
+5- - -
+ at end example
+
+ at noindent
+You can work around this by doing manual word splitting, such as using
+ at samp{"$str" $list} rather than @samp{"$str"$list}.
+
+There are also portability pitfalls with particular expansions:
+
+ at table @code
+ at item $@@
+ at cindex @code{"$@@"}
+One of the most famous shell-portability issues is related to
+ at samp{"$@@"}. When there are no positional arguments, Posix says
+that @samp{"$@@"} is supposed to be equivalent to nothing, but the
+original Unix version 7 Bourne shell treated it as equivalent to
+ at samp{""} instead, and this behavior survives in later implementations
+like Digital Unix 5.0.
+
+The traditional way to work around this portability problem is to use
+ at samp{$@{1+"$@@"@}}. Unfortunately this method does not work with
+Zsh (3.x and 4.x), which is used on Mac OS X at . When emulating
+the Bourne shell, Zsh performs word splitting on @samp{$@{1+"$@@"@}}:
+
+ at example
+zsh $ @kbd{emulate sh}
+zsh $ @kbd{for i in "$@@"; do echo $i; done}
+Hello World
+!
+zsh $ @kbd{for i in $@{1+"$@@"@}; do echo $i; done}
+Hello
+World
+!
+ at end example
+
+ at noindent
+Zsh handles plain @samp{"$@@"} properly, but we can't use plain
+ at samp{"$@@"} because of the portability problems mentioned above.
+One workaround relies on Zsh's ``global aliases'' to convert
+ at samp{$@{1+"$@@"@}} into @samp{"$@@"} by itself:
+
+ at example
+test "$@{ZSH_VERSION+set@}" = set && alias -g '$@{1+"$@@"@}'='"$@@"'
+ at end example
+
+Zsh only recognizes this alias when a shell word matches it exactly;
+ at samp{"foo"$@{1+"$@@"@}} remains subject to word splitting. Since this
+case always yields at least one shell word, use plain @samp{"$@@"}.
+
+A more conservative workaround is to avoid @samp{"$@@"} if it is
+possible that there may be no positional arguments. For example,
+instead of:
+
+ at example
+cat conftest.c "$@@"
+ at end example
+
+you can use this instead:
+
+ at example
+case $# in
+0) cat conftest.c;;
+*) cat conftest.c "$@@";;
+esac
+ at end example
+
+Autoconf macros often use the @command{set} command to update
+ at samp{$@@}, so if you are writing shell code intended for
+ at command{configure} you should not assume that the value of @samp{$@@}
+persists for any length of time.
+
+
+ at item $@{10@}
+ at cindex positional parameters
+The 10th, 11th, @dots{} positional parameters can be accessed only after
+a @code{shift}. The 7th Edition shell reported an error if given
+ at code{$@{10@}}, and
+Solaris 10 @command{/bin/sh} still acts that way:
+
+ at example
+$ @kbd{set 1 2 3 4 5 6 7 8 9 10}
+$ @kbd{echo $@{10@}}
+bad substitution
+ at end example
+
+Conversely, not all shells obey the Posix rule that when braces are
+omitted, multiple digits beyond a @samp{$} imply the single-digit
+positional parameter expansion concatenated with the remaining literal
+digits. To work around the issue, you must use braces.
+
+ at example
+$ @kbd{bash -c 'set a b c d e f g h i j; echo $10 $@{1@}0'}
+a0 a0
+$ @kbd{dash -c 'set a b c d e f g h i j; echo $10 $@{1@}0'}
+j a0
+ at end example
+
+ at item $@{@var{var}:- at var{value}@}
+ at c Info cannot handle `:' in index entries.
+ at ifnotinfo
+ at cindex @code{$@{@var{var}:- at var{value}@}}
+ at end ifnotinfo
+ at cindex @code{$@{@var{var}- at var{value}@}}
+Old BSD shells, including the Ultrix @code{sh}, don't accept the
+colon for any shell substitution, and complain and die.
+Similarly for $@{@var{var}:=@var{value}@}, $@{@var{var}:?@var{value}@}, etc.
+However, all shells that support functions allow the use of colon in
+shell substitution, and since m4sh requires functions, you can portably
+use null variable substitution patterns in configure scripts.
+
+ at item $@{@var{var}+ at var{value}@}
+ at cindex @code{$@{@var{var}+ at var{value}@}}
+When using @samp{$@{@var{var}- at var{value}@}} or
+ at samp{$@{@var{var}- at var{value}@}} for providing alternate substitutions,
+ at var{value} must either be a single shell word, quoted, or in the
+context of an unquoted here-document. Solaris
+ at command{/bin/sh} complains otherwise.
+
+ at example
+$ @kbd{/bin/sh -c 'echo $@{a-b c@}'}
+/bin/sh: bad substitution
+$ @kbd{/bin/sh -c 'echo $@{a-'\''b c'\''@}'}
+b c
+$ @kbd{/bin/sh -c 'echo "$@{a-b c@}"'}
+b c
+$ @kbd{/bin/sh -c 'cat <<EOF
+$@{a-b c@}
+EOF}
+b c
+ at end example
+
+According to Posix, if an expansion occurs inside double quotes, then
+the use of unquoted double quotes within @var{value} is unspecified, and
+any single quotes become literal characters; in that case, escaping must
+be done with backslash. Likewise, the use of unquoted here-documents is
+a case where double quotes have unspecified results:
+
+ at example
+$ @kbd{/bin/sh -c 'echo "$@{a-"b c"@}"'}
+/bin/sh: bad substitution
+$ @kbd{ksh -c 'echo "$@{a-"b c"@}"'}
+b c
+$ @kbd{bash -c 'echo "$@{a-"b c"@}"'}
+b c
+$ @kbd{/bin/sh -c 'a=; echo $@{a+'\''b c'\''@}'}
+b c
+$ @kbd{/bin/sh -c 'a=; echo "$@{a+'\''b c'\''@}"'}
+'b c'
+$ @kbd{/bin/sh -c 'a=; echo "$@{a+\"b c\"@}"'}
+"b c"
+$ @kbd{/bin/sh -c 'a=; echo "$@{a+b c@}"'}
+b c
+$ @kbd{/bin/sh -c 'cat <<EOF
+$@{a-"b c"@}
+EOF'}
+"b c"
+$ @kbd{/bin/sh -c 'cat <<EOF
+$@{a-'b c'@}
+EOF'}
+'b c'
+$ @kbd{bash -c 'cat <<EOF
+$@{a-"b c"@}
+EOF'}
+b c
+$ @kbd{bash -c 'cat <<EOF
+$@{a-'b c'@}
+EOF'}
+'b c'
+ at end example
+
+Perhaps the easiest way to work around quoting issues in a manner
+portable to all shells is to place the results in a temporary variable,
+then use @samp{$t} as the @var{value}, rather than trying to inline
+the expression needing quoting.
+
+ at example
+$ @kbd{/bin/sh -c 't="b c\"'\''@}\\"; echo "$@{a-$t@}"'}
+b c"'@}\
+$ @kbd{ksh -c 't="b c\"'\''@}\\"; echo "$@{a-$t@}"'}
+b c"'@}\
+$ @kbd{bash -c 't="b c\"'\''@}\\"; echo "$@{a-$t@}"'}
+b c"'@}\
+ at end example
+
+ at item $@{@var{var}=@var{value}@}
+ at cindex @code{$@{@var{var}=@var{value}@}}
+When using @samp{$@{@var{var}=@var{value}@}} to assign a default value
+to @var{var}, remember that even though the assignment to @var{var} does
+not undergo file name expansion, the result of the variable expansion
+does unless the expansion occurred within double quotes. In particular,
+when using @command{:} followed by unquoted variable expansion for the
+side effect of setting a default value, if the final value of
+ at samp{$var} contains any globbing characters (either from @var{value} or
+from prior contents), the shell has to spend time performing file name
+expansion and field splitting even though those results will not be
+used. Therefore, it is a good idea to consider double quotes when performing
+default initialization; while remembering how this impacts any quoting
+characters appearing in @var{value}.
+
+ at example
+$ @kbd{time bash -c ': "$@{a=/usr/bin/*@}"; echo "$a"'}
+/usr/bin/*
+
+real 0m0.005s
+user 0m0.002s
+sys 0m0.003s
+$ @kbd{time bash -c ': $@{a=/usr/bin/*@}; echo "$a"'}
+/usr/bin/*
+
+real 0m0.039s
+user 0m0.026s
+sys 0m0.009s
+$ @kbd{time bash -c 'a=/usr/bin/*; : $@{a=noglob@}; echo "$a"'}
+/usr/bin/*
+
+real 0m0.031s
+user 0m0.020s
+sys 0m0.010s
+
+$ @kbd{time bash -c 'a=/usr/bin/*; : "$@{a=noglob@}"; echo "$a"'}
+/usr/bin/*
+
+real 0m0.006s
+user 0m0.002s
+sys 0m0.003s
+ at end example
+
+As with @samp{+} and @samp{-}, you must use quotes when using @samp{=}
+if the @var{value} contains more than one shell word; either single
+quotes for just the @var{value}, or double quotes around the entire
+expansion:
+
+ at example
+$ @kbd{: $@{var1='Some words'@}}
+$ @kbd{: "$@{var2=like this@}"}
+$ @kbd{echo $var1 $var2}
+Some words like this
+ at end example
+
+ at noindent
+otherwise some shells, such as Solaris @command{/bin/sh} or on Digital
+Unix V 5.0, die because of a ``bad substitution''. Meanwhile, Posix
+requires that with @samp{=}, quote removal happens prior to the
+assignment, and the expansion be the final contents of @var{var} without
+quoting (and thus subject to field splitting), in contrast to the
+behavior with @samp{-} passing the quoting through to the final
+expansion. However, @command{bash} 4.1 does not obey this rule.
+
+ at example
+$ @kbd{ksh -c 'echo $@{var-a\ \ b@}'}
+a b
+$ @kbd{ksh -c 'echo $@{var=a\ \ b@}'}
+a b
+$ @kbd{bash -c 'echo $@{var=a\ \ b@}'}
+a b
+ at end example
+
+Finally, Posix states that when mixing @samp{$@{a=b@}} with regular
+commands, it is unspecified whether the assignments affect the parent
+shell environment. It is best to perform assignments independently from
+commands, to avoid the problems demonstrated in this example:
+
+ at example
+$ @kbd{bash -c 'x= y=$@{x:=b@} sh -c "echo +\$x+\$y+";echo -$x-'}
++b+b+
+-b-
+$ @kbd{/bin/sh -c 'x= y=$@{x:=b@} sh -c "echo +\$x+\$y+";echo -$x-'}
+++b+
+--
+$ @kbd{ksh -c 'x= y=$@{x:=b@} sh -c "echo +\$x+\$y+";echo -$x-'}
++b+b+
+--
+ at end example
+
+ at item $@{@var{var}=@var{value}@}
+ at cindex @code{$@{@var{var}=@var{literal}@}}
+Solaris @command{/bin/sh} has a frightening bug in its handling of
+literal assignments. Imagine you need set a variable to a string containing
+ at samp{@}}. This @samp{@}} character confuses Solaris @command{/bin/sh}
+when the affected variable was already set. This bug can be exercised
+by running:
+
+ at example
+$ @kbd{unset foo}
+$ @kbd{foo=$@{foo='@}'@}}
+$ @kbd{echo $foo}
+@}
+$ @kbd{foo=$@{foo='@}' # no error; this hints to what the bug is}
+$ @kbd{echo $foo}
+@}
+$ @kbd{foo=$@{foo='@}'@}}
+$ @kbd{echo $foo}
+@}@}
+ ^ ugh!
+ at end example
+
+It seems that @samp{@}} is interpreted as matching @samp{$@{}, even
+though it is enclosed in single quotes. The problem doesn't happen
+using double quotes, or when using a temporary variable holding the
+problematic string.
+
+ at item $@{@var{var}=@var{expanded-value}@}
+ at cindex @code{$@{@var{var}=@var{expanded-value}@}}
+On Ultrix,
+running
+
+ at example
+default="yu,yaa"
+: $@{var="$default"@}
+ at end example
+
+ at noindent
+sets @var{var} to @samp{M-yM-uM-,M-yM-aM-a}, i.e., the 8th bit of
+each char is set. You don't observe the phenomenon using a simple
+ at samp{echo $var} since apparently the shell resets the 8th bit when it
+expands $var. Here are two means to make this shell confess its sins:
+
+ at example
+$ @kbd{cat -v <<EOF
+$var
+EOF}
+ at end example
+
+ at noindent
+and
+
+ at example
+$ @kbd{set | grep '^var=' | cat -v}
+ at end example
+
+One classic incarnation of this bug is:
+
+ at example
+default="a b c"
+: $@{list="$default"@}
+for c in $list; do
+ echo $c
+done
+ at end example
+
+ at noindent
+You'll get @samp{a b c} on a single line. Why? Because there are no
+spaces in @samp{$list}: there are @samp{M- }, i.e., spaces with the 8th
+bit set, hence no IFS splitting is performed!!!
+
+One piece of good news is that Ultrix works fine with @samp{:
+$@{list=$default@}}; i.e., if you @emph{don't} quote. The bad news is
+then that QNX 4.25 then sets @var{list} to the @emph{last} item of
+ at var{default}!
+
+The portable way out consists in using a double assignment, to switch
+the 8th bit twice on Ultrix:
+
+ at example
+list=$@{list="$default"@}
+ at end example
+
+ at noindent
+ at dots{}but beware of the @samp{@}} bug from Solaris (see above). For safety,
+use:
+
+ at example
+test "$@{var+set@}" = set || var=@var{@{value@}}
+ at end example
+
+ at item $@{#@var{var}@}
+ at itemx $@{@var{var}%@var{word}@}
+ at itemx $@{@var{var}%%@var{word}@}
+ at itemx $@{@var{var}#@var{word}@}
+ at itemx $@{@var{var}##@var{word}@}
+ at cindex @code{$@{#@var{var}@}}
+ at cindex @code{$@{@var{var}%@var{word}@}}
+ at cindex @code{$@{@var{var}%%@var{word}@}}
+ at cindex @code{$@{@var{var}#@var{word}@}}
+ at cindex @code{$@{@var{var}##@var{word}@}}
+Posix requires support for these usages, but they do not work with many
+traditional shells, e.g., Solaris 10 @command{/bin/sh}.
+
+Also, @command{pdksh} 5.2.14 mishandles some @var{word} forms. For
+example if @samp{$1} is @samp{a/b} and @samp{$2} is @samp{a}, then
+ at samp{$@{1#$2@}} should yield @samp{/b}, but with @command{pdksh} it
+yields the empty string.
+
+
+ at item `@var{commands}`
+ at cindex @code{`@var{commands}`}
+ at cindex Command Substitution
+Posix requires shells to trim all trailing newlines from command
+output before substituting it, so assignments like
+ at samp{dir=`echo "$file" | tr a A`} do not work as expected if
+ at samp{$file} ends in a newline.
+
+While in general it makes no sense, do not substitute a single builtin
+with side effects, because Ash 0.2, trying to optimize, does not fork a
+subshell to perform the command.
+
+For instance, if you wanted to check that @command{cd} is silent, do not
+use @samp{test -z "`cd /`"} because the following can happen:
+
+ at example
+$ @kbd{pwd}
+/tmp
+$ @kbd{test -z "`cd /`" && pwd}
+/
+ at end example
+
+ at noindent
+The result of @samp{foo=`exit 1`} is left as an exercise to the reader.
+
+The MSYS shell leaves a stray byte in the expansion of a double-quoted
+command substitution of a native program, if the end of the substitution
+is not aligned with the end of the double quote. This may be worked
+around by inserting another pair of quotes:
+
+ at example
+$ @kbd{echo "`printf 'foo\r\n'` bar" > broken}
+$ @kbd{echo "`printf 'foo\r\n'`"" bar" | cmp - broken}
+- broken differ: char 4, line 1
+ at end example
+
+Upon interrupt or SIGTERM, some shells may abort a command substitution,
+replace it with a null string, and wrongly evaluate the enclosing
+command before entering the trap or ending the script. This can lead to
+spurious errors:
+
+ at example
+$ @kbd{sh -c 'if test `sleep 5; echo hi` = hi; then echo yes; fi'}
+$ @kbd{^C}
+sh: test: hi: unexpected operator/operand
+ at end example
+
+ at noindent
+You can avoid this by assigning the command substitution to a temporary
+variable:
+
+ at example
+$ @kbd{sh -c 'res=`sleep 5; echo hi`
+ if test "x$res" = xhi; then echo yes; fi'}
+$ @kbd{^C}
+ at end example
+
+ at item $(@var{commands})
+ at cindex @code{$(@var{commands})}
+This construct is meant to replace @samp{`@var{commands}`},
+and it has most of the problems listed under @code{`@var{commands}`}.
+
+This construct can be
+nested while this is impossible to do portably with back quotes.
+Unfortunately it is not yet universally supported. Most notably, even recent
+releases of Solaris don't support it:
+
+ at example
+$ @kbd{showrev -c /bin/sh | grep version}
+Command version: SunOS 5.10 Generic 121005-03 Oct 2006
+$ @kbd{echo $(echo blah)}
+syntax error: `(' unexpected
+ at end example
+
+ at noindent
+nor does IRIX 6.5's Bourne shell:
+ at example
+$ @kbd{uname -a}
+IRIX firebird-image 6.5 07151432 IP22
+$ @kbd{echo $(echo blah)}
+$(echo blah)
+ at end example
+
+If you do use @samp{$(@var{commands})}, make sure that the commands
+do not start with a parenthesis, as that would cause confusion with
+a different notation @samp{$((@var{expression}))} that in modern
+shells is an arithmetic expression not a command. To avoid the
+confusion, insert a space between the two opening parentheses.
+
+Avoid @var{commands} that contain unbalanced parentheses in
+here-documents, comments, or case statement patterns, as many shells
+mishandle them. For example, Bash 3.1, @samp{ksh88}, @command{pdksh}
+5.2.14, and Zsh 4.2.6 all mishandle the following valid command:
+
+ at example
+echo $(case x in x) echo hello;; esac)
+ at end example
+
+
+ at item $((@var{expression}))
+ at cindex @code{$((@var{expression}))}
+Arithmetic expansion is not portable as some shells (most
+notably Solaris 10 @command{/bin/sh}) don't support it.
+
+Among shells that do support @samp{$(( ))}, not all of them obey the
+Posix rule that octal and hexadecimal constants must be recognized:
+
+ at example
+$ @kbd{bash -c 'echo $(( 010 + 0x10 ))'}
+24
+$ @kbd{zsh -c 'echo $(( 010 + 0x10 ))'}
+26
+$ @kbd{zsh -c 'emulate sh; echo $(( 010 + 0x10 ))'}
+24
+$ @kbd{pdksh -c 'echo $(( 010 + 0x10 ))'}
+pdksh: 010 + 0x10 : bad number `0x10'
+$ @kbd{pdksh -c 'echo $(( 010 ))'}
+10
+ at end example
+
+When it is available, using arithmetic expansion provides a noticeable
+speedup in script execution; but testing for support requires
+ at command{eval} to avoid syntax errors. The following construct is used
+by @code{AS_VAR_ARITH} to provide arithmetic computation when all
+arguments are provided in decimal and without a leading zero, and all
+operators are properly quoted and appear as distinct arguments:
+
+ at example
+if ( eval 'test $(( 1 + 1 )) = 2' ) 2>/dev/null; then
+ eval 'func_arith ()
+ @{
+ func_arith_result=$(( $* ))
+ @}'
+else
+ func_arith ()
+ @{
+ func_arith_result=`expr "$@@"`
+ @}
+fi
+func_arith 1 + 1
+foo=$func_arith_result
+ at end example
+
+
+ at item ^
+ at cindex @code{^} quoting
+Always quote @samp{^}, otherwise traditional shells such as
+ at command{/bin/sh} on Solaris 10 treat this like @samp{|}.
+
+ at end table
+
+
+ at node Assignments
+ at section Assignments
+ at cindex Shell assignments
+
+When setting several variables in a row, be aware that the order of the
+evaluation is undefined. For instance @samp{foo=1 foo=2; echo $foo}
+gives @samp{1} with Solaris @command{/bin/sh}, but @samp{2} with Bash.
+You must use
+ at samp{;} to enforce the order: @samp{foo=1; foo=2; echo $foo}.
+
+Don't rely on the following to find @file{subdir/program}:
+
+ at example
+PATH=subdir$PATH_SEPARATOR$PATH program
+ at end example
+
+ at noindent
+as this does not work with Zsh 3.0.6. Use something like this
+instead:
+
+ at example
+(PATH=subdir$PATH_SEPARATOR$PATH; export PATH; exec program)
+ at end example
+
+Don't rely on the exit status of an assignment: Ash 0.2 does not change
+the status and propagates that of the last statement:
+
+ at example
+$ @kbd{false || foo=bar; echo $?}
+1
+$ @kbd{false || foo=`:`; echo $?}
+0
+ at end example
+
+ at noindent
+and to make things even worse, QNX 4.25 just sets the exit status
+to 0 in any case:
+
+ at example
+$ @kbd{foo=`exit 1`; echo $?}
+0
+ at end example
+
+To assign default values, follow this algorithm:
+
+ at enumerate
+ at item
+If the default value is a literal and does not contain any closing
+brace, use:
+
+ at example
+: "$@{var='my literal'@}"
+ at end example
+
+ at item
+If the default value contains no closing brace, has to be expanded, and
+the variable being initialized is not intended to be IFS-split
+(i.e., it's not a list), then use:
+
+ at example
+: $@{var="$default"@}
+ at end example
+
+ at item
+If the default value contains no closing brace, has to be expanded, and
+the variable being initialized is intended to be IFS-split (i.e., it's a list),
+then use:
+
+ at example
+var=$@{var="$default"@}
+ at end example
+
+ at item
+If the default value contains a closing brace, then use:
+
+ at example
+test "$@{var+set@}" = set || var="has a '@}'"
+ at end example
+ at end enumerate
+
+In most cases @samp{var=$@{var="$default"@}} is fine, but in case of
+doubt, just use the last form. @xref{Shell Substitutions}, items
+ at samp{$@{@var{var}:- at var{value}@}} and @samp{$@{@var{var}=@var{value}@}}
+for the rationale.
+
+ at node Parentheses
+ at section Parentheses in Shell Scripts
+ at cindex Shell parentheses
+
+Beware of two opening parentheses in a row, as many shell
+implementations treat them specially, and Posix says that a portable
+script cannot use @samp{((} outside the @samp{$((} form used for shell
+arithmetic. In traditional shells, @samp{((cat))} behaves like
+ at samp{(cat)}; but many shells, including
+Bash and the Korn shell, treat @samp{((cat))} as an arithmetic
+expression equivalent to @samp{let "cat"}, and may or may not report an
+error when they detect that @samp{cat} is not a number. As another
+example, @samp{pdksh} 5.2.14 does not treat the following code
+as a traditional shell would:
+
+ at example
+if ((true) || false); then
+ echo ok
+fi
+ at end example
+
+ at noindent
+To work around this problem, insert a space between the two opening
+parentheses. There is a similar problem and workaround with
+ at samp{$((}; see @ref{Shell Substitutions}.
+
+ at node Slashes
+ at section Slashes in Shell Scripts
+ at cindex Shell slashes
+
+Unpatched Tru64 5.1 @command{sh} omits the last slash of command-line
+arguments that contain two trailing slashes:
+
+ at example
+$ @kbd{echo / // /// //// .// //.}
+/ / // /// ./ //.
+$ @kbd{x=//}
+$ @kbd{eval "echo \$x"}
+/
+$ @kbd{set -x}
+$ @kbd{echo abc | tr -t ab //}
++ echo abc
++ tr -t ab /
+/bc
+ at end example
+
+Unpatched Tru64 4.0 @command{sh} adds a slash after @samp{"$var"} if the
+variable is empty and the second double-quote is followed by a word that
+begins and ends with slash:
+
+ at example
+$ @kbd{sh -xc 'p=; echo "$p"/ouch/'}
+p=
++ echo //ouch/
+//ouch/
+ at end example
+
+However, our understanding is that patches are available, so perhaps
+it's not worth worrying about working around these horrendous bugs.
+
+ at node Special Shell Variables
+ at section Special Shell Variables
+ at cindex Shell variables
+ at cindex Special shell variables
+
+Some shell variables should not be used, since they can have a deep
+influence on the behavior of the shell. In order to recover a sane
+behavior from the shell, some variables should be unset; M4sh takes
+care of this and provides fallback values, whenever needed, to cater
+for a very old @file{/bin/sh} that does not support @command{unset}.
+(@pxref{Portable Shell, , Portable Shell Programming}).
+
+As a general rule, shell variable names containing a lower-case letter
+are safe; you can define and use these variables without worrying about
+their effect on the underlying system, and without worrying about
+whether the shell changes them unexpectedly. (The exception is the
+shell variable @code{status}, as described below.)
+
+Here is a list of names that are known to cause trouble. This list is
+not exhaustive, but you should be safe if you avoid the name
+ at code{status} and names containing only upper-case letters and
+underscores.
+
+ at c Alphabetical order, case insensitive, `A' before `a'.
+ at table @code
+ at item ?
+Not all shells correctly reset @samp{$?} after conditionals (@pxref{if,
+, Limitations of Shell Builtins}). Not all shells manage @samp{$?}
+correctly in shell functions (@pxref{Shell Functions}) or in traps
+(@pxref{trap, , Limitations of Shell Builtins}). Not all shells reset
+ at samp{$?} to zero after an empty command.
+
+ at example
+$ @kbd{bash -c 'false; $empty; echo $?'}
+0
+$ @kbd{zsh -c 'false; $empty; echo $?'}
+1
+ at end example
+
+ at item _
+ at evindex _
+Many shells reserve @samp{$_} for various purposes, e.g., the name of
+the last command executed.
+
+ at item BIN_SH
+ at evindex BIN_SH
+In Tru64, if @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of
+the standard shell conform to Posix.
+
+ at item CDPATH
+ at evindex CDPATH
+When this variable is set it specifies a list of directories to search
+when invoking @code{cd} with a relative file name that did not start
+with @samp{./} or @samp{../}. Posix
+1003.1-2001 says that if a nonempty directory name from @env{CDPATH}
+is used successfully, @code{cd} prints the resulting absolute
+file name. Unfortunately this output can break idioms like
+ at samp{abs=`cd src && pwd`} because @code{abs} receives the name twice.
+Also, many shells do not conform to this part of Posix; for
+example, @command{zsh} prints the result only if a directory name
+other than @file{.} was chosen from @env{CDPATH}.
+
+In practice the shells that have this problem also support
+ at command{unset}, so you can work around the problem as follows:
+
+ at example
+(unset CDPATH) >/dev/null 2>&1 && unset CDPATH
+ at end example
+
+You can also avoid output by ensuring that your directory name is
+absolute or anchored at @samp{./}, as in @samp{abs=`cd ./src && pwd`}.
+
+Configure scripts use M4sh, which automatically unsets @env{CDPATH} if
+possible, so you need not worry about this problem in those scripts.
+
+ at item CLICOLOR_FORCE
+ at evindex CLICOLOR_FORCE
+When this variable is set, some implementations of tools like
+ at command{ls} attempt to add color to their output via terminal escape
+sequences, even when the output is not directed to a terminal, and can
+thus cause spurious failures in scripts. Configure scripts use M4sh,
+which automatically unsets this variable.
+
+ at item DUALCASE
+ at evindex DUALCASE
+In the MKS shell, case statements and file name generation are
+case-insensitive unless @env{DUALCASE} is nonzero.
+Autoconf-generated scripts export this variable when they start up.
+
+ at item ENV
+ at itemx MAIL
+ at itemx MAILPATH
+ at itemx PS1
+ at itemx PS2
+ at itemx PS4
+ at evindex ENV
+ at evindex MAIL
+ at evindex MAILPATH
+ at evindex PS1
+ at evindex PS2
+ at evindex PS4
+These variables should not matter for shell scripts, since they are
+supposed to affect only interactive shells. However, at least one
+shell (the pre-3.0 UWIN Korn shell) gets confused about
+whether it is interactive, which means that (for example) a @env{PS1}
+with a side effect can unexpectedly modify @samp{$?}. To work around
+this bug, M4sh scripts (including @file{configure} scripts) do something
+like this:
+
+ at example
+(unset ENV) >/dev/null 2>&1 && unset ENV MAIL MAILPATH
+PS1='$ '
+PS2='> '
+PS4='+ '
+ at end example
+
+ at noindent
+(actually, there is some complication due to bugs in @command{unset};
+ at pxref{unset, , Limitations of Shell Builtins}).
+
+ at item FPATH
+ at evindex FPATH
+The Korn shell uses @env{FPATH} to find shell functions, so avoid
+ at env{FPATH} in portable scripts. @env{FPATH} is consulted after
+ at env{PATH}, but you still need to be wary of tests that use @env{PATH}
+to find whether a command exists, since they might report the wrong
+result if @env{FPATH} is also set.
+
+ at item GREP_OPTIONS
+ at evindex GREP_OPTIONS
+When this variable is set, some implementations of @command{grep} honor
+these options, even if the options include direction to enable colored
+output via terminal escape sequences, and the result can cause spurious
+failures when the output is not directed to a terminal. Configure
+scripts use M4sh, which automatically unsets this variable.
+
+ at item IFS
+ at evindex IFS
+Long ago, shell scripts inherited @env{IFS} from the environment,
+but this caused many problems so modern shells ignore any environment
+settings for @env{IFS}.
+
+Don't set the first character of @env{IFS} to backslash. Indeed,
+Bourne shells use the first character (backslash) when joining the
+components in @samp{"$@@"} and some shells then reinterpret (!)@: the
+backslash escapes, so you can end up with backspace and other strange
+characters.
+
+The proper value for @env{IFS} (in regular code, not when performing
+splits) is @samp{@key{SPC}@key{TAB}@key{RET}}. The first character is
+especially important, as it is used to join the arguments in @samp{$*};
+however, note that traditional shells, but also bash-2.04, fail to adhere
+to this and join with a space anyway.
+
+M4sh guarantees that @env{IFS} will have the default value at the
+beginning of a script, and many macros within autoconf rely on this
+setting. It is okay to use blocks of shell code that temporarily change
+the value of @env{IFS} in order to split on another character, but
+remember to restore it before expanding further macros.
+
+Unsetting @code{IFS} instead of resetting it to the default sequence
+is not suggested, since code that tries to save and restore the
+variable's value will incorrectly reset it to an empty value, thus
+disabling field splitting:
+
+ at example
+unset IFS
+# default separators used for field splitting
+
+save_IFS=$IFS
+IFS=:
+# ...
+IFS=$save_IFS
+# no field splitting performed
+ at end example
+
+ at item LANG
+ at itemx LC_ALL
+ at itemx LC_COLLATE
+ at itemx LC_CTYPE
+ at itemx LC_MESSAGES
+ at itemx LC_MONETARY
+ at itemx LC_NUMERIC
+ at itemx LC_TIME
+ at evindex LANG
+ at evindex LC_ALL
+ at evindex LC_COLLATE
+ at evindex LC_CTYPE
+ at evindex LC_MESSAGES
+ at evindex LC_MONETARY
+ at evindex LC_NUMERIC
+ at evindex LC_TIME
+
+You should set all these variables to @samp{C} because so much
+configuration code assumes the C locale and Posix requires that locale
+environment variables be set to @samp{C} if the C locale is desired;
+ at file{configure} scripts and M4sh do that for you.
+Export these variables after setting them.
+
+ at c However, some older, nonstandard
+ at c systems (notably SCO) break if locale environment variables
+ at c are set to @samp{C}, so when running on these systems
+ at c Autoconf-generated scripts unset the variables instead.
+
+ at item LANGUAGE
+ at evindex LANGUAGE
+
+ at env{LANGUAGE} is not specified by Posix, but it is a GNU
+extension that overrides @env{LC_ALL} in some cases, so you (or M4sh)
+should set it too.
+
+ at item LC_ADDRESS
+ at itemx LC_IDENTIFICATION
+ at itemx LC_MEASUREMENT
+ at itemx LC_NAME
+ at itemx LC_PAPER
+ at itemx LC_TELEPHONE
+ at evindex LC_ADDRESS
+ at evindex LC_IDENTIFICATION
+ at evindex LC_MEASUREMENT
+ at evindex LC_NAME
+ at evindex LC_PAPER
+ at evindex LC_TELEPHONE
+
+These locale environment variables are GNU extensions. They
+are treated like their Posix brethren (@env{LC_COLLATE},
+etc.)@: as described above.
+
+ at item LINENO
+ at evindex LINENO
+Most modern shells provide the current line number in @code{LINENO}.
+Its value is the line number of the beginning of the current command.
+M4sh, and hence Autoconf, attempts to execute @command{configure} with
+a shell that supports @code{LINENO}. If no such shell is available, it
+attempts to implement @code{LINENO} with a Sed prepass that replaces each
+instance of the string @code{$LINENO} (not followed by an alphanumeric
+character) with the line's number. In M4sh scripts you should execute
+ at code{AS_LINENO_PREPARE} so that these workarounds are included in
+your script; configure scripts do this automatically in @code{AC_INIT}.
+
+You should not rely on @code{LINENO} within @command{eval} or shell
+functions, as the behavior differs in practice. The presence of a
+quoted newline within simple commands can alter which line number is
+used as the starting point for @code{$LINENO} substitutions within that
+command. Also, the possibility of the Sed prepass means that you should
+not rely on @code{$LINENO} when quoted, when in here-documents, or when
+line continuations are used. Subshells should be OK, though. In the
+following example, lines 1, 9, and 14 are portable, but the other
+instances of @code{$LINENO} do not have deterministic values:
+
+ at example
+ at group
+$ @kbd{cat lineno}
+echo 1. $LINENO
+echo "2. $LINENO
+3. $LINENO"
+cat <<EOF
+5. $LINENO
+6. $LINENO
+7. \$LINENO
+EOF
+( echo 9. $LINENO )
+eval 'echo 10. $LINENO'
+eval 'echo 11. $LINENO
+echo 12. $LINENO'
+echo 13. '$LINENO'
+echo 14. $LINENO '
+15.' $LINENO
+f () @{ echo $1 $LINENO;
+echo $1 $LINENO @}
+f 18.
+echo 19. \
+$LINENO
+ at end group
+ at group
+$ @kbd{bash-3.2 ./lineno}
+1. 1
+2. 3
+3. 3
+5. 4
+6. 4
+7. $LINENO
+9. 9
+10. 10
+11. 12
+12. 13
+13. $LINENO
+14. 14
+15. 14
+18. 16
+18. 17
+19. 19
+ at end group
+ at group
+$ @kbd{zsh-4.3.4 ./lineno}
+1. 1
+2. 2
+3. 2
+5. 4
+6. 4
+7. $LINENO
+9. 9
+10. 1
+11. 1
+12. 2
+13. $LINENO
+14. 14
+15. 14
+18. 0
+18. 1
+19. 19
+ at end group
+ at group
+$ @kbd{pdksh-5.2.14 ./lineno}
+1. 1
+2. 2
+3. 2
+5. 4
+6. 4
+7. $LINENO
+9. 9
+10. 0
+11. 0
+12. 0
+13. $LINENO
+14. 14
+15. 14
+18. 16
+18. 17
+19. 19
+ at end group
+ at group
+$ @kbd{sed '=' <lineno |}
+> @kbd{ sed '}
+> @kbd{ N}
+> @kbd{ s,$,-,}
+> @kbd{ t loop}
+> @kbd{ :loop}
+> @kbd{ s,^\([0-9]*\)\(.*\)[$]LINENO\([^a-zA-Z0-9_]\),\1\2\1\3,}
+> @kbd{ t loop}
+> @kbd{ s,-$,,}
+> @kbd{ s,^[0-9]*\n,,}
+> @kbd{ ' |}
+> @kbd{ sh}
+1. 1
+2. 2
+3. 3
+5. 5
+6. 6
+7. \7
+9. 9
+10. 10
+11. 11
+12. 12
+13. 13
+14. 14
+15. 15
+18. 16
+18. 17
+19. 20
+ at end group
+ at end example
+
+In particular, note that @file{config.status} (and any other subsidiary
+script created by @code{AS_INIT_GENERATED}) might report line numbers
+relative to the parent script as a result of the potential Sed pass.
+
+ at item NULLCMD
+ at evindex NULLCMD
+When executing the command @samp{>foo}, @command{zsh} executes
+ at samp{$NULLCMD >foo} unless it is operating in Bourne shell
+compatibility mode and the @command{zsh} version is newer
+than 3.1.6-dev-18. If you are using an older @command{zsh}
+and forget to set @env{NULLCMD},
+your script might be suspended waiting for data on its standard input.
+
+ at item options
+ at evindex options
+For @command{zsh} 4.3.10, @env{options} is treated as an associative
+array even after @code{emulate sh}, so it should not be used.
+
+ at item PATH_SEPARATOR
+ at evindex PATH_SEPARATOR
+On DJGPP systems, the @env{PATH_SEPARATOR} environment
+variable can be set to either @samp{:} or @samp{;} to control the path
+separator Bash uses to set up certain environment variables (such as
+ at env{PATH}). You can set this variable to @samp{;} if you want
+ at command{configure} to use @samp{;} as a separator; this might be useful
+if you plan to use non-Posix shells to execute files. @xref{File System
+Conventions}, for more information about @code{PATH_SEPARATOR}.
+
+ at item POSIXLY_CORRECT
+ at evindex POSIXLY_CORRECT
+In the GNU environment, exporting @env{POSIXLY_CORRECT} with any value
+(even empty) causes programs to try harder to conform to Posix.
+Autoconf does not directly manipulate this variable, but @command{bash}
+ties the shell variable @env{POSIXLY_CORRECT} to whether the script is
+running in Posix mode. Therefore, take care when exporting or unsetting
+this variable, so as not to change whether @command{bash} is in Posix
+mode.
+
+ at example
+$ @kbd{bash --posix -c 'set -o | grep posix}
+> @kbd{unset POSIXLY_CORRECT}
+> @kbd{set -o | grep posix'}
+posix on
+posix off
+ at end example
+
+ at item PWD
+ at evindex PWD
+Posix 1003.1-2001 requires that @command{cd} and
+ at command{pwd} must update the @env{PWD} environment variable to point
+to the logical name of the current directory, but traditional shells
+do not support this. This can cause confusion if one shell instance
+maintains @env{PWD} but a subsidiary and different shell does not know
+about @env{PWD} and executes @command{cd}; in this case @env{PWD}
+points to the wrong directory. Use @samp{`pwd`} rather than
+ at samp{$PWD}.
+
+ at item RANDOM
+ at evindex RANDOM
+Many shells provide @code{RANDOM}, a variable that returns a different
+integer each time it is used. Most of the time, its value does not
+change when it is not used, but on IRIX 6.5 the value changes all
+the time. This can be observed by using @command{set}. It is common
+practice to use @code{$RANDOM} as part of a file name, but code
+shouldn't rely on @code{$RANDOM} expanding to a nonempty string.
+
+ at item status
+ at evindex status
+This variable is an alias to @samp{$?} for @code{zsh} (at least 3.1.6),
+hence read-only. Do not use it.
+ at end table
+
+ at node Shell Functions
+ at section Shell Functions
+ at cindex Shell Functions
+
+Nowadays, it is difficult to find a shell that does not support
+shell functions at all. However, some differences should be expected.
+
+When declaring a shell function, you must include whitespace between the
+ at samp{)} after the function name and the start of the compound
+expression, to avoid upsetting @command{ksh}. While it is possible to
+use any compound command, most scripts use @samp{@{@dots{}@}}.
+
+ at example
+$ @kbd{/bin/sh -c 'a()@{ echo hi;@}; a'}
+hi
+$ @kbd{ksh -c 'a()@{ echo hi;@}; a'}
+ksh: syntax error at line 1: `@}' unexpected
+$ @kbd{ksh -c 'a() @{ echo hi;@}; a'}
+hi
+ at end example
+
+Inside a shell function, you should not rely on the error status of a
+subshell if the last command of that subshell was @code{exit} or
+ at code{trap}, as this triggers bugs in zsh 4.x; while Autoconf tries to
+find a shell that does not exhibit the bug, zsh might be the only shell
+present on the user's machine.
+
+Likewise, the state of @samp{$?} is not reliable when entering a shell
+function. This has the effect that using a function as the first
+command in a @command{trap} handler can cause problems.
+
+ at example
+$ @kbd{bash -c 'foo() @{ echo $?; @}; trap foo 0; (exit 2); exit 2'; echo $?}
+2
+2
+$ @kbd{ash -c 'foo() @{ echo $?; @}; trap foo 0; (exit 2); exit 2'; echo $?}
+0
+2
+ at end example
+
+DJGPP bash 2.04 has a bug in that @command{return} from a
+shell function which also used a command substitution causes a
+segmentation fault. To work around the issue, you can use
+ at command{return} from a subshell, or @samp{AS_SET_STATUS} as last command
+in the execution flow of the function (@pxref{Common Shell Constructs}).
+
+Not all shells treat shell functions as simple commands impacted by
+ at samp{set -e}, for example with Solaris 10 @command{/bin/sh}:
+
+ at example
+$ @kbd{bash -c 'f() @{ return 1; @}; set -e; f; echo oops'}
+$ @kbd{/bin/sh -c 'f() @{ return 1; @}; set -e; f; echo oops'}
+oops
+ at end example
+
+Shell variables and functions may share the same namespace, for example
+with Solaris 10 @command{/bin/sh}:
+
+ at example
+$ @kbd{f () @{ :; @}; f=; f}
+f: not found
+ at end example
+
+ at noindent
+For this reason, Autoconf (actually M4sh, @pxref{Programming in M4sh})
+uses the prefix @samp{as_fn_} for its functions.
+
+Handling of positional parameters and shell options varies among shells.
+For example, Korn shells reset and restore trace output (@samp{set -x})
+and other options upon function entry and exit. Inside a function,
+IRIX sh sets @samp{$0} to the function name.
+
+It is not portable to pass temporary environment variables to shell
+functions. Solaris @command{/bin/sh} does not see the variable.
+Meanwhile, not all shells follow the Posix rule that the assignment must
+affect the current environment in the same manner as special built-ins.
+
+ at example
+$ @kbd{/bin/sh -c 'func() @{ echo $a;@}; a=1 func; echo $a'}
+ at result{}
+ at result{}
+$ @kbd{ash -c 'func() @{ echo $a;@}; a=1 func; echo $a'}
+ at result{}1
+ at result{}
+$ @kbd{bash -c 'set -o posix; func() @{ echo $a;@}; a=1 func; echo $a'}
+ at result{}1
+ at result{}1
+ at end example
+
+Some ancient Bourne shell variants with function support did not reset
+ at samp{$@var{i}, @var{i} >= 0}, upon function exit, so effectively the
+arguments of the script were lost after the first function invocation.
+It is probably not worth worrying about these shells any more.
+
+With AIX sh, a @command{trap} on 0 installed in a shell function
+triggers at function exit rather than at script exit. @xref{trap, ,
+Limitations of Shell Builtins}.
+
+ at node Limitations of Builtins
+ at section Limitations of Shell Builtins
+ at cindex Shell builtins
+ at cindex Limitations of shell builtins
+
+No, no, we are serious: some shells do have limitations! :)
+
+You should always keep in mind that any builtin or command may support
+options, and therefore differ in behavior with arguments
+starting with a dash. For instance, even the innocent @samp{echo "$word"}
+can give unexpected results when @code{word} starts with a dash. It is
+often possible to avoid this problem using @samp{echo "x$word"}, taking
+the @samp{x} into account later in the pipe. Many of these limitations
+can be worked around using M4sh (@pxref{Programming in M4sh}).
+
+ at c This table includes things like `@command{test} (files)', so we can't
+ at c use @table @command.
+ at table @asis
+ at item @command{.}
+ at c --------------
+ at prindex @command{.}
+Use @command{.} only with regular files (use @samp{test -f}). Bash
+2.03, for instance, chokes on @samp{. /dev/null}. Remember that
+ at command{.} uses @env{PATH} if its argument contains no slashes. Also,
+some shells, including bash 3.2, implicitly append the current directory
+to this @env{PATH} search, even though Posix forbids it. So if you want
+to use @command{.} on a file @file{foo} in the current directory, you
+must use @samp{. ./foo}.
+
+Not all shells gracefully handle syntax errors within a sourced file.
+On one extreme, some non-interactive shells abort the entire script. On
+the other, @command{zsh} 4.3.10 has a bug where it fails to react to the
+syntax error.
+
+ at example
+$ @kbd{echo 'fi' > syntax}
+$ @kbd{bash -c '. ./syntax; echo $?'}
+./syntax: line 1: syntax error near unexpected token `fi'
+./syntax: line 1: `fi'
+1
+$ @kbd{ash -c '. ./syntax; echo $?'}
+./syntax: 1: Syntax error: "fi" unexpected
+$ @kbd{zsh -c '. ./syntax; echo $?'}
+./syntax:1: parse error near `fi'
+0
+ at end example
+
+ at item @command{!}
+ at c --------------
+ at prindex @command{!}
+The Unix version 7 shell did not support
+negating the exit status of commands with @command{!}, and this feature
+is still absent from some shells (e.g., Solaris @command{/bin/sh}).
+Other shells, such as FreeBSD @command{/bin/sh} or @command{ash}, have
+bugs when using @command{!}:
+
+ at example
+$ @kbd{sh -c '! : | :'; echo $?}
+1
+$ @kbd{ash -c '! : | :'; echo $?}
+0
+$ @kbd{sh -c '! @{ :; @}'; echo $?}
+1
+$ @kbd{ash -c '! @{ :; @}'; echo $?}
+@{: not found
+Syntax error: "@}" unexpected
+2
+ at end example
+
+Shell code like this:
+
+ at example
+if ! cmp file1 file2 >/dev/null 2>&1; then
+ echo files differ or trouble
+fi
+ at end example
+
+is therefore not portable in practice. Typically it is easy to rewrite
+such code, e.g.:
+
+ at example
+cmp file1 file2 >/dev/null 2>&1 ||
+ echo files differ or trouble
+ at end example
+
+More generally, one can always rewrite @samp{! @var{command}} as:
+
+ at example
+if @var{command}; then (exit 1); else :; fi
+ at end example
+
+
+ at item @command{@{...@}}
+ at c --------------------
+ at prindex @command{@{...@}}
+Bash 3.2 (and earlier versions) sometimes does not properly set
+ at samp{$?} when failing to write redirected output of a compound command.
+This problem is most commonly observed with @samp{@{@dots{}@}}; it does
+not occur with @samp{(@dots{})}. For example:
+
+ at example
+$ @kbd{bash -c '@{ echo foo; @} >/bad; echo $?'}
+bash: line 1: /bad: Permission denied
+0
+$ @kbd{bash -c 'while :; do echo; done >/bad; echo $?'}
+bash: line 1: /bad: Permission denied
+0
+ at end example
+
+To work around the bug, prepend @samp{:;}:
+
+ at example
+$ @kbd{bash -c ':;@{ echo foo; @} >/bad; echo $?'}
+bash: line 1: /bad: Permission denied
+1
+ at end example
+
+Posix requires a syntax error if a brace list has no contents. However,
+not all shells obey this rule; and on shells where empty lists are
+permitted, the effect on @samp{$?} is inconsistent. To avoid problems,
+ensure that a brace list is never empty.
+
+ at example
+$ @kbd{bash -c 'false; @{ @}; echo $?' || echo $?}
+bash: line 1: syntax error near unexpected token `@}'
+bash: line 1: `false; @{ @}; echo $?'
+2
+$ @kbd{zsh -c 'false; @{ @}; echo $?' || echo $?}
+1
+$ @kbd{pdksh -c 'false; @{ @}; echo $?' || echo $?}
+0
+ at end example
+
+
+ at item @command{break}
+ at c ------------------
+ at prindex @command{break}
+The use of @samp{break 2} etc.@: is safe.
+
+
+ at anchor{case}
+ at item @command{case}
+ at c -----------------
+ at prindex @command{case}
+You don't need to quote the argument; no splitting is performed.
+
+You don't need the final @samp{;;}, but you should use it.
+
+Posix requires support for @code{case} patterns with opening
+parentheses like this:
+
+ at example
+case $file_name in
+ (*.c) echo "C source code";;
+esac
+ at end example
+
+ at noindent
+but the @code{(} in this example is not portable to many Bourne
+shell implementations, which is a pity for those of us using tools that
+rely on balanced parentheses. For instance, with Solaris
+ at command{/bin/sh}:
+
+ at example
+$ @kbd{case foo in (foo) echo foo;; esac}
+ at error{}syntax error: `(' unexpected
+ at end example
+
+ at noindent
+The leading @samp{(} can be omitted safely. Unfortunately, there are
+contexts where unbalanced parentheses cause other problems, such as when
+using a syntax-highlighting editor that searches for the balancing
+counterpart, or more importantly, when using a case statement as an
+underquoted argument to an Autoconf macro. @xref{Balancing
+Parentheses}, for tradeoffs involved in various styles of dealing with
+unbalanced @samp{)}.
+
+Zsh handles pattern fragments derived from parameter expansions or
+command substitutions as though quoted:
+
+ at example
+$ pat=\?; case aa in ?$pat) echo match;; esac
+$ pat=\?; case a? in ?$pat) echo match;; esac
+match
+ at end example
+
+ at noindent
+Because of a bug in its @code{fnmatch}, Bash fails to properly
+handle backslashes in character classes:
+
+ at example
+bash-2.02$ @kbd{case /tmp in [/\\]*) echo OK;; esac}
+bash-2.02$
+ at end example
+
+ at noindent
+This is extremely unfortunate, since you are likely to use this code to
+handle Posix or MS-DOS absolute file names. To work around this
+bug, always put the backslash first:
+
+ at example
+bash-2.02$ @kbd{case '\TMP' in [\\/]*) echo OK;; esac}
+OK
+bash-2.02$ @kbd{case /tmp in [\\/]*) echo OK;; esac}
+OK
+ at end example
+
+Many Bourne shells cannot handle closing brackets in character classes
+correctly.
+
+Some shells also have problems with backslash escaping in case you do not want
+to match the backslash: both a backslash and the escaped character match this
+pattern. To work around this, specify the character class in a variable, so
+that quote removal does not apply afterwards, and the special characters don't
+have to be backslash-escaped:
+
+ at example
+$ @kbd{case '\' in [\<]) echo OK;; esac}
+OK
+$ @kbd{scanset='[<]'; case '\' in $scanset) echo OK;; esac}
+$
+ at end example
+
+Even with this, Solaris @command{ksh} matches a backslash if the set
+contains any
+of the characters @samp{|}, @samp{&}, @samp{(}, or @samp{)}.
+
+Conversely, Tru64 @command{ksh} (circa 2003) erroneously always matches
+a closing parenthesis if not specified in a character class:
+
+ at example
+$ @kbd{case foo in *\)*) echo fail ;; esac}
+fail
+$ @kbd{case foo in *')'*) echo fail ;; esac}
+fail
+ at end example
+
+Some shells, such as Ash 0.3.8, are confused by an empty
+ at code{case}/@code{esac}:
+
+ at example
+ash-0.3.8 $ @kbd{case foo in esac;}
+ at error{}Syntax error: ";" unexpected (expecting ")")
+ at end example
+
+Posix requires @command{case} to give an exit status of 0 if no cases
+match. However, @command{/bin/sh} in Solaris 10 does not obey this
+rule. Meanwhile, it is unclear whether a case that matches, but
+contains no statements, must also change the exit status to 0. The M4sh
+macro @code{AS_CASE} works around these inconsistencies.
+
+ at example
+$ @kbd{bash -c 'case `false` in ?) ;; esac; echo $?'}
+0
+$ @kbd{/bin/sh -c 'case `false` in ?) ;; esac; echo $?'}
+255
+ at end example
+
+
+ at item @command{cd}
+ at c ---------------
+ at prindex @command{cd}
+Posix 1003.1-2001 requires that @command{cd} must support
+the @option{-L} (``logical'') and @option{-P} (``physical'') options,
+with @option{-L} being the default. However, traditional shells do
+not support these options, and their @command{cd} command has the
+ at option{-P} behavior.
+
+Portable scripts should assume neither option is supported, and should
+assume neither behavior is the default. This can be a bit tricky,
+since the Posix default behavior means that, for example,
+ at samp{ls ..} and @samp{cd ..} may refer to different directories if
+the current logical directory is a symbolic link. It is safe to use
+ at code{cd @var{dir}} if @var{dir} contains no @file{..} components.
+Also, Autoconf-generated scripts check for this problem when computing
+variables like @code{ac_top_srcdir} (@pxref{Configuration Actions}),
+so it is safe to @command{cd} to these variables.
+
+Posix states that behavior is undefined if @command{cd} is given an
+explicit empty argument. Some shells do nothing, some change to the
+first entry in @env{CDPATH}, some change to @env{HOME}, and some exit
+the shell rather than returning an error. Unfortunately, this means
+that if @samp{$var} is empty, then @samp{cd "$var"} is less predictable
+than @samp{cd $var} (at least the latter is well-behaved in all shells
+at changing to @env{HOME}, although this is probably not what you wanted
+in a script). You should check that a directory name was supplied
+before trying to change locations.
+
+ at xref{Special Shell Variables}, for portability problems involving
+ at command{cd} and the @env{CDPATH} environment variable.
+Also please see the discussion of the @command{pwd} command.
+
+
+ at anchor{echo}
+ at item @command{echo}
+ at c -----------------
+ at prindex @command{echo}
+The simple @command{echo} is probably the most surprising source of
+portability troubles. It is not possible to use @samp{echo} portably
+unless both options and escape sequences are omitted. Don't expect any
+option.
+
+Do not use backslashes in the arguments, as there is no consensus on
+their handling. For @samp{echo '\n' | wc -l}, the @command{sh} of
+Solaris outputs 2, but Bash and Zsh (in @command{sh} emulation mode) output 1.
+The problem is truly @command{echo}: all the shells
+understand @samp{'\n'} as the string composed of a backslash and an
+ at samp{n}. Within a command substitution, @samp{echo 'string\c'} will
+mess up the internal state of ksh88 on AIX 6.1 so that it will print
+the first character @samp{s} only, followed by a newline, and then
+entirely drop the output of the next echo in a command substitution.
+
+Because of these problems, do not pass a string containing arbitrary
+characters to @command{echo}. For example, @samp{echo "$foo"} is safe
+only if you know that @var{foo}'s value cannot contain backslashes and
+cannot start with @samp{-}.
+
+If this may not be true, @command{printf} is in general safer and
+easier to use than @command{echo} and @command{echo -n}. Thus, scripts
+where portability is not a major concern should use @command{printf
+'%s\n'} whenever @command{echo} could fail, and similarly use
+ at command{printf %s} instead of @command{echo -n}. For portable shell
+scripts, instead, it is suggested to use a here-document like this:
+
+ at example
+cat <<EOF
+$foo
+EOF
+ at end example
+
+Alternatively, M4sh provides @code{AS_ECHO} and @code{AS_ECHO_N} macros
+which choose between various portable implementations: @samp{echo}
+or @samp{print} where they work, @command{printf} if it is available,
+or else other creative tricks in order to work around the above problems.
+
+
+ at item @command{eval}
+ at c -----------------
+ at prindex @command{eval}
+The @command{eval} command is useful in limited circumstances, e.g.,
+using commands like @samp{eval table_$key=\$value} and @samp{eval
+value=table_$key} to simulate a hash table when the key is known to be
+alphanumeric.
+
+You should also be wary of common bugs in @command{eval} implementations.
+In some shell implementations (e.g., older @command{ash}, OpenBSD 3.8
+ at command{sh}, @command{pdksh} v5.2.14 99/07/13.2, and @command{zsh}
+4.2.5), the arguments of @samp{eval} are evaluated in a context where
+ at samp{$?} is 0, so they exhibit behavior like this:
+
+ at example
+$ @kbd{false; eval 'echo $?'}
+0
+ at end example
+
+The correct behavior here is to output a nonzero value,
+but portable scripts should not rely on this.
+
+You should not rely on @code{LINENO} within @command{eval}.
+ at xref{Special Shell Variables}.
+
+Note that, even though these bugs are easily avoided,
+ at command{eval} is tricky to use on arbitrary arguments.
+It is obviously unwise to use @samp{eval $cmd} if the string value of
+ at samp{cmd} was derived from an untrustworthy source. But even if the
+string value is valid, @samp{eval $cmd} might not work as intended,
+since it causes field splitting and file name expansion to occur twice,
+once for the @command{eval} and once for the command itself. It is
+therefore safer to use @samp{eval "$cmd"}. For example, if @var{cmd}
+has the value @samp{cat test?.c}, @samp{eval $cmd} might expand to the
+equivalent of @samp{cat test;.c} if there happens to be a file named
+ at file{test;.c} in the current directory; and this in turn
+mistakenly attempts to invoke @command{cat} on the file @file{test} and
+then execute the command @command{.c}. To avoid this problem, use
+ at samp{eval "$cmd"} rather than @samp{eval $cmd}.
+
+However, suppose that you want to output the text of the evaluated
+command just before executing it. Assuming the previous example,
+ at samp{echo "Executing: $cmd"} outputs @samp{Executing: cat test?.c}, but
+this output doesn't show the user that @samp{test;.c} is the actual name
+of the copied file. Conversely, @samp{eval "echo Executing: $cmd"}
+works on this example, but it fails with @samp{cmd='cat foo >bar'},
+since it mistakenly replaces the contents of @file{bar} by the
+string @samp{cat foo}. No simple, general, and portable solution to
+this problem is known.
+
+ at item @command{exec}
+ at c -----------------
+ at prindex @command{exec}
+Posix describes several categories of shell built-ins. Special
+built-ins (such as @command{exit}) must impact the environment of the
+current shell, and need not be available through @command{exec}. All
+other built-ins are regular, and must not propagate variable assignments
+to the environment of the current shell. However, the group of regular
+built-ins is further distinguished by commands that do not require a
+ at env{PATH} search (such as @command{cd}), in contrast to built-ins that
+are offered as a more efficient version of something that must still be
+found in a @env{PATH} search (such as @command{echo}). Posix is not
+clear on whether @command{exec} must work with the list of 17 utilities
+that are invoked without a @env{PATH} search, and many platforms lack an
+executable for some of those built-ins:
+
+ at example
+$ @kbd{sh -c 'exec cd /tmp'}
+sh: line 0: exec: cd: not found
+ at end example
+
+All other built-ins that provide utilities specified by Posix must have
+a counterpart executable that exists on @env{PATH}, although Posix
+allows @command{exec} to use the built-in instead of the executable.
+For example, contrast @command{bash} 3.2 and @command{pdksh} 5.2.14:
+
+ at example
+$ @kbd{bash -c 'pwd --version' | head -n1}
+bash: line 0: pwd: --: invalid option
+pwd: usage: pwd [-LP]
+$ @kbd{bash -c 'exec pwd --version' | head -n1}
+pwd (GNU coreutils) 6.10
+$ @kbd{pdksh -c 'exec pwd --version' | head -n1}
+pdksh: pwd: --: unknown option
+ at end example
+
+When it is desired to avoid a regular shell built-in, the workaround is
+to use some other forwarding command, such as @command{env} or
+ at command{nice}, that will ensure a path search:
+
+ at example
+$ @kbd{pdksh -c 'exec true --version' | head -n1}
+$ @kbd{pdksh -c 'nice true --version' | head -n1}
+true (GNU coreutils) 6.10
+$ @kbd{pdksh -c 'env true --version' | head -n1}
+true (GNU coreutils) 6.10
+ at end example
+
+ at item @command{exit}
+ at c -----------------
+ at prindex @command{exit}
+The default value of @command{exit} is supposed to be @code{$?};
+unfortunately, some shells, such as the DJGPP port of Bash 2.04, just
+perform @samp{exit 0}.
+
+ at example
+bash-2.04$ @kbd{foo=`exit 1` || echo fail}
+fail
+bash-2.04$ @kbd{foo=`(exit 1)` || echo fail}
+fail
+bash-2.04$ @kbd{foo=`(exit 1); exit` || echo fail}
+bash-2.04$
+ at end example
+
+Using @samp{exit $?} restores the expected behavior.
+
+Some shell scripts, such as those generated by @command{autoconf}, use a
+trap to clean up before exiting. If the last shell command exited with
+nonzero status, the trap also exits with nonzero status so that the
+invoker can tell that an error occurred.
+
+Unfortunately, in some shells, such as Solaris @command{/bin/sh}, an exit
+trap ignores the @code{exit} command's argument. In these shells, a trap
+cannot determine whether it was invoked by plain @code{exit} or by
+ at code{exit 1}. Instead of calling @code{exit} directly, use the
+ at code{AC_MSG_ERROR} macro that has a workaround for this problem.
+
+
+ at anchor{export}
+ at item @command{export}
+ at c -------------------
+ at prindex @command{export}
+The builtin @command{export} dubs a shell variable @dfn{environment
+variable}. Each update of exported variables corresponds to an update
+of the environment variables. Conversely, each environment variable
+received by the shell when it is launched should be imported as a shell
+variable marked as exported.
+
+Alas, many shells, such as Solaris @command{/bin/sh},
+IRIX 6.3, IRIX 5.2,
+AIX 4.1.5, and Digital Unix 4.0, forget to
+ at command{export} the environment variables they receive. As a result,
+two variables coexist: the environment variable and the shell
+variable. The following code demonstrates this failure:
+
+ at example
+#!/bin/sh
+echo $FOO
+FOO=bar
+echo $FOO
+exec /bin/sh $0
+ at end example
+
+ at noindent
+when run with @samp{FOO=foo} in the environment, these shells print
+alternately @samp{foo} and @samp{bar}, although they should print only
+ at samp{foo} and then a sequence of @samp{bar}s.
+
+Therefore you should @command{export} again each environment variable
+that you update; the export can occur before or after the assignment.
+
+Posix is not clear on whether the @command{export} of an undefined
+variable causes the variable to be defined with the value of an empty
+string, or merely marks any future definition of a variable by that name
+for export. Various shells behave differently in this regard:
+
+ at example
+$ @kbd{sh -c 'export foo; env | grep foo'}
+$ @kbd{ash -c 'export foo; env | grep foo'}
+foo=
+ at end example
+
+Posix requires @command{export} to honor assignments made as arguments,
+but older shells do not support this, including @command{/bin/sh} in
+Solaris 10. Portable scripts should separate assignments and exports
+into different statements.
+
+ at example
+$ @kbd{bash -c 'export foo=bar; echo $foo'}
+bar
+$ @kbd{/bin/sh -c 'export foo=bar; echo $foo'}
+/bin/sh: foo=bar: is not an identifier
+$ @kbd{/bin/sh -c 'export foo; foo=bar; echo $foo'}
+bar
+ at end example
+
+ at item @command{false}
+ at c ------------------
+ at prindex @command{false}
+Don't expect @command{false} to exit with status 1: in native
+Solaris @file{/bin/false} exits with status 255.
+
+
+ at item @command{for}
+ at c ----------------
+ at prindex @command{for}
+To loop over positional arguments, use:
+
+ at example
+for arg
+do
+ echo "$arg"
+done
+ at end example
+
+ at noindent
+You may @emph{not} leave the @code{do} on the same line as @code{for},
+since some shells improperly grok:
+
+ at example
+for arg; do
+ echo "$arg"
+done
+ at end example
+
+If you want to explicitly refer to the positional arguments, given the
+ at samp{$@@} bug (@pxref{Shell Substitutions}), use:
+
+ at example
+for arg in $@{1+"$@@"@}; do
+ echo "$arg"
+done
+ at end example
+
+ at noindent
+But keep in mind that Zsh, even in Bourne shell emulation mode, performs
+word splitting on @samp{$@{1+"$@@"@}}; see @ref{Shell Substitutions},
+item @samp{$@@}, for more.
+
+In Solaris @command{/bin/sh}, when the list of arguments of a
+ at command{for} loop starts with @emph{unquoted} tokens looking like
+variable assignments, the loop is not executed on those tokens:
+
+ at example
+$ @kbd{/bin/sh -c 'for v in a=b c=d x e=f; do echo $v; done'}
+x
+e=f
+ at end example
+
+ at noindent
+Thankfully, quoting the assignment-like tokens, or starting the list
+with other tokens (including unquoted variable expansion that results in
+an assignment-like result), avoids the problem, so it is easy to work
+around:
+
+ at example
+$ @kbd{/bin/sh -c 'for v in "a=b"; do echo $v; done'}
+a=b
+$ @kbd{/bin/sh -c 'x=a=b; for v in $x c=d; do echo $v; done'}
+a=b
+c=d
+ at end example
+
+ at anchor{if}
+ at item @command{if}
+ at c ---------------
+ at prindex @command{if}
+Using @samp{!} is not portable. Instead of:
+
+ at example
+if ! cmp -s file file.new; then
+ mv file.new file
+fi
+ at end example
+
+ at noindent
+use:
+
+ at example
+if cmp -s file file.new; then :; else
+ mv file.new file
+fi
+ at end example
+
+ at noindent
+Or, especially if the @dfn{else} branch is short, you can use @code{||}.
+In M4sh, the @code{AS_IF} macro provides an easy way to write these kinds
+of conditionals:
+
+ at example
+AS_IF([cmp -s file file.new], [], [mv file.new file])
+ at end example
+
+This is especially useful in other M4 macros, where the @dfn{then} and
+ at dfn{else} branches might be macro arguments.
+
+Some very old shells did not reset the exit status from an @command{if}
+with no @command{else}:
+
+ at example
+$ @kbd{if (exit 42); then true; fi; echo $?}
+42
+ at end example
+
+ at noindent
+whereas a proper shell should have printed @samp{0}. But this is no
+longer a portability problem; any shell that supports functions gets it
+correct. However, it explains why some makefiles have lengthy
+constructs:
+
+ at example
+if test -f "$file"; then
+ install "$file" "$dest"
+else
+ :
+fi
+ at end example
+
+
+ at item @command{printf}
+ at c ------------------
+ at prindex @command{printf}
+A format string starting with a @samp{-} can cause problems.
+Bash interprets it as an option and
+gives an error. And @samp{--} to mark the end of options is not good
+in the NetBSD Almquist shell (e.g., 0.4.6) which takes that
+literally as the format string. Putting the @samp{-} in a @samp{%c}
+or @samp{%s} is probably easiest:
+
+ at example
+printf %s -foo
+ at end example
+
+Bash 2.03 mishandles an escape sequence that happens to evaluate to @samp{%}:
+
+ at example
+$ @kbd{printf '\045'}
+bash: printf: `%': missing format character
+ at end example
+
+Large outputs may cause trouble. On Solaris 2.5.1 through 10, for
+example, @file{/usr/bin/printf} is buggy, so when using
+ at command{/bin/sh} the command @samp{printf %010000x 123} normally dumps
+core.
+
+Since @command{printf} is not always a shell builtin, there is a
+potential speed penalty for using @code{printf '%s\n'} as a replacement
+for an @command{echo} that does not interpret @samp{\} or leading
+ at samp{-}. With Solaris @command{ksh}, it is possible to use @code{print
+-r --} for this role instead.
+
+ at xref{echo, , Limitations of Shell Builtins} for a discussion of
+portable alternatives to both @command{printf} and @command{echo}.
+
+
+ at item @command{pwd}
+ at c ----------------
+ at prindex @command{pwd}
+With modern shells, plain @command{pwd} outputs a ``logical''
+directory name, some of whose components may be symbolic links. These
+directory names are in contrast to ``physical'' directory names, whose
+components are all directories.
+
+Posix 1003.1-2001 requires that @command{pwd} must support
+the @option{-L} (``logical'') and @option{-P} (``physical'') options,
+with @option{-L} being the default. However, traditional shells do
+not support these options, and their @command{pwd} command has the
+ at option{-P} behavior.
+
+Portable scripts should assume neither option is supported, and should
+assume neither behavior is the default. Also, on many hosts
+ at samp{/bin/pwd} is equivalent to @samp{pwd -P}, but Posix
+does not require this behavior and portable scripts should not rely on
+it.
+
+Typically it's best to use plain @command{pwd}. On modern hosts this
+outputs logical directory names, which have the following advantages:
+
+ at itemize @bullet
+ at item
+Logical names are what the user specified.
+ at item
+Physical names may not be portable from one installation
+host to another due to network file system gymnastics.
+ at item
+On modern hosts @samp{pwd -P} may fail due to lack of permissions to
+some parent directory, but plain @command{pwd} cannot fail for this
+reason.
+ at end itemize
+
+Also please see the discussion of the @command{cd} command.
+
+
+ at item @command{read}
+ at c -----------------
+ at prindex @command{read}
+No options are portable, not even support @option{-r} (Solaris
+ at command{/bin/sh} for example). Tru64/OSF 5.1 @command{sh} treats
+ at command{read} as a special built-in, so it may exit if input is
+redirected from a non-existent or unreadable file.
+
+
+ at anchor{set}
+ at item @command{set}
+ at c ----------------
+ at prindex @command{set}
+With the FreeBSD 6.0 shell, the @command{set} command (without
+any options) does not sort its output.
+
+The @command{set} builtin faces the usual problem with arguments
+starting with a
+dash. Modern shells such as Bash or Zsh understand @option{--} to specify
+the end of the options (any argument after @option{--} is a parameter,
+even @samp{-x} for instance), but many traditional shells (e.g., Solaris
+10 @command{/bin/sh}) simply stop option
+processing as soon as a non-option argument is found. Therefore, use
+ at samp{dummy} or simply @samp{x} to end the option processing, and use
+ at command{shift} to pop it out:
+
+ at example
+set x $my_list; shift
+ at end example
+
+Avoid @samp{set -}, e.g., @samp{set - $my_list}. Posix no
+longer requires support for this command, and in traditional shells
+ at samp{set - $my_list} resets the @option{-v} and @option{-x} options, which
+makes scripts harder to debug.
+
+Some nonstandard shells do not recognize more than one option
+(e.g., @samp{set -e -x} assigns @samp{-x} to the command line). It is
+better to combine them:
+
+ at example
+set -ex
+ at end example
+
+ at cindex @command{set -e}
+The option @option{-e} has historically been underspecified, with enough
+ambiguities to cause numerous differences across various shell
+implementations; see for example
+ at uref{http://www.in-ulm.de/@/~mascheck/@/various/@/set-e/, this overview},
+or @uref{http://www.austingroupbugs.net/@/view.php?id=52, this link},
+documenting a change to Posix 2008 to match @command{ksh88} behavior.
+Note that mixing @code{set -e} and shell functions is asking for surprises:
+
+ at example
+set -e
+doit()
+@{
+ rm file
+ echo one
+@}
+doit || echo two
+ at end example
+
+ at noindent
+According to the recommendation, @samp{one} should always be output
+regardless of whether the @command{rm} failed, because it occurs within
+the body of the shell function @samp{doit} invoked on the left side of
+ at samp{||}, where the effects of @samp{set -e} are not enforced.
+Likewise, @samp{two} should never be printed, since the failure of
+ at command{rm} does not abort the function, such that the status of
+ at samp{doit} is 0.
+
+The BSD shell has had several problems with the @option{-e}
+option. Older versions of the BSD
+shell (circa 1990) mishandled @samp{&&}, @samp{||}, @samp{if}, and
+ at samp{case} when @option{-e} was in effect, causing the shell to exit
+unexpectedly in some cases. This was particularly a problem with
+makefiles, and led to circumlocutions like @samp{sh -c 'test -f file ||
+touch file'}, where the seemingly-unnecessary @samp{sh -c '@dots{}'}
+wrapper works around the bug (@pxref{Failure in Make Rules}).
+
+Even relatively-recent versions of the BSD shell (e.g., OpenBSD 3.4)
+wrongly exit with @option{-e} if the last command within a compound
+statement fails and is guarded by an @samp{&&} only. For example:
+
+ at example
+#! /bin/sh
+set -e
+foo=''
+test -n "$foo" && exit 1
+echo one
+if :; then
+ test -n "$foo" && exit 1
+ echo two
+ test -n "$foo" && exit 1
+fi
+echo three
+ at end example
+
+ at noindent
+does not print @samp{three}. One workaround is to change the last
+instance of @samp{test -n "$foo" && exit 1} to be @samp{if test -n
+"$foo"; then exit 1; fi} instead. Another possibility is to warn BSD
+users not to use @samp{sh -e}.
+
+When @samp{set -e} is in effect, a failed command substitution in
+Solaris @command{/bin/sh} cannot be ignored, even with @samp{||}.
+
+ at example
+$ @kbd{/bin/sh -c 'set -e; foo=`false` || echo foo; echo bar'}
+$ @kbd{bash -c 'set -e; foo=`false` || echo foo; echo bar'}
+foo
+bar
+ at end example
+
+ at noindent
+Moreover, a command substitution, successful or not, causes this shell to
+exit from a failing outer command even in presence of an @samp{&&} list:
+
+ at example
+$ @kbd{bash -c 'set -e; false `true` && echo notreached; echo ok'}
+ok
+$ @kbd{sh -c 'set -e; false `true` && echo notreached; echo ok'}
+$
+ at end example
+
+Portable scripts should not use @samp{set -e} if @command{trap} is used
+to install an exit handler. This is because Tru64/OSF 5.1 @command{sh}
+sometimes enters the trap handler with the exit status of the command
+prior to the one that triggered the errexit handler:
+
+ at example
+$ @kbd{sh -ec 'trap '\''echo $?'\'' 0; false'}
+0
+$ @kbd{sh -c 'set -e; trap '\''echo $?'\'' 0; false'}
+1
+ at end example
+
+ at noindent
+Thus, when writing a script in M4sh, rather than trying to rely on
+ at samp{set -e}, it is better to append @samp{|| AS_EXIT} to any
+statement where it is desirable to abort on failure.
+
+ at cindex @command{set -b}
+ at cindex @command{set -m}
+Job control is not provided by all shells, so the use of @samp{set -m}
+or @samp{set -b} must be done with care. When using @command{zsh} in
+native mode, asynchronous notification (@samp{set -b}) is enabled by
+default, and using @samp{emulate sh} to switch to Posix mode does not
+clear this setting (although asynchronous notification has no impact
+unless job monitoring is also enabled). Also, @command{zsh} 4.3.10 and
+earlier have a bug where job control can be manipulated in interactive
+shells, but not in subshells or scripts. Furthermore, some shells, like
+ at command{pdksh}, fail to treat subshells as interactive, even though the
+parent shell was.
+
+ at example
+$ @kbd{echo $ZSH_VERSION}
+4.3.10
+$ @kbd{set -m; echo $?}
+0
+$ @kbd{zsh -c 'set -m; echo $?'}
+set: can't change option: -m
+$ @kbd{(set -m); echo $?}
+set: can't change option: -m
+1
+$ @kbd{pdksh -ci 'echo $-; (echo $-)'}
+cim
+c
+ at end example
+
+ at cindex @command{set -n}
+Use of @command{set -n} (typically via @command{sh -n script}) to
+validate a script is not foolproof. Modern @command{ksh93} tries to be
+helpful by informing you about better syntax, but switching the script
+to use the suggested syntax in order to silence the warnings would
+render the script no longer portable to older shells:
+
+ at example
+$ @kbd{ksh -nc '``'}
+ksh: warning: line 1: `...` obsolete, use $(...)
+0
+ at end example
+
+Furthermore, on ancient hosts, such as SunOS 4, @command{sh -n} could go
+into an infinite loop; even with that bug fixed, Solaris 8
+ at command{/bin/sh} takes extremely long to parse large scripts. Autoconf
+itself uses @command{sh -n} within its testsuite to check that correct
+scripts were generated, but only after first probing for other shell
+features (such as @code{test -n "$@{BASH_VERSION+set@}"}) that indicate
+a reasonably fast and working implementation.
+
+ at item @command{shift}
+ at c ------------------
+ at prindex @command{shift}
+Not only is @command{shift}ing a bad idea when there is nothing left to
+shift, but in addition it is not portable: the shell of MIPS
+RISC/OS 4.52 refuses to do it.
+
+Don't use @samp{shift 2} etc.; while it in the SVR1 shell (1983),
+it is also absent in many pre-Posix shells.
+
+
+ at item @command{source}
+ at c -------------------
+ at prindex @command{source}
+This command is not portable, as Posix does not require it; use
+ at command{.} instead.
+
+
+ at item @command{test}
+ at c -----------------
+ at prindex @command{test}
+The @code{test} program is the way to perform many file and string
+tests. It is often invoked by the alternate name @samp{[}, but using
+that name in Autoconf code is asking for trouble since it is an M4 quote
+character.
+
+The @option{-a}, @option{-o}, @samp{(}, and @samp{)} operands are not
+present in all implementations, and have been marked obsolete by Posix
+2008. This is because there are inherent ambiguities in using them.
+For example, @samp{test "$1" -a "$2"} looks like a binary operator to
+check whether two strings are both non-empty, but if @samp{$1} is the
+literal @samp{!}, then some implementations of @command{test} treat it
+as a negation of the unary operator @option{-a}.
+
+Thus, portable uses of @command{test} should never have more than four
+arguments, and scripts should use shell constructs like @samp{&&} and
+ at samp{||} instead. If you combine @samp{&&} and @samp{||} in the same
+statement, keep in mind that they have equal precedence, so it is often
+better to parenthesize even when this is redundant. For example:
+
+ at smallexample
+# Not portable:
+test "X$a" = "X$b" -a \
+ '(' "X$c" != "X$d" -o "X$e" = "X$f" ')'
+
+# Portable:
+test "X$a" = "X$b" &&
+ @{ test "X$c" != "X$d" || test "X$e" = "X$f"; @}
+ at end smallexample
+
+ at command{test} does not process options like most other commands do; for
+example, it does not recognize the @option{--} argument as marking the
+end of options.
+
+It is safe to use @samp{!} as a @command{test} operator. For example,
+ at samp{if test ! -d foo; @dots{}} is portable even though @samp{if ! test
+-d foo; @dots{}} is not.
+
+
+ at item @command{test} (files)
+ at c -------------------------
+To enable @command{configure} scripts to support cross-compilation, they
+shouldn't do anything that tests features of the build system instead of
+the host system. But occasionally you may find it necessary to check
+whether some arbitrary file exists. To do so, use @samp{test -f},
+ at samp{test -r}, or @samp{test -x}. Do not use @samp{test -e}, because
+Solaris 10 @command{/bin/sh}
+lacks it. To test for symbolic links on systems that have them, use
+ at samp{test -h} rather than @samp{test -L}; either form conforms to
+Posix 1003.1-2001, but older shells like Solaris 8
+ at code{/bin/sh} support only @option{-h}.
+
+For historical reasons, Posix reluctantly allows implementations of
+ at samp{test -x} that will succeed for the root user, even if no execute
+permissions are present. Furthermore, shells do not all agree on
+whether Access Control Lists should affect @samp{test -r}, @samp{test
+-w}, and @samp{test -x}; some shells base test results strictly on the
+current user id compared to file owner and mode, as if by
+ at code{stat(2)}; while other shells base test results on whether the
+current user has the given right, even if that right is only granted by
+an ACL, as if by @code{faccessat(2)}. Furthermore, there is a classic
+time of check to time of use race between any use of @command{test}
+followed by operating on the just-checked file. Therefore, it is a good
+idea to write scripts that actually attempt an operation, and are
+prepared for the resulting failure if permission is denied, rather than
+trying to avoid an operation based solely on whether @command{test}
+guessed that it might not be permitted.
+
+ at item @command{test} (strings)
+ at c ---------------------------
+Posix says that @samp{test "@var{string}"} succeeds if @var{string} is
+not null, but this usage is not portable to traditional platforms like
+Solaris 10 @command{/bin/sh}, which mishandle strings like @samp{!} and
+ at samp{-n}.
+
+Posix also says that @samp{test ! "@var{string}"},
+ at samp{test -n "@var{string}"} and
+ at samp{test -z "@var{string}"} work with any string, but many
+shells (such as Solaris, AIX 3.2, UNICOS 10.0.0.6,
+Digital Unix 4, etc.)@: get confused if
+ at var{string} looks like an operator:
+
+ at example
+$ @kbd{test -n =}
+test: argument expected
+$ @kbd{test ! -n}
+test: argument expected
+$ @kbd{test -z ")"; echo $?}
+0
+ at end example
+
+Similarly, Posix says that both @samp{test "@var{string1}" = "@var{string2"}}
+and @samp{test "@var{string1}" != "@var{string2"}} work for any pairs of
+strings, but in practice this is not true for troublesome strings that
+look like operators or parentheses, or that begin with @samp{-}.
+
+It is best to protect such strings with a leading @samp{X}, e.g.,
+ at samp{test "X at var{string}" != X} rather than @samp{test -n
+"@var{string}"} or @samp{test ! "@var{string}"}.
+
+It is common to find variations of the following idiom:
+
+ at example
+test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" &&
+ @var{action}
+ at end example
+
+ at noindent
+to take an action when a token matches a given pattern. Such constructs
+should be avoided by using:
+
+ at example
+case $ac_feature in
+ *[!-a-zA-Z0-9_]*) @var{action};;
+esac
+ at end example
+
+If the pattern is a complicated regular expression that cannot be
+expressed as a shell pattern, use something like this instead:
+
+ at example
+expr "X$ac_feature" : 'X.*[^-a-zA-Z0-9_]' >/dev/null &&
+ @var{action}
+ at end example
+
+ at samp{expr "X at var{foo}" : "X at var{bar}"} is more robust than @samp{echo
+"X at var{foo}" | grep "^X at var{bar}"}, because it avoids problems when
+ at samp{@var{foo}} contains backslashes.
+
+
+ at anchor{trap}
+ at item @command{trap}
+ at c -----------------
+ at prindex @command{trap}
+It is safe to trap at least the signals 1, 2, 13, and 15. You can also
+trap 0, i.e., have the @command{trap} run when the script ends (either via an
+explicit @command{exit}, or the end of the script). The trap for 0 should be
+installed outside of a shell function, or AIX 5.3 @command{/bin/sh}
+will invoke the trap at the end of this function.
+
+Posix says that @samp{trap - 1 2 13 15} resets the traps for the
+specified signals to their default values, but many common shells (e.g.,
+Solaris @command{/bin/sh}) misinterpret this and attempt to execute a
+``command'' named @command{-} when the specified conditions arise.
+Posix 2008 also added a requirement to support @samp{trap 1 2 13 15} to
+reset traps, as this is supported by a larger set of shells, but there
+are still shells like @command{dash} that mistakenly try to execute
+ at command{1} instead of resetting the traps. Therefore, there is no
+portable workaround, except for @samp{trap - 0}, for which
+ at samp{trap '' 0} is a portable substitute.
+
+Although Posix is not absolutely clear on this point, it is widely
+admitted that when entering the trap @samp{$?} should be set to the exit
+status of the last command run before the trap. The ambiguity can be
+summarized as: ``when the trap is launched by an @command{exit}, what is
+the @emph{last} command run: that before @command{exit}, or
+ at command{exit} itself?''
+
+Bash considers @command{exit} to be the last command, while Zsh and
+Solaris @command{/bin/sh} consider that when the trap is run it is
+ at emph{still} in the @command{exit}, hence it is the previous exit status
+that the trap receives:
+
+ at example
+$ @kbd{cat trap.sh}
+trap 'echo $?' 0
+(exit 42); exit 0
+$ @kbd{zsh trap.sh}
+42
+$ @kbd{bash trap.sh}
+0
+ at end example
+
+The portable solution is then simple: when you want to @samp{exit 42},
+run @samp{(exit 42); exit 42}, the first @command{exit} being used to
+set the exit status to 42 for Zsh, and the second to trigger the trap
+and pass 42 as exit status for Bash. In M4sh, this is covered by using
+ at code{AS_EXIT}.
+
+The shell in FreeBSD 4.0 has the following bug: @samp{$?} is
+reset to 0 by empty lines if the code is inside @command{trap}.
+
+ at example
+$ @kbd{trap 'false}
+
+echo $?' 0
+$ @kbd{exit}
+0
+ at end example
+
+ at noindent
+Fortunately, this bug only affects @command{trap}.
+
+Several shells fail to execute an exit trap that is defined inside a
+subshell, when the last command of that subshell is not a builtin. A
+workaround is to use @samp{exit $?} as the shell builtin.
+
+ at example
+$ @kbd{bash -c '(trap "echo hi" 0; /bin/true)'}
+hi
+$ @kbd{/bin/sh -c '(trap "echo hi" 0; /bin/true)'}
+$ @kbd{/bin/sh -c '(trap "echo hi" 0; /bin/true; exit $?)'}
+hi
+ at end example
+
+ at noindent
+Likewise, older implementations of @command{bash} failed to preserve
+ at samp{$?} across an exit trap consisting of a single cleanup command.
+
+ at example
+$ @kbd{bash -c 'trap "/bin/true" 0; exit 2'; echo $?}
+2
+$ @kbd{bash-2.05b -c 'trap "/bin/true" 0; exit 2'; echo $?}
+0
+$ @kbd{bash-2.05b -c 'trap ":; /bin/true" 0; exit 2'; echo $?}
+2
+ at end example
+
+ at item @command{true}
+ at c -----------------
+ at prindex @command{true}
+ at c Info cannot handle `:' in index entries.
+ at c @prindex @command{:}
+Don't worry: as far as we know @command{true} is portable.
+Nevertheless, it's not always a builtin (e.g., Bash 1.x), and the
+portable shell community tends to prefer using @command{:}. This has a
+funny side effect: when asked whether @command{false} is more portable
+than @command{true} Alexandre Oliva answered:
+
+ at quotation
+In a sense, yes, because if it doesn't exist, the shell will produce an
+exit status of failure, which is correct for @command{false}, but not
+for @command{true}.
+ at end quotation
+
+Remember that even though @samp{:} ignores its arguments, it still takes
+time to compute those arguments. It is a good idea to use double quotes
+around any arguments to @samp{:} to avoid time spent in field splitting
+and file name expansion.
+
+
+ at anchor{unset}
+ at item @command{unset}
+ at c ------------------
+ at prindex @command{unset}
+In some nonconforming shells (e.g., Solaris 10 @command{/bin/ksh} and
+ at command{/usr/xpg4/bin/sh}, NetBSD 5.99.43 sh, or Bash 2.05a),
+ at code{unset FOO} fails when @code{FOO} is not set. This can interfere
+with @code{set -e} operation. You can use
+
+ at smallexample
+FOO=; unset FOO
+ at end smallexample
+
+ at noindent
+if you are not sure that @code{FOO} is set.
+
+A few ancient shells lack @command{unset} entirely. For some variables
+such as @code{PS1}, you can use a neutralizing value instead:
+
+ at smallexample
+PS1='$ '
+ at end smallexample
+
+Usually, shells that do not support @command{unset} need less effort to
+make the environment sane, so for example is not a problem if you cannot
+unset @command{CDPATH} on those shells. However, Bash 2.01 mishandles
+ at code{unset MAIL} and @code{unset MAILPATH} in some cases and dumps core.
+So, you should do something like
+
+ at smallexample
+( (unset MAIL) || exit 1) >/dev/null 2>&1 && unset MAIL || :
+ at end smallexample
+
+ at noindent
+ at xref{Special Shell Variables}, for some neutralizing values. Also, see
+ at ref{export, , Limitations of Builtins}, for
+the case of environment variables.
+
+ at item @command{wait}
+ at c -----------------
+ at prindex @command{wait}
+The exit status of @command{wait} is not always reliable.
+ at end table
+
+ at node Limitations of Usual Tools
+ at section Limitations of Usual Tools
+ at cindex Limitations of usual tools
+
+The small set of tools you can expect to find on any machine can still
+include some limitations you should be aware of.
+
+ at comment Between this list and the list of builtins above, we should
+ at comment mention all the tools in GNU Coding Standards ``Utilities in
+ at comment Makefiles''.
+
+ at c This table includes things like `@command{expr} (|)', so we can't
+ at c use @table @command.
+ at table @asis
+ at anchor{awk}
+ at item @command{awk}
+ at c ----------------
+ at prindex @command{awk}
+Don't leave white space before the opening parenthesis in a user function call.
+Posix does not allow this and GNU Awk rejects it:
+
+ at example
+$ @kbd{gawk 'function die () @{ print "Aaaaarg!" @}
+ BEGIN @{ die () @}'}
+gawk: cmd. line:2: BEGIN @{ die () @}
+gawk: cmd. line:2: ^ parse error
+$ @kbd{gawk 'function die () @{ print "Aaaaarg!" @}
+ BEGIN @{ die() @}'}
+Aaaaarg!
+ at end example
+
+Posix says that if a program contains only @samp{BEGIN} actions, and
+contains no instances of @code{getline}, then the program merely
+executes the actions without reading input. However, traditional Awk
+implementations (such as Solaris 10 @command{awk}) read and discard
+input in this case. Portable scripts can redirect input from
+ at file{/dev/null} to work around the problem. For example:
+
+ at example
+awk 'BEGIN @{print "hello world"@}' </dev/null
+ at end example
+
+Posix says that in an @samp{END} action, @samp{$NF} (and presumably,
+ at samp{$1}) retain their value from the last record read, if no
+intervening @samp{getline} occurred. However, some implementations
+(such as Solaris 10 @samp{/usr/bin/awk}, @samp{nawk}, or Darwin
+ at samp{awk}) reset these variables. A workaround is to use an
+intermediate variable prior to the @samp{END} block. For example:
+
+ at example
+$ @kbd{cat end.awk}
+@{ tmp = $1 @}
+END @{ print "a", $1, $NF, "b", tmp @}
+$ @kbd{echo 1 | awk -f end.awk}
+a b 1
+$ @kbd{echo 1 | gawk -f end.awk}
+a 1 1 b 1
+ at end example
+
+If you want your program to be deterministic, don't depend on @code{for}
+on arrays:
+
+ at example
+$ @kbd{cat for.awk}
+END @{
+ arr["foo"] = 1
+ arr["bar"] = 1
+ for (i in arr)
+ print i
+@}
+$ @kbd{gawk -f for.awk </dev/null}
+foo
+bar
+$ @kbd{nawk -f for.awk </dev/null}
+bar
+foo
+ at end example
+
+Some Awk implementations, such as HP-UX 11.0's native one,
+mishandle anchors:
+
+ at example
+$ @kbd{echo xfoo | $AWK '/foo|^bar/ @{ print @}'}
+$ @kbd{echo bar | $AWK '/foo|^bar/ @{ print @}'}
+bar
+$ @kbd{echo xfoo | $AWK '/^bar|foo/ @{ print @}'}
+xfoo
+$ @kbd{echo bar | $AWK '/^bar|foo/ @{ print @}'}
+bar
+ at end example
+
+ at noindent
+Either do not depend on such patterns (i.e., use @samp{/^(.*foo|bar)/},
+or use a simple test to reject such implementations.
+
+On @samp{ia64-hp-hpux11.23}, Awk mishandles @code{printf} conversions
+after @code{%u}:
+
+ at example
+$ @kbd{awk 'BEGIN @{ printf "%u %d\n", 0, -1 @}'}
+0 0
+ at end example
+
+AIX version 5.2 has an arbitrary limit of 399 on the
+length of regular expressions and literal strings in an Awk program.
+
+Traditional Awk implementations derived from Unix version 7, such as
+Solaris @command{/bin/awk}, have many limitations and do not
+conform to Posix. Nowadays @code{AC_PROG_AWK} (@pxref{Particular
+Programs}) finds you an Awk that doesn't have these problems, but if
+for some reason you prefer not to use @code{AC_PROG_AWK} you may need to
+address them. For more detailed descriptions, see @ref{Language
+History, , @command{awk} language history, gawk, GNU Awk User's Guide}.
+
+Traditional Awk does not support multidimensional arrays or user-defined
+functions.
+
+Traditional Awk does not support the @option{-v} option. You can use
+assignments after the program instead, e.g., @code{$AWK '@{print v
+$1@}' v=x}; however, don't forget that such assignments are not
+evaluated until they are encountered (e.g., after any @code{BEGIN}
+action).
+
+Traditional Awk does not support the keywords @code{delete} or @code{do}.
+
+Traditional Awk does not support the expressions
+ at code{@var{a}?@var{b}:@var{c}}, @code{!@var{a}}, @code{@var{a}^@var{b}},
+or @code{@var{a}^=@var{b}}.
+
+Traditional Awk does not support the predefined @code{CONVFMT} or
+ at code{ENVIRON} variables.
+
+Traditional Awk supports only the predefined functions @code{exp}, @code{index},
+ at code{int}, @code{length}, @code{log}, @code{split}, @code{sprintf},
+ at code{sqrt}, and @code{substr}.
+
+Traditional Awk @code{getline} is not at all compatible with Posix;
+avoid it.
+
+Traditional Awk has @code{for (i in a) @dots{}} but no other uses of the
+ at code{in} keyword. For example, it lacks @code{if (i in a) @dots{}}.
+
+In code portable to both traditional and modern Awk, @code{FS} must be a
+string containing just one ordinary character, and similarly for the
+field-separator argument to @code{split}.
+
+Traditional Awk has a limit of 99 fields in a record. Since some Awk
+implementations, like Tru64's, split the input even if you don't refer
+to any field in the script, to circumvent this problem, set @samp{FS}
+to an unusual character and use @code{split}.
+
+Traditional Awk has a limit of at most 99 bytes in a number formatted by
+ at code{OFMT}; for example, @code{OFMT="%.300e"; print 0.1;} typically
+dumps core.
+
+The original version of Awk had a limit of at most 99 bytes per
+ at code{split} field, 99 bytes per @code{substr} substring, and 99 bytes
+per run of non-special characters in a @code{printf} format, but these
+bugs have been fixed on all practical hosts that we know of.
+
+HP-UX 11.00 and IRIX 6.5 Awk require that input files have a line length
+of at most 3070 bytes.
+
+ at item @command{basename}
+ at c ---------------------
+ at prindex @command{basename}
+Not all hosts have a working @command{basename}.
+You can use @command{expr} instead.
+
+ at c AS_BASENAME is to be replaced by a better API.
+ at ignore
+Not all hosts have a working @command{basename}, and you should instead
+use @code{AS_BASENAME} (@pxref{Programming in M4sh}), followed by
+ at command{expr} if you need to strip a suffix. For example:
+
+ at example
+a=`basename "$aname"` # This is not portable.
+a=`AS_BASENAME(["$aname"])` # This is more portable.
+
+# This is not portable.
+c=`basename "$cname" .c`
+
+# This is more portable.
+c=`AS_BASENAME(["$cname"])`
+case $c in
+?*.c) c=`expr "X$c" : 'X\(.*\)\.c'`;;
+esac
+ at end example
+ at end ignore
+
+
+ at item @command{cat}
+ at c ----------------
+ at prindex @command{cat}
+Don't rely on any option.
+
+
+ at item @command{cc}
+ at c ---------------
+ at prindex @command{cc}
+The command @samp{cc -c foo.c} traditionally produces an object file
+named @file{foo.o}. Most compilers allow @option{-c} to be combined
+with @option{-o} to specify a different object file name, but
+Posix does not require this combination and a few compilers
+lack support for it. @xref{C Compiler}, for how GNU Make
+tests for this feature with @code{AC_PROG_CC_C_O}.
+
+When a compilation such as @samp{cc -o foo foo.c} fails, some compilers
+(such as CDS on Reliant Unix) leave a @file{foo.o}.
+
+HP-UX @command{cc} doesn't accept @file{.S} files to preprocess and
+assemble. @samp{cc -c foo.S} appears to succeed, but in fact does
+nothing.
+
+The default executable, produced by @samp{cc foo.c}, can be
+
+ at itemize
+ at item @file{a.out} --- usual Posix convention.
+ at item @file{b.out} --- i960 compilers (including @command{gcc}).
+ at item @file{a.exe} --- DJGPP port of @command{gcc}.
+ at item @file{a_out.exe} --- GNV @command{cc} wrapper for DEC C on OpenVMS.
+ at item @file{foo.exe} --- various MS-DOS compilers.
+ at end itemize
+
+The C compiler's traditional name is @command{cc}, but other names like
+ at command{gcc} are common. Posix 1003.1-2001 specifies the
+name @command{c99}, but older Posix editions specified
+ at command{c89} and anyway these standard names are rarely used in
+practice. Typically the C compiler is invoked from makefiles that use
+ at samp{$(CC)}, so the value of the @samp{CC} make variable selects the
+compiler name.
+
+ at item @command{chgrp}
+ at itemx @command{chown}
+ at c -------------------
+ at prindex @command{chgrp}
+ at prindex @command{chown}
+It is not portable to change a file's group to a group that the owner
+does not belong to.
+
+ at item @command{chmod}
+ at c ------------------
+ at prindex @command{chmod}
+Avoid usages like @samp{chmod -w file}; use @samp{chmod a-w file}
+instead, for two reasons. First, plain @option{-w} does not necessarily
+make the file unwritable, since it does not affect mode bits that
+correspond to bits in the file mode creation mask. Second,
+Posix says that the @option{-w} might be interpreted as an
+implementation-specific option, not as a mode; Posix suggests
+using @samp{chmod -- -w file} to avoid this confusion, but unfortunately
+ at samp{--} does not work on some older hosts.
+
+
+ at item @command{cmp}
+ at c ----------------
+ at prindex @command{cmp}
+ at command{cmp} performs a raw data comparison of two files, while
+ at command{diff} compares two text files. Therefore, if you might compare
+DOS files, even if only checking whether two files are different, use
+ at command{diff} to avoid spurious differences due to differences of
+newline encoding.
+
+
+ at item @command{cp}
+ at c ---------------
+ at prindex @command{cp}
+Avoid the @option{-r} option, since Posix 1003.1-2004 marks it as
+obsolescent and its behavior on special files is implementation-defined.
+Use @option{-R} instead. On GNU hosts the two options
+are equivalent, but on Solaris hosts (for example) @code{cp -r}
+reads from pipes instead of replicating them. AIX 5.3 @code{cp -R} may
+corrupt its own memory with some directory hierarchies and error out or
+dump core:
+
+ at example
+ at kbd{mkdir -p 12345678/12345678/12345678/12345678}
+ at kbd{touch 12345678/12345678/x}
+ at kbd{cp -R 12345678 t}
+cp: 0653-440 12345678/12345678/: name too long.
+ at end example
+
+Some @command{cp} implementations (e.g., BSD/OS 4.2) do not allow
+trailing slashes at the end of nonexistent destination directories. To
+avoid this problem, omit the trailing slashes. For example, use
+ at samp{cp -R source /tmp/newdir} rather than @samp{cp -R source
+/tmp/newdir/} if @file{/tmp/newdir} does not exist.
+
+ at c This is thanks to Ian.
+The ancient SunOS 4 @command{cp} does not support @option{-f}, although
+its @command{mv} does.
+
+ at cindex timestamp resolution
+Traditionally, file timestamps had 1-second resolution, and @samp{cp
+-p} copied the timestamps exactly. However, many modern file systems
+have timestamps with 1-nanosecond resolution. Unfortunately, some older
+ at samp{cp -p} implementations truncate timestamps when copying files,
+which can cause the destination file to appear to be older than the
+source. The exact amount of truncation depends on the resolution of
+the system calls that @command{cp} uses. Traditionally this was
+ at code{utime}, which has 1-second resolution. Less-ancient @command{cp}
+implementations such as GNU Core Utilities 5.0.91 (2003) use
+ at code{utimes}, which has 1-microsecond resolution. Modern
+implementations such as GNU Core Utilities 6.12 (2008) can set timestamps to
+the full nanosecond resolution, using the modern system calls
+ at code{futimens} and @code{utimensat} when they are available. As of
+2011, though, many platforms do not yet fully support these new system
+calls.
+
+Bob Proulx notes that @samp{cp -p} always @emph{tries} to copy
+ownerships. But whether it actually does copy ownerships or not is a
+system dependent policy decision implemented by the kernel. If the
+kernel allows it then it happens. If the kernel does not allow it then
+it does not happen. It is not something @command{cp} itself has control
+over.
+
+In Unix System V any user can chown files to any other user, and System
+V also has a non-sticky @file{/tmp}. That probably derives from the
+heritage of System V in a business environment without hostile users.
+BSD changed this
+to be a more secure model where only root can @command{chown} files and
+a sticky @file{/tmp} is used. That undoubtedly derives from the heritage
+of BSD in a campus environment.
+
+GNU/Linux and Solaris by default follow BSD, but
+can be configured to allow a System V style @command{chown}. On the
+other hand, HP-UX follows System V, but can
+be configured to use the modern security model and disallow
+ at command{chown}. Since it is an administrator-configurable parameter
+you can't use the name of the kernel as an indicator of the behavior.
+
+
+
+ at item @command{date}
+ at c -----------------
+ at prindex @command{date}
+Some versions of @command{date} do not recognize special @samp{%} directives,
+and unfortunately, instead of complaining, they just pass them through,
+and exit with success:
+
+ at example
+$ @kbd{uname -a}
+OSF1 medusa.sis.pasteur.fr V5.1 732 alpha
+$ @kbd{date "+%s"}
+%s
+ at end example
+
+
+ at item @command{diff}
+ at c -----------------
+ at prindex @command{diff}
+Option @option{-u} is nonportable.
+
+Some implementations, such as Tru64's, fail when comparing to
+ at file{/dev/null}. Use an empty file instead.
+
+
+ at item @command{dirname}
+ at c --------------------
+ at prindex @command{dirname}
+Not all hosts have a working @command{dirname}, and you should instead
+use @code{AS_DIRNAME} (@pxref{Programming in M4sh}). For example:
+
+ at example
+dir=`dirname "$file"` # This is not portable.
+dir=`AS_DIRNAME(["$file"])` # This is more portable.
+ at end example
+
+
+ at item @command{egrep}
+ at c ------------------
+ at prindex @command{egrep}
+Posix 1003.1-2001 no longer requires @command{egrep},
+but many hosts do not yet support the Posix
+replacement @code{grep -E}. Also, some traditional implementations do
+not work on long input lines. To work around these problems, invoke
+ at code{AC_PROG_EGREP} and then use @code{$EGREP}.
+
+Portable extended regular expressions should use @samp{\} only to escape
+characters in the string @samp{$()*+.?[\^@{|}. For example, @samp{\@}}
+is not portable, even though it typically matches @samp{@}}.
+
+The empty alternative is not portable. Use @samp{?} instead. For
+instance with Digital Unix v5.0:
+
+ at example
+> printf "foo\n|foo\n" | $EGREP '^(|foo|bar)$'
+|foo
+> printf "bar\nbar|\n" | $EGREP '^(foo|bar|)$'
+bar|
+> printf "foo\nfoo|\n|bar\nbar\n" | $EGREP '^(foo||bar)$'
+foo
+|bar
+ at end example
+
+ at command{$EGREP} also suffers the limitations of @command{grep}
+(@pxref{grep, , Limitations of Usual Tools}).
+
+ at item @command{expr}
+ at c -----------------
+ at prindex @command{expr}
+Not all implementations obey the Posix rule that @samp{--} separates
+options from arguments; likewise, not all implementations provide the
+extension to Posix that the first argument can be treated as part of a
+valid expression rather than an invalid option if it begins with
+ at samp{-}. When performing arithmetic, use @samp{expr 0 + $var} if
+ at samp{$var} might be a negative number, to keep @command{expr} from
+interpreting it as an option.
+
+No @command{expr} keyword starts with @samp{X}, so use @samp{expr
+X"@var{word}" : 'X at var{regex}'} to keep @command{expr} from
+misinterpreting @var{word}.
+
+Don't use @code{length}, @code{substr}, @code{match} and @code{index}.
+
+ at item @command{expr} (@samp{|})
+ at prindex @command{expr} (@samp{|})
+You can use @samp{|}. Although Posix does require that @samp{expr
+''} return the empty string, it does not specify the result when you
+ at samp{|} together the empty string (or zero) with the empty string. For
+example:
+
+ at example
+expr '' \| ''
+ at end example
+
+Posix 1003.2-1992 returns the empty string
+for this case, but traditional Unix returns @samp{0} (Solaris is
+one such example). In Posix 1003.1-2001, the specification was
+changed to match traditional Unix's behavior (which is
+bizarre, but it's too late to fix this). Please note that the same
+problem does arise when the empty string results from a computation,
+as in:
+
+ at example
+expr bar : foo \| foo : bar
+ at end example
+
+ at noindent
+Avoid this portability problem by avoiding the empty string.
+
+
+ at item @command{expr} (@samp{:})
+ at c ----------------------------
+ at prindex @command{expr}
+Portable @command{expr} regular expressions should use @samp{\} to
+escape only characters in the string @samp{$()*.0123456789[\^n@{@}}.
+For example, alternation, @samp{\|}, is common but Posix does not
+require its support, so it should be avoided in portable scripts.
+Similarly, @samp{\+} and @samp{\?} should be avoided.
+
+Portable @command{expr} regular expressions should not begin with
+ at samp{^}. Patterns are automatically anchored so leading @samp{^} is
+not needed anyway.
+
+On the other hand, the behavior of the @samp{$} anchor is not portable
+on multi-line strings. Posix is ambiguous whether the anchor applies to
+each line, as was done in older versions of the GNU Core Utilities, or
+whether it applies only to the end of the overall string, as in
+Coreutils 6.0 and most other implementations.
+
+ at example
+$ @kbd{baz='foo}
+> @kbd{bar'}
+$ @kbd{expr "X$baz" : 'X\(foo\)$'}
+
+$ @kbd{expr-5.97 "X$baz" : 'X\(foo\)$'}
+foo
+ at end example
+
+The Posix standard is ambiguous as to whether
+ at samp{expr 'a' : '\(b\)'} outputs @samp{0} or the empty string.
+In practice, it outputs the empty string on most platforms, but portable
+scripts should not assume this. For instance, the QNX 4.25 native
+ at command{expr} returns @samp{0}.
+
+One might think that a way to get a uniform behavior would be to use
+the empty string as a default value:
+
+ at example
+expr a : '\(b\)' \| ''
+ at end example
+
+ at noindent
+Unfortunately this behaves exactly as the original expression; see the
+ at command{expr} (@samp{|}) entry for more information.
+
+Some ancient @command{expr} implementations (e.g., SunOS 4 @command{expr} and
+Solaris 8 @command{/usr/ucb/expr}) have a silly length limit that causes
+ at command{expr} to fail if the matched substring is longer than 120
+bytes. In this case, you might want to fall back on @samp{echo|sed} if
+ at command{expr} fails. Nowadays this is of practical importance only for
+the rare installer who mistakenly puts @file{/usr/ucb} before
+ at file{/usr/bin} in @env{PATH}.
+
+On Mac OS X 10.4, @command{expr} mishandles the pattern @samp{[^-]} in
+some cases. For example, the command
+ at example
+expr Xpowerpc-apple-darwin8.1.0 : 'X[^-]*-[^-]*-\(.*\)'
+ at end example
+
+ at noindent
+outputs @samp{apple-darwin8.1.0} rather than the correct @samp{darwin8.1.0}.
+This particular case can be worked around by substituting @samp{[^--]}
+for @samp{[^-]}.
+
+Don't leave, there is some more!
+
+The QNX 4.25 @command{expr}, in addition of preferring @samp{0} to
+the empty string, has a funny behavior in its exit status: it's always 1
+when parentheses are used!
+
+ at example
+$ @kbd{val=`expr 'a' : 'a'`; echo "$?: $val"}
+0: 1
+$ @kbd{val=`expr 'a' : 'b'`; echo "$?: $val"}
+1: 0
+
+$ @kbd{val=`expr 'a' : '\(a\)'`; echo "?: $val"}
+1: a
+$ @kbd{val=`expr 'a' : '\(b\)'`; echo "?: $val"}
+1: 0
+ at end example
+
+ at noindent
+In practice this can be a big problem if you are ready to catch failures
+of @command{expr} programs with some other method (such as using
+ at command{sed}), since you may get twice the result. For instance
+
+ at example
+$ @kbd{expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/'}
+ at end example
+
+ at noindent
+outputs @samp{a} on most hosts, but @samp{aa} on QNX 4.25. A
+simple workaround consists of testing @command{expr} and using a variable
+set to @command{expr} or to @command{false} according to the result.
+
+Tru64 @command{expr} incorrectly treats the result as a number, if it
+can be interpreted that way:
+
+ at example
+$ @kbd{expr 00001 : '.*\(...\)'}
+1
+ at end example
+
+On HP-UX 11, @command{expr} only supports a single
+sub-expression.
+
+ at example
+$ @kbd{expr 'Xfoo' : 'X\(f\(oo\)*\)$'}
+expr: More than one '\(' was used.
+ at end example
+
+
+ at item @command{fgrep}
+ at c ------------------
+ at prindex @command{fgrep}
+Posix 1003.1-2001 no longer requires @command{fgrep},
+but many hosts do not yet support the Posix
+replacement @code{grep -F}. Also, some traditional implementations do
+not work on long input lines. To work around these problems, invoke
+ at code{AC_PROG_FGREP} and then use @code{$FGREP}.
+
+Tru64/OSF 5.1 @command{fgrep} does not match an empty pattern.
+
+
+ at item @command{find}
+ at c -----------------
+ at prindex @command{find}
+The option @option{-maxdepth} seems to be GNU specific.
+Tru64 v5.1, NetBSD 1.5 and Solaris @command{find}
+commands do not understand it.
+
+The replacement of @samp{@{@}} is guaranteed only if the argument is
+exactly @emph{@{@}}, not if it's only a part of an argument. For
+instance on DU, and HP-UX 10.20 and HP-UX 11:
+
+ at example
+$ @kbd{touch foo}
+$ @kbd{find . -name foo -exec echo "@{@}-@{@}" \;}
+@{@}-@{@}
+ at end example
+
+ at noindent
+while GNU @command{find} reports @samp{./foo-./foo}.
+
+
+ at anchor{grep}
+ at item @command{grep}
+ at c -----------------
+ at prindex @command{grep}
+Portable scripts can rely on the @command{grep} options @option{-c},
+ at option{-l}, @option{-n}, and @option{-v}, but should avoid other
+options. For example, don't use @option{-w}, as Posix does not require
+it and Irix 6.5.16m's @command{grep} does not support it. Also,
+portable scripts should not combine @option{-c} with @option{-l},
+as Posix does not allow this.
+
+Some of the options required by Posix are not portable in practice.
+Don't use @samp{grep -q} to suppress output, because many @command{grep}
+implementations (e.g., Solaris) do not support @option{-q}.
+Don't use @samp{grep -s} to suppress output either, because Posix
+says @option{-s} does not suppress output, only some error messages;
+also, the @option{-s} option of traditional @command{grep} behaved
+like @option{-q} does in most modern implementations. Instead,
+redirect the standard output and standard error (in case the file
+doesn't exist) of @code{grep} to @file{/dev/null}. Check the exit
+status of @code{grep} to determine whether it found a match.
+
+The QNX4 implementation fails to count lines with @code{grep -c '$'},
+but works with @code{grep -c '^'}. Other alternatives for counting
+lines are to use @code{sed -n '$='} or @code{wc -l}.
+
+Some traditional @command{grep} implementations do not work on long
+input lines. On AIX the default @code{grep} silently truncates long
+lines on the input before matching.
+
+Also, many implementations do not support multiple regexps
+with @option{-e}: they either reject @option{-e} entirely (e.g., Solaris)
+or honor only the last pattern (e.g., IRIX 6.5 and NeXT). To
+work around these problems, invoke @code{AC_PROG_GREP} and then use
+ at code{$GREP}.
+
+Another possible workaround for the multiple @option{-e} problem is to
+separate the patterns by newlines, for example:
+
+ at example
+grep 'foo
+bar' in.txt
+ at end example
+
+ at noindent
+except that this fails with traditional @command{grep}
+implementations and with OpenBSD 3.8 @command{grep}.
+
+Traditional @command{grep} implementations (e.g., Solaris) do not
+support the @option{-E} or @option{-F} options. To work around these
+problems, invoke @code{AC_PROG_EGREP} and then use @code{$EGREP}, and
+similarly for @code{AC_PROG_FGREP} and @code{$FGREP}. Even if you are
+willing to require support for Posix @command{grep}, your script should
+not use both @option{-E} and @option{-F}, since Posix does not allow
+this combination.
+
+Portable @command{grep} regular expressions should use @samp{\} only to
+escape characters in the string @samp{$()*.0123456789[\^@{@}}. For example,
+alternation, @samp{\|}, is common but Posix does not require its
+support in basic regular expressions, so it should be avoided in
+portable scripts. Solaris and HP-UX @command{grep} do not support it.
+Similarly, the following escape sequences should also be avoided:
+ at samp{\<}, @samp{\>}, @samp{\+}, @samp{\?}, @samp{\`}, @samp{\'},
+ at samp{\B}, @samp{\b}, @samp{\S}, @samp{\s}, @samp{\W}, and @samp{\w}.
+
+Posix does not specify the behavior of @command{grep} on binary files.
+An example where this matters is using BSD @command{grep} to
+search text that includes embedded ANSI escape sequences for
+colored output to terminals (@samp{\033[m} is the sequence to restore
+normal output); the behavior depends on whether input is seekable:
+
+ at example
+$ @kbd{printf 'esc\033[mape\n' > sample}
+$ @kbd{grep . sample}
+Binary file sample matches
+$ @kbd{cat sample | grep .}
+escape
+ at end example
+
+
+ at item @command{join}
+ at c -----------------
+ at prindex @command{join}
+Solaris 8 @command{join} has bugs when the second operand is standard
+input, and when standard input is a pipe. For example, the following
+shell script causes Solaris 8 @command{join} to loop forever:
+
+ at example
+cat >file <<'EOF'
+1 x
+2 y
+EOF
+cat file | join file -
+ at end example
+
+Use @samp{join - file} instead.
+
+On NetBSD, @command{join -a 1 file1 file2} mistakenly behaves like
+ at command{join -a 1 -a 2 1 file1 file2}, resulting in a usage warning;
+the workaround is to use @command{join -a1 file1 file2} instead.
+
+ at item @command{ln}
+ at c ---------------
+ at prindex @command{ln}
+ at cindex Symbolic links
+Don't rely on @command{ln} having a @option{-f} option. Symbolic links
+are not available on old systems; use @samp{$(LN_S)} as a portable substitute.
+
+For versions of the DJGPP before 2.04,
+ at command{ln} emulates symbolic links
+to executables by generating a stub that in turn calls the real
+program. This feature also works with nonexistent files like in the
+Posix spec. So @samp{ln -s file link} generates @file{link.exe},
+which attempts to call @file{file.exe} if run. But this feature only
+works for executables, so @samp{cp -p} is used instead for these
+systems. DJGPP versions 2.04 and later have full support
+for symbolic links.
+
+
+ at item @command{ls}
+ at c ---------------
+ at prindex @command{ls}
+ at cindex Listing directories
+The portable options are @option{-acdilrtu}. Current practice is for
+ at option{-l} to output both owner and group, even though ancient versions
+of @command{ls} omitted the group.
+
+On ancient hosts, @samp{ls foo} sent the diagnostic @samp{foo not found}
+to standard output if @file{foo} did not exist. Hence a shell command
+like @samp{sources=`ls *.c 2>/dev/null`} did not always work, since it
+was equivalent to @samp{sources='*.c not found'} in the absence of
+ at samp{.c} files. This is no longer a practical problem, since current
+ at command{ls} implementations send diagnostics to standard error.
+
+The behavior of @command{ls} on a directory that is being concurrently
+modified is not always predictable, because of a data race where cached
+information returned by @code{readdir} does not match the current
+directory state. In fact, MacOS 10.5 has an intermittent bug where
+ at code{readdir}, and thus @command{ls}, sometimes lists a file more than
+once if other files were added or removed from the directory immediately
+prior to the @command{ls} call. Since @command{ls} already sorts its
+output, the duplicate entries can be avoided by piping the results
+through @code{uniq}.
+
+ at anchor{mkdir}
+ at item @command{mkdir}
+ at c ------------------
+ at prindex @command{mkdir}
+ at cindex Making directories
+No @command{mkdir} option is portable to older systems. Instead of
+ at samp{mkdir -p @var{file-name}}, you should use
+ at code{AS_MKDIR_P(@var{file-name})} (@pxref{Programming in M4sh})
+or @code{AC_PROG_MKDIR_P} (@pxref{Particular Programs}).
+
+Combining the @option{-m} and @option{-p} options, as in @samp{mkdir -m
+go-w -p @var{dir}}, often leads to trouble. FreeBSD
+ at command{mkdir} incorrectly attempts to change the permissions of
+ at var{dir} even if it already exists. HP-UX 11.23 and
+IRIX 6.5 @command{mkdir} often assign the wrong permissions to
+any newly-created parents of @var{dir}.
+
+Posix does not clearly specify whether @samp{mkdir -p foo}
+should succeed when @file{foo} is a symbolic link to an already-existing
+directory. The GNU Core Utilities 5.1.0 @command{mkdir}
+succeeds, but Solaris @command{mkdir} fails.
+
+Traditional @code{mkdir -p} implementations suffer from race conditions.
+For example, if you invoke @code{mkdir -p a/b} and @code{mkdir -p a/c}
+at the same time, both processes might detect that @file{a} is missing,
+one might create @file{a}, then the other might try to create @file{a}
+and fail with a @code{File exists} diagnostic. The GNU Core
+Utilities (@samp{fileutils} version 4.1), FreeBSD 5.0,
+NetBSD 2.0.2, and OpenBSD 2.4 are known to be
+race-free when two processes invoke @code{mkdir -p} simultaneously, but
+earlier versions are vulnerable. Solaris @command{mkdir} is still
+vulnerable as of Solaris 10, and other traditional Unix systems are
+probably vulnerable too. This possible race is harmful in parallel
+builds when several Make rules call @code{mkdir -p} to
+construct directories. You may use
+ at code{install-sh -d} as a safe replacement, provided this script is
+recent enough; the copy shipped with Autoconf 2.60 and Automake 1.10 is
+OK, but copies from older versions are vulnerable.
+
+
+ at item @command{mkfifo}
+ at itemx @command{mknod}
+ at c -------------------
+ at prindex @command{mkfifo}
+ at prindex @command{mknod}
+The GNU Coding Standards state that @command{mknod} is safe to use on
+platforms where it has been tested to exist; but it is generally portable
+only for creating named FIFOs, since device numbers are
+platform-specific. Autotest uses @command{mkfifo} to implement parallel
+testsuites. Posix states that behavior is unspecified when opening a
+named FIFO for both reading and writing; on at least Cygwin, this
+results in failure on any attempt to read or write to that file
+descriptor.
+
+ at item @command{mktemp}
+ at c -------------------
+ at prindex @command{mktemp}
+ at cindex Creating temporary files
+Shell scripts can use temporary files safely with @command{mktemp}, but
+it does not exist on all systems. A portable way to create a safe
+temporary file name is to create a temporary directory with mode 700 and
+use a file inside this directory. Both methods prevent attackers from
+gaining control, though @command{mktemp} is far less likely to fail
+gratuitously under attack.
+
+Here is sample code to create a new temporary directory @samp{$dir} safely:
+
+ at example
+# Create a temporary directory $dir in $TMPDIR (default /tmp).
+# Use mktemp if possible; otherwise fall back on mkdir,
+# with $RANDOM to make collisions less likely.
+: "$@{TMPDIR:=/tmp@}"
+@{
+ dir=`
+ (umask 077 && mktemp -d "$TMPDIR/fooXXXXXX") 2>/dev/null
+ ` &&
+ test -d "$dir"
+@} || @{
+ dir=$TMPDIR/foo$$-$RANDOM
+ at c $$ restore font-lock
+ (umask 077 && mkdir "$dir")
+@} || exit $?
+ at end example
+
+
+ at item @command{mv}
+ at c ---------------
+ at prindex @command{mv}
+ at cindex Moving open files
+The only portable options are @option{-f} and @option{-i}.
+
+Moving individual files between file systems is portable (it was in Unix
+version 6),
+but it is not always atomic: when doing @samp{mv new existing}, there's
+a critical section where neither the old nor the new version of
+ at file{existing} actually exists.
+
+On some systems moving files from @file{/tmp} can sometimes cause
+undesirable (but perfectly valid) warnings, even if you created these
+files. This is because @file{/tmp} belongs to a group that ordinary
+users are not members of, and files created in @file{/tmp} inherit
+the group of @file{/tmp}. When the file is copied, @command{mv} issues
+a diagnostic without failing:
+
+ at smallexample
+$ @kbd{touch /tmp/foo}
+$ @kbd{mv /tmp/foo .}
+ at error{}mv: ./foo: set owner/group (was: 100/0): Operation not permitted
+$ @kbd{echo $?}
+0
+$ @kbd{ls foo}
+foo
+ at end smallexample
+
+ at noindent
+This annoying behavior conforms to Posix, unfortunately.
+
+Moving directories across mount points is not portable, use @command{cp}
+and @command{rm}.
+
+DOS variants cannot rename or remove open files, and do not
+support commands like @samp{mv foo bar >foo}, even though this is
+perfectly portable among Posix hosts.
+
+
+ at item @command{od}
+ at c ---------------
+ at prindex @command{od}
+
+In Mac OS X 10.3, @command{od} does not support the
+standard Posix options @option{-A}, @option{-j}, @option{-N}, or
+ at option{-t}, or the XSI option @option{-s}. The only
+supported Posix option is @option{-v}, and the only supported
+XSI options are those in @option{-bcdox}. The BSD
+ at command{hexdump} program can be used instead.
+
+This problem no longer exists in Mac OS X 10.4.3.
+
+
+ at item @command{rm}
+ at c ---------------
+ at prindex @command{rm}
+The @option{-f} and @option{-r} options are portable.
+
+It is not portable to invoke @command{rm} without options or operands.
+On the other hand, Posix now requires @command{rm -f} to silently
+succeed when there are no operands (useful for constructs like
+ at command{rm -rf $filelist} without first checking if @samp{$filelist}
+was empty). But this was not always portable; at least NetBSD
+ at command{rm} built before 2008 would fail with a diagnostic.
+
+A file might not be removed even if its parent directory is writable
+and searchable. Many Posix hosts cannot remove a mount point, a named
+stream, a working directory, or a last link to a file that is being
+executed.
+
+DOS variants cannot rename or remove open files, and do not
+support commands like @samp{rm foo >foo}, even though this is
+perfectly portable among Posix hosts.
+
+ at item @command{rmdir}
+ at c ------------------
+ at prindex @command{rmdir}
+Just as with @command{rm}, some platforms refuse to remove a working
+directory.
+
+ at anchor{sed}
+ at item @command{sed}
+ at c ----------------
+ at prindex @command{sed}
+Patterns should not include the separator (unless escaped), even as part
+of a character class. In conformance with Posix, the Cray
+ at command{sed} rejects @samp{s/[^/]*$//}: use @samp{s%[^/]*$%%}.
+Even when escaped, patterns should not include separators that are also
+used as @command{sed} metacharacters. For example, GNU sed 4.0.9 rejects
+ at samp{s,x\@{1\,\@},,}, while sed 4.1 strips the backslash before the comma
+before evaluating the basic regular expression.
+
+Avoid empty patterns within parentheses (i.e., @samp{\(\)}). Posix does
+not require support for empty patterns, and Unicos 9 @command{sed} rejects
+them.
+
+Unicos 9 @command{sed} loops endlessly on patterns like @samp{.*\n.*}.
+
+Sed scripts should not use branch labels longer than 7 characters and
+should not contain comments; AIX 5.3 @command{sed} rejects indented comments.
+HP-UX sed has a limit of 99 commands (not counting @samp{:} commands) and
+48 labels, which cannot be circumvented by using more than one script
+file. It can execute up to 19 reads with the @samp{r} command per cycle.
+Solaris @command{/usr/ucb/sed} rejects usages that exceed a limit of
+about 6000 bytes for the internal representation of commands.
+
+Avoid redundant @samp{;}, as some @command{sed} implementations, such as
+NetBSD 1.4.2's, incorrectly try to interpret the second
+ at samp{;} as a command:
+
+ at example
+$ @kbd{echo a | sed 's/x/x/;;s/x/x/'}
+sed: 1: "s/x/x/;;s/x/x/": invalid command code ;
+ at end example
+
+Some @command{sed} implementations have a buffer limited to 4000 bytes,
+and this limits the size of input lines, output lines, and internal
+buffers that can be processed portably. Likewise,
+not all @command{sed} implementations can handle embedded @code{NUL} or
+a missing trailing newline.
+
+Remember that ranges within a bracket expression of a regular expression
+are only well-defined in the @samp{C} (or @samp{POSIX}) locale.
+Meanwhile, support for character classes like @samp{[[:upper:]]} is not
+yet universal, so if you cannot guarantee the setting of @env{LC_ALL},
+it is better to spell out a range @samp{[ABCDEFGHIJKLMNOPQRSTUVWXYZ]}
+than to rely on @samp{[A-Z]}.
+
+Additionally, Posix states that regular expressions are only
+well-defined on characters. Unfortunately, there exist platforms such
+as MacOS X 10.5 where not all 8-bit byte values are valid characters,
+even though that platform has a single-byte @samp{C} locale. And Posix
+allows the existence of a multi-byte @samp{C} locale, although that does
+not yet appear to be a common implementation. At any rate, it means
+that not all bytes will be matched by the regular expression @samp{.}:
+
+ at example
+$ @kbd{printf '\200\n' | LC_ALL=C sed -n /./p | wc -l}
+0
+$ @kbd{printf '\200\n' | LC_ALL=en_US.ISO8859-1 sed -n /./p | wc -l}
+1
+ at end example
+
+Portable @command{sed} regular expressions should use @samp{\} only to escape
+characters in the string @samp{$()*.0123456789[\^n@{@}}. For example,
+alternation, @samp{\|}, is common but Posix does not require its
+support, so it should be avoided in portable scripts. Solaris
+ at command{sed} does not support alternation; e.g., @samp{sed '/a\|b/d'}
+deletes only lines that contain the literal string @samp{a|b}.
+Similarly, @samp{\+} and @samp{\?} should be avoided.
+
+Anchors (@samp{^} and @samp{$}) inside groups are not portable.
+
+Nested parentheses in patterns (e.g., @samp{\(\(a*\)b*)\)}) are
+quite portable to current hosts, but was not supported by some ancient
+ at command{sed} implementations like SVR3.
+
+Some @command{sed} implementations, e.g., Solaris, restrict the special
+role of the asterisk @samp{*} to one-character regular expressions and
+back-references, and the special role of interval expressions
+ at samp{\@{@var{m}\@}}, @samp{\@{@var{m},\@}}, or @samp{\@{@var{m}, at var{n}\@}}
+to one-character regular expressions. This may lead to unexpected behavior:
+
+ at example
+$ @kbd{echo '1*23*4' | /usr/bin/sed 's/\(.\)*/x/g'}
+x2x4
+$ @kbd{echo '1*23*4' | /usr/xpg4/bin/sed 's/\(.\)*/x/g'}
+x
+ at end example
+
+The @option{-e} option is mostly portable.
+However, its argument
+cannot start with @samp{a}, @samp{c}, or @samp{i},
+as this runs afoul of a Tru64 5.1 bug.
+Also, its argument cannot be empty, as this fails on AIX 5.3.
+Some people prefer to use @samp{-e}:
+
+ at example
+sed -e '@var{command-1}' \
+ -e '@var{command-2}'
+ at end example
+
+ at noindent
+as opposed to the equivalent:
+
+ at example
+sed '
+ @var{command-1}
+ @var{command-2}
+'
+ at end example
+
+ at noindent
+The following usage is sometimes equivalent:
+
+ at example
+sed '@var{command-1};@var{command-2}'
+ at end example
+
+but Posix says that this use of a semicolon has undefined effect if
+ at var{command-1}'s verb is @samp{@{}, @samp{a}, @samp{b}, @samp{c},
+ at samp{i}, @samp{r}, @samp{t}, @samp{w}, @samp{:}, or @samp{#}, so you
+should use semicolon only with simple scripts that do not use these
+verbs.
+
+Posix up to the 2008 revision requires the argument of the @option{-e}
+option to be a syntactically complete script. GNU @command{sed} allows
+to pass multiple script fragments, each as argument of a separate
+ at option{-e} option, that are then combined, with newlines between the
+fragments, and a future Posix revision may allow this as well. This
+approach is not portable with script fragments ending in backslash; for
+example, the @command{sed} programs on Solaris 10, HP-UX 11, and AIX
+don't allow splitting in this case:
+
+ at example
+$ @kbd{echo a | sed -n -e 'i\}
+ at kbd{0'}
+0
+$ @kbd{echo a | sed -n -e 'i\' -e 0}
+Unrecognized command: 0
+ at end example
+
+ at noindent
+In practice, however, this technique of joining fragments
+through @option{-e} works for multiple @command{sed} functions within
+ at samp{@{} and @samp{@}}, even if that is not specified by Posix:
+
+ at example
+ at c The quote around the closing brace silences interactive zsh.
+$ @kbd{echo a | sed -n -e '/a/@{' -e s/a/b/ -e p -e '@}'}
+b
+ at end example
+
+Commands inside @{ @} brackets are further restricted. Posix 2008 says that
+they cannot be preceded by addresses, @samp{!}, or @samp{;}, and that
+each command must be followed immediately by a newline, without any
+intervening blanks or semicolons. The closing bracket must be alone on
+a line, other than white space preceding or following it. However, a
+future version of Posix may standardize the use of addresses within brackets.
+
+Contrary to yet another urban legend, you may portably use @samp{&} in
+the replacement part of the @code{s} command to mean ``what was
+matched''. All descendants of Unix version 7 @command{sed}
+(at least; we
+don't have first hand experience with older @command{sed} implementations) have
+supported it.
+
+Posix requires that you must not have any white space between
+ at samp{!} and the following command. It is OK to have blanks between
+the address and the @samp{!}. For instance, on Solaris:
+
+ at example
+$ @kbd{echo "foo" | sed -n '/bar/ ! p'}
+ at error{}Unrecognized command: /bar/ ! p
+$ @kbd{echo "foo" | sed -n '/bar/! p'}
+ at error{}Unrecognized command: /bar/! p
+$ @kbd{echo "foo" | sed -n '/bar/ !p'}
+foo
+ at end example
+
+Posix also says that you should not combine @samp{!} and @samp{;}. If
+you use @samp{!}, it is best to put it on a command that is delimited by
+newlines rather than @samp{;}.
+
+Also note that Posix requires that the @samp{b}, @samp{t}, @samp{r}, and
+ at samp{w} commands be followed by exactly one space before their argument.
+On the other hand, no white space is allowed between @samp{:} and the
+subsequent label name.
+
+If a sed script is specified on the command line and ends in an
+ at samp{a}, @samp{c}, or @samp{i} command, the last line of inserted text
+should be followed by a newline. Otherwise some @command{sed}
+implementations (e.g., OpenBSD 3.9) do not append a newline to the
+inserted text.
+
+Many @command{sed} implementations (e.g., MacOS X 10.4,
+OpenBSD 3.9, Solaris 10
+ at command{/usr/ucb/sed}) strip leading white space from the text of
+ at samp{a}, @samp{c}, and @samp{i} commands. Prepend a backslash to
+work around this incompatibility with Posix:
+
+ at example
+$ @kbd{echo flushleft | sed 'a\}
+> @kbd{ indented}
+> @kbd{'}
+flushleft
+indented
+$ @kbd{echo foo | sed 'a\}
+> @kbd{\ indented}
+> @kbd{'}
+flushleft
+ indented
+ at end example
+
+Posix requires that with an empty regular expression, the last non-empty
+regular expression from either an address specification or substitution
+command is applied. However, busybox 1.6.1 complains when using a
+substitution command with a replacement containing a back-reference to
+an empty regular expression; the workaround is repeating the regular
+expression.
+
+ at example
+$ @kbd{echo abc | busybox sed '/a\(b\)c/ s//\1/'}
+sed: No previous regexp.
+$ @kbd{echo abc | busybox sed '/a\(b\)c/ s/a\(b\)c/\1/'}
+b
+ at end example
+
+
+ at item @command{sed} (@samp{t})
+ at c ---------------------------
+ at prindex @command{sed} (@samp{t})
+Some old systems have @command{sed} that ``forget'' to reset their
+ at samp{t} flag when starting a new cycle. For instance on MIPS
+RISC/OS, and on IRIX 5.3, if you run the following @command{sed}
+script (the line numbers are not actual part of the texts):
+
+ at example
+s/keep me/kept/g # a
+t end # b
+s/.*/deleted/g # c
+:end # d
+ at end example
+
+ at noindent
+on
+
+ at example
+delete me # 1
+delete me # 2
+keep me # 3
+delete me # 4
+ at end example
+
+ at noindent
+you get
+
+ at example
+deleted
+delete me
+kept
+deleted
+ at end example
+
+ at noindent
+instead of
+
+ at example
+deleted
+deleted
+kept
+deleted
+ at end example
+
+Why? When processing line 1, (c) matches, therefore sets the @samp{t}
+flag, and the output is produced. When processing
+line 2, the @samp{t} flag is still set (this is the bug). Command (a)
+fails to match, but @command{sed} is not supposed to clear the @samp{t}
+flag when a substitution fails. Command (b) sees that the flag is set,
+therefore it clears it, and jumps to (d), hence you get @samp{delete me}
+instead of @samp{deleted}. When processing line (3), @samp{t} is clear,
+(a) matches, so the flag is set, hence (b) clears the flags and jumps.
+Finally, since the flag is clear, line 4 is processed properly.
+
+There are two things one should remember about @samp{t} in @command{sed}.
+Firstly, always remember that @samp{t} jumps if @emph{some} substitution
+succeeded, not only the immediately preceding substitution. Therefore,
+always use a fake @samp{t clear} followed by a @samp{:clear} on the next
+line, to reset the @samp{t} flag where needed.
+
+Secondly, you cannot rely on @command{sed} to clear the flag at each new
+cycle.
+
+One portable implementation of the script above is:
+
+ at example
+t clear
+:clear
+s/keep me/kept/g
+t end
+s/.*/deleted/g
+:end
+ at end example
+
+ at item @command{sleep}
+ at c ------------------
+ at prindex @command{sleep}
+Using @command{sleep} is generally portable. However, remember that
+adding a @command{sleep} to work around timestamp issues, with a minimum
+granularity of one second, doesn't scale well for parallel builds on
+modern machines with sub-second process completion.
+
+ at item @command{sort}
+ at c -----------------
+ at prindex @command{sort}
+Remember that sort order is influenced by the current locale. Inside
+ at file{configure}, the C locale is in effect, but in Makefile snippets,
+you may need to specify @code{LC_ALL=C sort}.
+
+ at item @command{tar}
+ at c ----------------
+ at prindex @command{tar}
+There are multiple file formats for @command{tar}; if you use Automake,
+the macro @code{AM_INIT_AUTOMAKE} has some options controlling which
+level of portability to use.
+
+ at anchor{touch}
+ at item @command{touch}
+ at c ------------------
+ at prindex @command{touch}
+ at cindex timestamp resolution
+If you specify the desired timestamp (e.g., with the @option{-r}
+option), older @command{touch} implementations use the @code{utime} or
+ at code{utimes} system call, which can result in the same kind of
+timestamp truncation problems that @samp{cp -p} has.
+
+On ancient BSD systems, @command{touch} or any command that
+results in an empty file does not update the timestamps, so use a
+command like @command{echo} as a workaround.
+Also,
+GNU @command{touch} 3.16r (and presumably all before that)
+fails to work on SunOS 4.1.3 when the empty file is on an
+NFS-mounted 4.2 volume.
+However, these problems are no longer of practical concern.
+
+ at item @command{tr}
+ at c ---------------
+ at prindex @command{tr}
+ at cindex carriage return, deleting
+ at cindex newline, deleting
+ at cindex deleting carriage return
+Not all versions of @command{tr} handle all backslash character escapes.
+For example, Solaris 10 @command{/usr/ucb/tr} falls over, even though
+Solaris contains more modern @command{tr} in other locations.
+Using octal escapes is more portable for carriage returns, since
+ at samp{\015} is the same for both ASCII and EBCDIC, and since use of
+literal carriage returns in scripts causes a number of other problems.
+But for other characters, like newline, using octal escapes ties the
+operation to ASCII, so it is better to use literal characters.
+
+ at example
+$ @kbd{@{ echo moon; echo light; @} | /usr/ucb/tr -d '\n' ; echo}
+moo
+light
+$ @kbd{@{ echo moon; echo light; @} | /usr/bin/tr -d '\n' ; echo}
+moonlight
+$ @kbd{@{ echo moon; echo light; @} | /usr/ucb/tr -d '\012' ; echo}
+moonlight
+$ @kbd{nl='}
+ at kbd{'; @{ echo moon; echo light; @} | /usr/ucb/tr -d "$nl" ; echo}
+moonlight
+ at end example
+
+Not all versions of @command{tr} recognize direct ranges of characters: at
+least Solaris @command{/usr/bin/tr} still fails to do so. But you can
+use @command{/usr/xpg4/bin/tr} instead, or add brackets (which in Posix
+transliterate to themselves).
+
+ at example
+$ @kbd{echo "Hazy Fantazy" | LC_ALL=C /usr/bin/tr a-z A-Z}
+HAZy FAntAZy
+$ @kbd{echo "Hazy Fantazy" | LC_ALL=C /usr/bin/tr '[a-z]' '[A-Z]'}
+HAZY FANTAZY
+$ @kbd{echo "Hazy Fantazy" | LC_ALL=C /usr/xpg4/bin/tr a-z A-Z}
+HAZY FANTAZY
+ at end example
+
+When providing two arguments, be sure the second string is at least as
+long as the first.
+
+ at example
+$ @kbd{echo abc | /usr/xpg4/bin/tr bc d}
+adc
+$ @kbd{echo abc | coreutils/tr bc d}
+add
+ at end example
+
+Posix requires @command{tr} to operate on binary files. But at least
+Solaris @command{/usr/ucb/tr} and @command{/usr/bin/tr} silently discard
+ at code{NUL} in the input prior to doing any translation. When using
+ at command{tr} to process a binary file that may contain @code{NUL} bytes,
+it is necessary to use @command{/usr/xpg4/bin/tr} instead, or
+ at command{/usr/xpg6/bin/tr} if that is available.
+
+ at example
+$ @kbd{printf 'a\0b' | /usr/ucb/tr x x | od -An -tx1}
+ 61 62
+$ @kbd{printf 'a\0b' | /usr/bin/tr x x | od -An -tx1}
+ 61 62
+$ @kbd{printf 'a\0b' | /usr/xpg4/bin/tr x x | od -An -tx1}
+ 61 00 62
+ at end example
+
+Solaris @command{/usr/ucb/tr} additionally fails to handle @samp{\0} as the
+octal escape for @code{NUL}.
+
+ at example
+$ @kbd{printf 'abc' | /usr/ucb/tr 'bc' '\0d' | od -An -tx1}
+ 61 62 63
+$ @kbd{printf 'abc' | /usr/bin/tr 'bc' '\0d' | od -An -tx1}
+ 61 00 64
+$ @kbd{printf 'abc' | /usr/xpg4/bin/tr 'bc' '\0d' | od -An -tx1}
+ 61 00 64
+ at end example
+
+ at end table
+
+
+ at node Portable Make
+ at chapter Portable Make Programming
+ at prindex @command{make}
+ at cindex Limitations of @command{make}
+
+Writing portable makefiles is an art. Since a makefile's commands are
+executed by the shell, you must consider the shell portability issues
+already mentioned. However, other issues are specific to @command{make}
+itself.
+
+ at menu
+* $< 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:: @code{make macro=value} and submakes
+* The Make Macro MAKEFLAGS:: @code{$(MAKEFLAGS)} portability issues
+* The Make Macro SHELL:: @code{$(SHELL)} portability issues
+* Parallel Make:: Parallel @command{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 @file{obj}
+* make -k Status:: Exit status of @samp{make -k}
+* VPATH and Make:: @code{VPATH} woes
+* Single Suffix Rules:: Single suffix rules and separated dependencies
+* Timestamps and Make:: Subsecond timestamp resolution
+ at end menu
+
+ at node $< in Ordinary Make Rules
+ at section @code{$<} in Ordinary Make Rules
+
+Posix says that the @samp{$<} construct in makefiles can be
+used only in inference rules and in the @samp{.DEFAULT} rule; its
+meaning in ordinary rules is unspecified. Solaris @command{make}
+for instance replaces it with the empty string. OpenBSD (3.0 and
+later) @command{make} diagnoses these uses and errors out.
+
+ at node Failure in Make Rules
+ at section Failure in Make Rules
+
+Posix 2008 requires that @command{make} must invoke each command with
+the equivalent of a @samp{sh -e -c} subshell, which causes the
+subshell to exit immediately if a subsidiary simple-command fails,
+although not all @command{make} implementations have historically
+followed this rule. For
+example, the command @samp{touch T; rm -f U} may attempt to
+remove @file{U} even if the @command{touch} fails, although this is not
+permitted with Posix make. One way to work around failures in simple
+commands is to reword them so that they always succeed, e.g., @samp{touch
+T || :; rm -f U}.
+However, even this approach can run into common bugs in BSD
+implementations of the @option{-e} option of @command{sh} and
+ at command{set} (@pxref{set, , Limitations of Shell Builtins}), so if you
+are worried
+about porting to buggy BSD shells it may be simpler to migrate
+complicated @command{make} actions into separate scripts.
+
+ at node Special Chars in Names
+ at section Special Characters in Make Macro Names
+
+Posix limits macro names to nonempty strings containing only
+ASCII letters and digits, @samp{.}, and @samp{_}. Many
+ at command{make} implementations allow a wider variety of characters, but
+portable makefiles should avoid them. It is portable to start a name
+with a special character, e.g., @samp{$(.FOO)}.
+
+Some ancient @command{make} implementations don't support leading
+underscores in macro names. An example is NEWS-OS 4.2R.
+
+ at example
+$ @kbd{cat Makefile}
+_am_include = #
+_am_quote =
+all:; @@echo this is test
+$ @kbd{make}
+Make: Must be a separator on rules line 2. Stop.
+$ @kbd{cat Makefile2}
+am_include = #
+am_quote =
+all:; @@echo this is test
+$ @kbd{make -f Makefile2}
+this is test
+ at end example
+
+ at noindent
+However, this problem is no longer of practical concern.
+
+ at node Backslash-Newline-Empty
+ at section Backslash-Newline Before Empty Lines
+
+A bug in Bash 2.03 can cause problems if a Make rule contains a
+backslash-newline followed by line that expands to nothing.
+For example, on Solaris 8:
+
+ at example
+SHELL = /bin/bash
+EMPTY =
+foo:
+ touch foo \
+ $(EMPTY)
+ at end example
+
+ at noindent
+executes
+
+ at example
+/bin/bash -c 'touch foo \
+'
+ at end example
+
+ at noindent
+which fails with a syntax error, due to the Bash bug. To avoid this
+problem, avoid nullable macros in the last line of a multiline command.
+
+ at c This has been seen on ia64 hpux 11.20, and on one hppa hpux 10.20,
+ at c but another hppa hpux 10.20 didn't have it. Bob Proulx
+ at c <bob at proulx.com> thinks it was in hpux 8.0 too.
+On some versions of HP-UX, @command{make} reads multiple newlines
+following a backslash, continuing to the next non-empty line. For
+example,
+
+ at example
+FOO = one \
+
+BAR = two
+
+test:
+ : FOO is "$(FOO)"
+ : BAR is "$(BAR)"
+ at end example
+
+ at noindent
+shows @code{FOO} equal to @code{one BAR = two}. Other implementations
+sensibly let a backslash continue only to the immediately following
+line.
+
+ at node Backslash-Newline Comments
+ at section Backslash-Newline in Make Comments
+
+According to Posix, Make comments start with @code{#}
+and continue until an unescaped newline is reached.
+
+ at example
+$ @kbd{cat Makefile}
+# A = foo \
+ bar \
+ baz
+
+all:
+ @@echo ok
+$ @kbd{make} # GNU make
+ok
+ at end example
+
+ at noindent
+However this is not always the case. Some implementations
+discard everything from @code{#} through the end of the line, ignoring any
+trailing backslash.
+
+ at example
+$ @kbd{pmake} # BSD make
+"Makefile", line 3: Need an operator
+Fatal errors encountered -- cannot continue
+ at end example
+
+ at noindent
+Therefore, if you want to comment out a multi-line definition, prefix each
+line with @code{#}, not only the first.
+
+ at example
+# A = foo \
+# bar \
+# baz
+ at end example
+
+ at node Long Lines in Makefiles
+ at section Long Lines in Makefiles
+
+Tru64 5.1's @command{make} has been reported to crash when given a
+makefile with lines longer than around 20 kB. Earlier versions are
+reported to exit with @code{Line too long} diagnostics.
+
+ at node Macros and Submakes
+ at section @code{make macro=value} and Submakes
+
+A command-line variable definition such as @code{foo=bar} overrides any
+definition of @code{foo} in a makefile. Some @command{make}
+implementations (such as GNU @command{make}) propagate this
+override to subsidiary invocations of @command{make}. Some other
+implementations do not pass the substitution along to submakes.
+
+ at example
+$ @kbd{cat Makefile}
+foo = foo
+one:
+ @@echo $(foo)
+ $(MAKE) two
+two:
+ @@echo $(foo)
+$ @kbd{make foo=bar} # GNU make 3.79.1
+bar
+make two
+make[1]: Entering directory `/home/adl'
+bar
+make[1]: Leaving directory `/home/adl'
+$ @kbd{pmake foo=bar} # BSD make
+bar
+pmake two
+foo
+ at end example
+
+You have a few possibilities if you do want the @code{foo=bar} override
+to propagate to submakes. One is to use the @option{-e}
+option, which causes all environment variables to have precedence over
+the makefile macro definitions, and declare foo as an environment
+variable:
+
+ at example
+$ @kbd{env foo=bar make -e}
+ at end example
+
+The @option{-e} option is propagated to submakes automatically,
+and since the environment is inherited between @command{make}
+invocations, the @code{foo} macro is overridden in
+submakes as expected.
+
+This syntax (@code{foo=bar make -e}) is portable only when used
+outside of a makefile, for instance from a script or from the
+command line. When run inside a @command{make} rule, GNU
+ at command{make} 3.80 and prior versions forget to propagate the
+ at option{-e} option to submakes.
+
+Moreover, using @option{-e} could have unexpected side effects if your
+environment contains some other macros usually defined by the
+makefile. (See also the note about @code{make -e} and @code{SHELL}
+below.)
+
+If you can foresee all macros that a user might want to override, then
+you can propagate them to submakes manually, from your makefile:
+
+ at example
+foo = foo
+one:
+ @@echo $(foo)
+ $(MAKE) foo=$(foo) two
+two:
+ @@echo $(foo)
+ at end example
+
+Another way to propagate a variable to submakes in a portable way is to
+expand an extra variable in every invocation of @samp{$(MAKE)} within
+your makefile:
+
+ at example
+foo = foo
+one:
+ @@echo $(foo)
+ $(MAKE) $(SUBMAKEFLAGS) two
+two:
+ @@echo $(foo)
+ at end example
+
+Users must be aware that this technique is in use to take advantage of
+it, e.g.@: with @code{make foo=bar SUBMAKEFLAGS='foo=bar'}, but it
+allows any macro to be overridden. Makefiles generated by
+ at command{automake} use this technique, expanding @code{$(AM_MAKEFLAGS)}
+on the command lines of submakes (@pxref{Subdirectories, , Automake,
+automake, GNU Automake}).
+
+ at node The Make Macro MAKEFLAGS
+ at section The Make Macro MAKEFLAGS
+ at cindex @code{MAKEFLAGS} and @command{make}
+ at cindex @command{make} and @code{MAKEFLAGS}
+
+Posix requires @command{make} to use @code{MAKEFLAGS} to affect the
+current and recursive invocations of make, but allows implementations
+several formats for the variable. It is tricky to parse
+ at code{$MAKEFLAGS} to determine whether @option{-s} for silent execution
+or @option{-k} for continued execution are in effect. For example, you
+cannot assume that the first space-separated word in @code{$MAKEFLAGS}
+contains single-letter options, since in the Cygwin version of
+GNU @command{make} it is either @option{--unix} or
+ at option{--win32} with the second word containing single-letter options.
+
+ at example
+$ @kbd{cat Makefile}
+all:
+ @@echo MAKEFLAGS = $(MAKEFLAGS)
+$ @kbd{make}
+MAKEFLAGS = --unix
+$ @kbd{make -k}
+MAKEFLAGS = --unix -k
+ at end example
+
+ at node The Make Macro SHELL
+ at section The Make Macro @code{SHELL}
+ at cindex @code{SHELL} and @command{make}
+ at cindex @command{make} and @code{SHELL}
+
+Posix-compliant @command{make} internally uses the @code{$(SHELL)}
+macro to spawn shell processes and execute Make rules. This
+is a builtin macro supplied by @command{make}, but it can be modified
+by a makefile or by a command-line argument.
+
+Not all @command{make} implementations define this @code{SHELL} macro.
+Tru64
+ at command{make} is an example; this implementation always uses
+ at code{/bin/sh}. So it's a good idea to always define @code{SHELL} in
+your makefiles. If you use Autoconf, do
+
+ at example
+SHELL = @@SHELL@@
+ at end example
+
+ at noindent
+If you use Automake, this is done for you.
+
+Do not force @code{SHELL = /bin/sh} because that is not correct
+everywhere. Remember, @file{/bin/sh} is not Posix compliant on many
+systems, such as FreeBSD 4, NetBSD 3, AIX 3, Solaris 10, or Tru64.
+Additionally, DJGPP lacks @code{/bin/sh}, and when its
+GNU @command{make} port sees such a setting it enters a
+special emulation mode where features like pipes and redirections are
+emulated on top of DOS's @command{command.com}. Unfortunately this
+emulation is incomplete; for instance it does not handle command
+substitutions. Using @code{@@SHELL@@} means that your makefile will
+benefit from the same improved shell, such as @command{bash} or
+ at command{ksh}, that was discovered during @command{configure}, so that
+you aren't fighting two different sets of shell bugs between the two
+contexts.
+
+Posix-compliant @command{make} should never acquire the value of
+$(SHELL) from the environment, even when @code{make -e} is used
+(otherwise, think about what would happen to your rules if
+ at code{SHELL=/bin/tcsh}).
+
+However not all @command{make} implementations have this exception.
+For instance it's not surprising that Tru64 @command{make} doesn't
+protect @code{SHELL}, since it doesn't use it.
+
+ at example
+$ @kbd{cat Makefile}
+SHELL = /bin/sh
+FOO = foo
+all:
+ @@echo $(SHELL)
+ @@echo $(FOO)
+$ @kbd{env SHELL=/bin/tcsh FOO=bar make -e} # Tru64 Make
+/bin/tcsh
+bar
+$ @kbd{env SHELL=/bin/tcsh FOO=bar gmake -e} # GNU make
+/bin/sh
+bar
+ at end example
+
+Conversely, @command{make} is not supposed to export any changes to the
+macro @code{SHELL} to child processes. Again, many implementations
+break this rule:
+
+ at example
+$ @kbd{cat Makefile}
+all:
+ @@echo $(SHELL)
+ @@printenv SHELL
+$ @kbd{env SHELL=sh make -e SHELL=/bin/ksh} # BSD Make, GNU make 3.80
+/bin/ksh
+/bin/ksh
+$ @kbd{env SHELL=sh gmake -e SHELL=/bin/ksh} # GNU make 3.81
+/bin/ksh
+sh
+ at end example
+
+ at node Parallel Make
+ at section Parallel Make
+ at cindex Parallel @command{make}
+
+Support for parallel execution in @command{make} implementation varies.
+Generally, using GNU make is your best bet.
+
+When NetBSD or FreeBSD @command{make} are run in parallel mode, they will
+reuse the same shell for multiple commands within one recipe. This can
+have various unexpected consequences. For example, changes of directories
+or variables persist between recipes, so that:
+
+ at example
+all:
+ @@var=value; cd /; pwd; echo $$var; echo $$$$
+ @@pwd; echo $$var; echo $$$$
+ at end example
+
+ at noindent
+may output the following with @code{make -j1}, at least on NetBSD up to
+5.1 and FreeBSD up to 8.2:
+
+ at example
+/
+value
+32235
+/
+value
+32235
+ at end example
+
+ at noindent
+while without @option{-j1}, or with @option{-B}, the output looks less
+surprising:
+
+ at example
+/
+value
+32238
+/tmp
+
+32239
+ at end example
+
+ at noindent
+Another consequence is that, if one command in a recipe uses @code{exit 0}
+to indicate a successful exit, the shell will be gone and the remaining
+commands of this recipe will not be executed.
+
+The BSD @command{make} implementations, when run in parallel mode,
+will also pass the @command{Makefile} recipes to the shell through
+its standard input, thus making it unusable from the recipes:
+
+ at example
+$ @kbd{cat Makefile}
+read:
+ @@read line; echo LINE: $$line
+ at c $$ @c restore font-lock
+$ @kbd{echo foo | make read}
+LINE: foo
+$ @kbd{echo foo | make -j1 read} # NetBSD 5.1 and FreeBSD 8.2
+LINE:
+ at end example
+
+ at noindent
+Moreover, when FreeBSD @command{make} (up at least to 8.2) is run in
+parallel mode, it implements the @code{@@} and @code{-} ``recipe
+modifiers'' by dynamically modifying the active shell flags. This
+behavior has the effects of potentially clobbering the exit status
+of recipes silenced with the @code{@@} modifier if they also unset
+the @option{errexit} shell flag, and of mangling the output in
+unexpected ways:
+
+ at example
+$ @kbd{cat Makefile}
+a:
+ @@echo $$-; set +e; false
+b:
+ -echo $$-; false; echo set -
+$ @kbd{make a; echo status: $?}
+ehBc
+*** Error code 1
+status: 1
+$ @kbd{make -j1 a; echo status: $?}
+ehB
+status: 0
+$ @kbd{make b}
+echo $-; echo set -
+hBc
+set -
+$ @kbd{make -j1 b}
+echo $-; echo hvB
+ at end example
+
+ at noindent
+You can avoid all these issues by using the @option{-B} option to enable
+compatibility semantics. However, that will effectively also disable
+all parallelism as that will cause prerequisites to be updated in the
+order they are listed in a rule.
+
+Some make implementations (among them, FreeBSD @command{make}, NetBSD
+ at command{make}, and Solaris @command{dmake}), when invoked with a
+ at option{-j at var{N}} option, connect the standard output and standard
+error of all their child processes to pipes or temporary regular
+files. This can lead to subtly different semantics in the behavior
+of the spawned processes. For example, even if the @command{make}
+standard output is connected to a tty, the recipe command will not be:
+
+ at example
+$ @kbd{cat Makefile}
+all:
+ @@test -t 1 && echo "Is a tty" || echo "Is not a tty"
+$ @kbd{make -j 2} # FreeBSD 8.2 make
+Is not a tty
+$ @kbd{make -j 2} # NetBSD 5.1 make
+--- all ---
+Is not a tty
+$ @kbd{dmake -j 2} # Solaris 10 dmake
+ at var{hostname} --> 1 job
+ at var{hostname} --> Job output
+Is not a tty
+ at end example
+
+ at noindent
+On the other hand:
+
+ at example
+$ @kbd{make -j 2} # GNU make, Heirloom make
+Is a tty
+ at end example
+
+ at noindent
+The above examples also show additional status output produced in parallel
+mode for targets being updated by Solaris @command{dmake} and NetBSD
+ at command{make} (but @emph{not} by FreeBSD @command{make}).
+
+Furthermore, parallel runs of those @command{make} implementations will
+route standard error from commands that they spawn into their own
+standard output, and may remove leading whitespace from output lines.
+
+
+ at node Comments in Make Rules
+ at section Comments in Make Rules
+ at cindex Comments in @file{Makefile} rules
+ at cindex @file{Makefile} rules and comments
+
+Never put comments in a rule.
+
+Some @command{make} treat anything starting with a tab as a command for
+the current rule, even if the tab is immediately followed by a @code{#}.
+The @command{make} from Tru64 Unix V5.1 is one of them. The following
+makefile runs @code{# foo} through the shell.
+
+ at example
+all:
+ # foo
+ at end example
+
+As a workaround, you can use the @command{:} no-op command with a string
+argument that gets ignored:
+
+ at example
+all:
+ : "foo"
+ at end example
+
+Conversely, if you want to use the @samp{#} character in some command,
+you can only do so by expanding it inside a rule (@pxref{Comments in
+Make Macros}). So for example, if @samp{COMMENT_CHAR} is substituted by
+ at command{config.status} as @samp{#}, then the following substitutes
+ at samp{@@COMMENT_CHAR@@} in a generated header:
+
+ at example
+foo.h: foo.h.in
+ sed -e 's|@@''COMMENT_CHAR''@@|@@COMMENT_CHAR@@|g' \
+ $(srcdir)/foo.h.in > $@@
+ at end example
+
+The funny shell quoting avoids a substitution at @command{config.status}
+run time of the left-hand side of the @command{sed} @samp{s} command.
+
+ at node Newlines in Make Rules
+ at section Newlines in Make Rules
+ at cindex Newlines in @file{Makefile} rules
+ at cindex @file{Makefile} rules and newlines
+
+In shell scripts, newlines can be used inside string literals. But in
+the shell statements of @file{Makefile} rules, this is not possible:
+A newline not preceded by a backslash is a separator between shell
+statements. Whereas a newline that is preceded by a backslash becomes
+part of the shell statement according to POSIX, but gets replaced,
+together with the backslash that precedes it, by a space in GNU
+ at command{make} 3.80 and older. So, how can a newline be used in a string
+literal?
+
+The trick is to set up a shell variable that contains a newline:
+
+ at example
+nlinit=`echo 'nl="'; echo '"'`; eval "$$nlinit"
+ at end example
+
+For example, in order to create a multiline @samp{sed} expression that
+inserts a blank line after every line of a file, this code can be used:
+
+ at example
+nlinit=`echo 'nl="'; echo '"'`; eval "$$nlinit"; \
+sed -e "s/\$$/\\$$@{nl@}/" < input > output
+ at end example
+
+ at node Comments in Make Macros
+ at section Comments in Make Macros
+ at cindex Comments in @file{Makefile} macros
+ at cindex @file{Makefile} macros and comments
+
+Avoid putting comments in macro values as far as possible. Posix
+specifies that the text starting from the @samp{#} sign until the end of
+the line is to be ignored, which has the unfortunate effect of
+disallowing them even within quotes. Thus, the following might lead to
+a syntax error at compile time:
+
+ at example
+CPPFLAGS = "-DCOMMENT_CHAR='#'"
+ at end example
+
+ at noindent
+as @samp{CPPFLAGS} may be expanded to @samp{"-DCOMMENT_CHAR='}.
+
+Most @command{make} implementations disregard this and treat single and
+double quotes specially here. Also, GNU @command{make} lets you put
+ at samp{#} into a macro value by escaping it with a backslash, i.e.,
+ at samp{\#}. However, neither of these usages are portable.
+ at xref{Comments in Make Rules}, for a portable alternative.
+
+Even without quoting involved, comments can have surprising effects,
+because the whitespace before them is part of the variable value:
+
+ at example
+foo = bar # trailing comment
+print: ; @@echo "$(foo)."
+ at end example
+
+ at noindent
+prints @samp{bar .}, which is usually not intended, and can expose
+ at command{make} bugs as described below.
+
+ at node Trailing whitespace in Make Macros
+ at section Trailing whitespace in Make Macros
+ at cindex whitespace in @file{Makefile} macros
+ at cindex @file{Makefile} macros and whitespace
+
+GNU @command{make} 3.80 mistreats trailing whitespace in macro
+substitutions and appends another spurious suffix:
+
+ at example
+empty =
+foo = bar $(empty)
+print: ; @@echo $(foo:=.test)
+ at end example
+
+ at noindent
+prints @samp{bar.test .test}.
+
+BSD and Solaris @command{make} implementations do not honor trailing
+whitespace in macro definitions as Posix requires:
+
+ at example
+foo = bar # Note the space after "bar".
+print: ; @@echo $(foo)t
+ at end example
+
+ at noindent
+prints @samp{bart} instead of @samp{bar t}. To work around this, you
+can use a helper macro as in the previous example.
+
+
+ at node Command-line Macros and whitespace
+ at section Command-line Macros and whitespace
+ at cindex whitespace in command-line macros
+ at cindex command-line, macros set on
+ at cindex environment, macros set from
+
+Some @command{make} implementations may strip trailing whitespace off
+of macros set on the command line in addition to leading whitespace.
+Further, some may strip leading whitespace off of macros set from
+environment variables:
+
+ at example
+$ @kbd{echo 'print: ; @@echo "x$(foo)x$(bar)x"' |
+ foo=' f f ' make -f - bar=' b b '}
+x f f xb b x # AIX, BSD, GNU make
+xf f xb b x # HP-UX, IRIX, Tru64/OSF make
+x f f xb bx # Solaris make
+ at end example
+
+
+ at node obj/ and Make
+ at section The @file{obj/} Subdirectory and Make
+ at cindex @file{obj/}, subdirectory
+ at cindex BSD @command{make} and @file{obj/}
+
+Never name one of your subdirectories @file{obj/} if you don't like
+surprises.
+
+If an @file{obj/} directory exists, BSD @command{make} enters it
+before reading the makefile. Hence the makefile in the
+current directory is not read.
+
+ at example
+$ @kbd{cat Makefile}
+all:
+ echo Hello
+$ @kbd{cat obj/Makefile}
+all:
+ echo World
+$ @kbd{make} # GNU make
+echo Hello
+Hello
+$ @kbd{pmake} # BSD make
+echo World
+World
+ at end example
+
+ at node make -k Status
+ at section Exit Status of @code{make -k}
+ at cindex @code{make -k}
+
+Do not rely on the exit status of @code{make -k}. Some implementations
+reflect whether they encountered an error in their exit status; other
+implementations always succeed.
+
+ at example
+$ @kbd{cat Makefile}
+all:
+ false
+$ @kbd{make -k; echo exit status: $?} # GNU make
+false
+make: *** [all] Error 1
+exit status: 2
+$ @kbd{pmake -k; echo exit status: $?} # BSD make
+false
+*** Error code 1 (continuing)
+exit status: 0
+ at end example
+
+ at node VPATH and Make
+ at section @code{VPATH} and Make
+ at cindex @code{VPATH}
+
+Posix does not specify the semantics of @code{VPATH}. Typically,
+ at command{make} supports @code{VPATH}, but its implementation is not
+consistent.
+
+Autoconf and Automake support makefiles whose usages of @code{VPATH} are
+portable to recent-enough popular implementations of @command{make}, but
+to keep the resulting makefiles portable, a package's makefile
+prototypes must take the following issues into account. These issues
+are complicated and are often poorly understood, and installers who use
+ at code{VPATH} should expect to find many bugs in this area. If you use
+ at code{VPATH}, the simplest way to avoid these portability bugs is to
+stick with GNU @command{make}, since it is the most
+commonly-used @command{make} among Autoconf users.
+
+Here are some known issues with some @code{VPATH}
+implementations.
+
+ at menu
+* Variables listed in VPATH:: @code{VPATH} must be literal on ancient hosts
+* VPATH and Double-colon:: Problems with @samp{::} on ancient hosts
+* $< in Explicit Rules:: @code{$<} does not work in ordinary rules
+* Automatic Rule Rewriting:: @code{VPATH} goes wild on Solaris
+* Tru64 Directory Magic:: @command{mkdir} goes wild on Tru64
+* Make Target Lookup:: More details about @code{VPATH} lookup
+ at end menu
+
+ at node Variables listed in VPATH
+ at subsection Variables listed in @code{VPATH}
+ at cindex @code{VPATH} and variables
+ at cindex variables and @code{VPATH}
+
+Do not set @code{VPATH} to the value of another variable, for example
+ at samp{VPATH = $(srcdir)}, because some ancient versions of
+ at command{make} do not do variable substitutions on the value of
+ at code{VPATH}. For example, use this
+
+ at example
+srcdir = @@srcdir@@
+VPATH = @@srcdir@@
+ at end example
+
+ at noindent
+rather than @samp{VPATH = $(srcdir)}. Note that with GNU
+Automake, there is no need to set this yourself.
+
+ at node VPATH and Double-colon
+ at subsection @code{VPATH} and Double-colon Rules
+ at cindex @code{VPATH} and double-colon rules
+ at cindex double-colon rules and @code{VPATH}
+
+With ancient versions of Sun @command{make},
+any assignment to @code{VPATH} causes @command{make} to execute only
+the first set of double-colon rules.
+However, this problem is no longer of practical concern.
+
+ at node $< in Explicit Rules
+ at subsection @code{$<} Not Supported in Explicit Rules
+ at cindex explicit rules, @code{$<}, and @code{VPATH}
+ at cindex @code{$<}, explicit rules, and @code{VPATH}
+ at cindex @code{VPATH}, explicit rules, and @code{$<}
+
+Using @code{$<} in explicit rules is not portable.
+The prerequisite file must be named explicitly in the rule. If you want
+to find the prerequisite via a @code{VPATH} search, you have to code the
+whole thing manually. @xref{Build Directories}.
+
+ at node Automatic Rule Rewriting
+ at subsection Automatic Rule Rewriting
+ at cindex @code{VPATH} and automatic rule rewriting
+ at cindex automatic rule rewriting and @code{VPATH}
+
+Some @command{make} implementations, such as Solaris and Tru64,
+search for prerequisites in @code{VPATH} and
+then rewrite each occurrence as a plain word in the rule.
+For instance:
+
+ at example
+# This isn't portable to GNU make.
+VPATH = ../pkg/src
+f.c: if.c
+ cp if.c f.c
+ at end example
+
+ at noindent
+executes @code{cp ../pkg/src/if.c f.c} if @file{if.c} is
+found in @file{../pkg/src}.
+
+However, this rule leads to real problems in practice. For example, if
+the source directory contains an ordinary file named @file{test} that is
+used in a dependency, Solaris @command{make} rewrites commands like
+ at samp{if test -r foo; @dots{}} to @samp{if ../pkg/src/test -r foo;
+ at dots{}}, which is typically undesirable. In fact, @command{make} is
+completely unaware of shell syntax used in the rules, so the VPATH
+rewrite can potentially apply to @emph{any} whitespace-separated word
+in a rule, including shell variables, functions, and keywords.
+
+ at example
+$ @kbd{mkdir build}
+$ @kbd{cd build}
+$ @kbd{cat > Makefile <<'END'}
+VPATH = ..
+all: arg func for echo
+ func () @{ for arg in "$$@@"; do echo $$arg; done; @}; \
+ func "hello world"
+END
+$ @kbd{touch ../arg ../func ../for ../echo}
+$ @kbd{make}
+../func () @{ ../for ../arg in "$@@"; do ../echo $arg; done; @}; \
+../func "hello world"
+sh: syntax error at line 1: `do' unexpected
+*** Error code 2
+ at end example
+
+ at noindent
+To avoid this problem, portable makefiles should never mention a source
+file or dependency whose name is that of a shell keyword like @file{for}
+or @file{until}, a shell command like @command{cat} or @command{gcc} or
+ at command{test}, or a shell function or variable used in the corresponding
+ at command{Makefile} recipe.
+
+Because of these problems GNU @command{make} and many other @command{make}
+implementations do not rewrite commands, so portable makefiles should
+search @code{VPATH} manually. It is tempting to write this:
+
+ at smallexample
+# This isn't portable to Solaris make.
+VPATH = ../pkg/src
+f.c: if.c
+ cp `test -f if.c || echo $(VPATH)/`if.c f.c
+ at end smallexample
+
+ at noindent
+However, the ``prerequisite rewriting'' still applies here. So if
+ at file{if.c} is in @file{../pkg/src}, Solaris and Tru64 @command{make}
+execute
+
+ at smallexample
+cp `test -f ../pkg/src/if.c || echo ../pkg/src/`if.c f.c
+ at end smallexample
+
+ at noindent
+which reduces to
+
+ at example
+cp if.c f.c
+ at end example
+
+ at noindent
+and thus fails. Oops.
+
+A simple workaround, and good practice anyway, is to use @samp{$?} and
+ at samp{$@@} when possible:
+
+ at smallexample
+VPATH = ../pkg/src
+f.c: if.c
+ cp $? $@@
+ at end smallexample
+
+ at noindent
+but this does not generalize well to commands with multiple
+prerequisites. A more general workaround is to rewrite the rule so that
+the prerequisite @file{if.c} never appears as a plain word. For
+example, these three rules would be safe, assuming @file{if.c} is in
+ at file{../pkg/src} and the other files are in the working directory:
+
+ at smallexample
+VPATH = ../pkg/src
+f.c: if.c f1.c
+ cat `test -f ./if.c || echo $(VPATH)/`if.c f1.c >$@@
+g.c: if.c g1.c
+ cat `test -f 'if.c' || echo $(VPATH)/`if.c g1.c >$@@
+h.c: if.c h1.c
+ cat `test -f "if.c" || echo $(VPATH)/`if.c h1.c >$@@
+ at end smallexample
+
+Things get worse when your prerequisites are in a macro.
+
+ at example
+VPATH = ../pkg/src
+HEADERS = f.h g.h h.h
+install-HEADERS: $(HEADERS)
+ for i in $(HEADERS); do \
+ $(INSTALL) -m 644 \
+ `test -f $$i || echo $(VPATH)/`$$i \
+ $(DESTDIR)$(includedir)/$$i; \
+ at c $$ restore font-lock
+ done
+ at end example
+
+The above @code{install-HEADERS} rule is not Solaris-proof because @code{for
+i in $(HEADERS);} is expanded to @code{for i in f.h g.h h.h;}
+where @code{f.h} and @code{g.h} are plain words and are hence
+subject to @code{VPATH} adjustments.
+
+If the three files are in @file{../pkg/src}, the rule is run as:
+
+ at example
+for i in ../pkg/src/f.h ../pkg/src/g.h h.h; do \
+ install -m 644 \
+ `test -f $i || echo ../pkg/src/`$i \
+ /usr/local/include/$i; \
+done
+ at end example
+
+where the two first @command{install} calls fail. For instance,
+consider the @code{f.h} installation:
+
+ at example
+install -m 644 \
+ `test -f ../pkg/src/f.h || \
+ echo ../pkg/src/ \
+ `../pkg/src/f.h \
+ /usr/local/include/../pkg/src/f.h;
+ at end example
+
+ at noindent
+It reduces to:
+
+ at example
+install -m 644 \
+ ../pkg/src/f.h \
+ /usr/local/include/../pkg/src/f.h;
+ at end example
+
+Note that the manual @code{VPATH} search did not cause any problems here;
+however this command installs @file{f.h} in an incorrect directory.
+
+Trying to quote @code{$(HEADERS)} in some way, as we did for
+ at code{foo.c} a few makefiles ago, does not help:
+
+ at example
+install-HEADERS: $(HEADERS)
+ headers='$(HEADERS)'; \
+ for i in $$headers; do \
+ $(INSTALL) -m 644 \
+ `test -f $$i || echo $(VPATH)/`$$i \
+ $(DESTDIR)$(includedir)/$$i; \
+ done
+ at end example
+
+Now, @code{headers='$(HEADERS)'} macro-expands to:
+
+ at example
+headers='f.h g.h h.h'
+ at end example
+
+ at noindent
+but @code{g.h} is still a plain word. (As an aside, the idiom
+ at code{headers='$(HEADERS)'; for i in $$headers;} is a good
+idea if @code{$(HEADERS)} can be empty, because some shells diagnose a
+syntax error on @code{for i in;}.)
+
+One workaround is to strip this unwanted @file{../pkg/src/} prefix manually:
+
+ at example
+VPATH = ../pkg/src
+HEADERS = f.h g.h h.h
+install-HEADERS: $(HEADERS)
+ headers='$(HEADERS)'; \
+ for i in $$headers; do \
+ i=`expr "$$i" : '$(VPATH)/\(.*\)'`;
+ $(INSTALL) -m 644 \
+ `test -f $$i || echo $(VPATH)/`$$i \
+ $(DESTDIR)$(includedir)/$$i; \
+ at c $$ restore font-lock
+ done
+ at end example
+
+Automake does something similar. However the above hack works only if
+the files listed in @code{HEADERS} are in the current directory or a
+subdirectory; they should not be in an enclosing directory. If we had
+ at code{HEADERS = ../f.h}, the above fragment would fail in a VPATH
+build with Tru64 @command{make}. The reason is that not only does
+Tru64 @command{make} rewrite dependencies, but it also simplifies
+them. Hence @code{../f.h} becomes @code{../pkg/f.h} instead of
+ at code{../pkg/src/../f.h}. This obviously defeats any attempt to strip
+a leading @file{../pkg/src/} component.
+
+The following example makes the behavior of Tru64 @command{make}
+more apparent.
+
+ at example
+$ @kbd{cat Makefile}
+VPATH = sub
+all: ../foo
+ echo ../foo
+$ @kbd{ls}
+Makefile foo
+$ @kbd{make}
+echo foo
+foo
+ at end example
+
+ at noindent
+Dependency @file{../foo} was found in @file{sub/../foo}, but Tru64
+ at command{make} simplified it as @file{foo}. (Note that the @file{sub/}
+directory does not even exist, this just means that the simplification
+occurred before the file was checked for.)
+
+For the record here is how SunOS 4 @command{make} behaves on this
+example.
+
+ at smallexample
+$ @kbd{make}
+make: Fatal error: Don't know how to make target `../foo'
+$ @kbd{mkdir sub}
+$ @kbd{make}
+echo sub/../foo
+sub/../foo
+ at end smallexample
+
+
+ at node Tru64 Directory Magic
+ at subsection Tru64 @command{make} Creates Prerequisite Directories Magically
+ at cindex @code{VPATH} and prerequisite directories
+ at cindex prerequisite directories and @code{VPATH}
+
+When a prerequisite is a subdirectory of @code{VPATH}, Tru64
+ at command{make} creates it in the current directory.
+
+ at example
+$ @kbd{mkdir -p foo/bar build}
+$ @kbd{cd build}
+$ @kbd{cat >Makefile <<END
+VPATH = ..
+all: foo/bar
+END}
+$ @kbd{make}
+mkdir foo
+mkdir foo/bar
+ at end example
+
+This can yield unexpected results if a rule uses a manual @code{VPATH}
+search as presented before.
+
+ at example
+VPATH = ..
+all : foo/bar
+ command `test -d foo/bar || echo ../`foo/bar
+ at end example
+
+The above @command{command} is run on the empty @file{foo/bar}
+directory that was created in the current directory.
+
+ at node Make Target Lookup
+ at subsection Make Target Lookup
+ at cindex @code{VPATH}, resolving target pathnames
+
+GNU @command{make} uses a complex algorithm to decide when it
+should use files found via a @code{VPATH} search. @xref{Search
+Algorithm, , How Directory Searches are Performed, make, The GNU Make
+Manual}.
+
+If a target needs to be rebuilt, GNU @command{make} discards the
+file name found during the @code{VPATH} search for this target, and
+builds the file locally using the file name given in the makefile.
+If a target does not need to be rebuilt, GNU @command{make} uses the
+file name found during the @code{VPATH} search.
+
+Other @command{make} implementations, like NetBSD @command{make}, are
+easier to describe: the file name found during the @code{VPATH} search
+is used whether the target needs to be rebuilt or not. Therefore
+new files are created locally, but existing files are updated at their
+ at code{VPATH} location.
+
+OpenBSD and FreeBSD @command{make}, however,
+never perform a
+ at code{VPATH} search for a dependency that has an explicit rule.
+This is extremely annoying.
+
+When attempting a @code{VPATH} build for an autoconfiscated package
+(e.g., @code{mkdir build && cd build && ../configure}), this means
+GNU
+ at command{make} builds everything locally in the @file{build}
+directory, while BSD @command{make} builds new files locally and
+updates existing files in the source directory.
+
+ at example
+$ @kbd{cat Makefile}
+VPATH = ..
+all: foo.x bar.x
+foo.x bar.x: newer.x
+ @@echo Building $@@
+$ @kbd{touch ../bar.x}
+$ @kbd{touch ../newer.x}
+$ @kbd{make} # GNU make
+Building foo.x
+Building bar.x
+$ @kbd{pmake} # NetBSD make
+Building foo.x
+Building ../bar.x
+$ @kbd{fmake} # FreeBSD make, OpenBSD make
+Building foo.x
+Building bar.x
+$ @kbd{tmake} # Tru64 make
+Building foo.x
+Building bar.x
+$ @kbd{touch ../bar.x}
+$ @kbd{make} # GNU make
+Building foo.x
+$ @kbd{pmake} # NetBSD make
+Building foo.x
+$ @kbd{fmake} # FreeBSD make, OpenBSD make
+Building foo.x
+Building bar.x
+$ @kbd{tmake} # Tru64 make
+Building foo.x
+Building bar.x
+ at end example
+
+Note how NetBSD @command{make} updates @file{../bar.x} in its
+VPATH location, and how FreeBSD, OpenBSD, and Tru64
+ at command{make} always
+update @file{bar.x}, even when @file{../bar.x} is up to date.
+
+Another point worth mentioning is that once GNU @command{make} has
+decided to ignore a @code{VPATH} file name (e.g., it ignored
+ at file{../bar.x} in the above example) it continues to ignore it when
+the target occurs as a prerequisite of another rule.
+
+The following example shows that GNU @command{make} does not look up
+ at file{bar.x} in @code{VPATH} before performing the @code{.x.y} rule,
+because it ignored the @code{VPATH} result of @file{bar.x} while running
+the @code{bar.x: newer.x} rule.
+
+ at example
+$ @kbd{cat Makefile}
+VPATH = ..
+all: bar.y
+bar.x: newer.x
+ @@echo Building $@@
+.SUFFIXES: .x .y
+.x.y:
+ cp $< $@@
+$ @kbd{touch ../bar.x}
+$ @kbd{touch ../newer.x}
+$ @kbd{make} # GNU make
+Building bar.x
+cp bar.x bar.y
+cp: cannot stat `bar.x': No such file or directory
+make: *** [bar.y] Error 1
+$ @kbd{pmake} # NetBSD make
+Building ../bar.x
+cp ../bar.x bar.y
+$ @kbd{rm bar.y}
+$ @kbd{fmake} # FreeBSD make, OpenBSD make
+echo Building bar.x
+cp bar.x bar.y
+cp: cannot stat `bar.x': No such file or directory
+*** Error code 1
+$ @kbd{tmake} # Tru64 make
+Building bar.x
+cp: bar.x: No such file or directory
+*** Exit 1
+ at end example
+
+Note that if you drop away the command from the @code{bar.x: newer.x}
+rule, GNU @command{make} magically starts to work: it
+knows that @code{bar.x} hasn't been updated, therefore it doesn't
+discard the result from @code{VPATH} (@file{../bar.x}) in succeeding
+uses. Tru64 also works, but FreeBSD and OpenBSD
+still don't.
+
+ at example
+$ @kbd{cat Makefile}
+VPATH = ..
+all: bar.y
+bar.x: newer.x
+.SUFFIXES: .x .y
+.x.y:
+ cp $< $@@
+$ @kbd{touch ../bar.x}
+$ @kbd{touch ../newer.x}
+$ @kbd{make} # GNU make
+cp ../bar.x bar.y
+$ @kbd{rm bar.y}
+$ @kbd{pmake} # NetBSD make
+cp ../bar.x bar.y
+$ @kbd{rm bar.y}
+$ @kbd{fmake} # FreeBSD make, OpenBSD make
+cp bar.x bar.y
+cp: cannot stat `bar.x': No such file or directory
+*** Error code 1
+$ @kbd{tmake} # Tru64 make
+cp ../bar.x bar.y
+ at end example
+
+It seems the sole solution that would please every @command{make}
+implementation is to never rely on @code{VPATH} searches for targets.
+In other words, @code{VPATH} should be reserved to unbuilt sources.
+
+
+ at node Single Suffix Rules
+ at section Single Suffix Rules and Separated Dependencies
+ at cindex Single Suffix Inference Rule
+ at cindex Rule, Single Suffix Inference
+A @dfn{Single Suffix Rule} is basically a usual suffix (inference) rule
+(@samp{.from.to:}), but which @emph{destination} suffix is empty
+(@samp{.from:}).
+
+ at cindex Separated Dependencies
+ at dfn{Separated dependencies} simply refers to listing the prerequisite
+of a target, without defining a rule. Usually one can list on the one
+hand side, the rules, and on the other hand side, the dependencies.
+
+Solaris @command{make} does not support separated dependencies for
+targets defined by single suffix rules:
+
+ at example
+$ @kbd{cat Makefile}
+.SUFFIXES: .in
+foo: foo.in
+.in:
+ cp $< $@@
+$ @kbd{touch foo.in}
+$ @kbd{make}
+$ @kbd{ls}
+Makefile foo.in
+ at end example
+
+ at noindent
+while GNU Make does:
+
+ at example
+$ @kbd{gmake}
+cp foo.in foo
+$ @kbd{ls}
+Makefile foo foo.in
+ at end example
+
+Note it works without the @samp{foo: foo.in} dependency.
+
+ at example
+$ @kbd{cat Makefile}
+.SUFFIXES: .in
+.in:
+ cp $< $@@
+$ @kbd{make foo}
+cp foo.in foo
+ at end example
+
+ at noindent
+and it works with double suffix inference rules:
+
+ at example
+$ @kbd{cat Makefile}
+foo.out: foo.in
+.SUFFIXES: .in .out
+.in.out:
+ cp $< $@@
+$ @kbd{make}
+cp foo.in foo.out
+ at end example
+
+As a result, in such a case, you have to write target rules.
+
+ at node Timestamps and Make
+ at section Timestamp Resolution and Make
+ at cindex timestamp resolution
+Traditionally, file timestamps had 1-second resolution, and
+ at command{make} used those timestamps to determine whether one file was
+newer than the other. However, many modern file systems have
+timestamps with 1-nanosecond resolution. Some @command{make}
+implementations look at the entire timestamp; others ignore the
+fractional part, which can lead to incorrect results. Normally this
+is not a problem, but in some extreme cases you may need to use tricks
+like @samp{sleep 1} to work around timestamp truncation bugs.
+
+Commands like @samp{cp -p} and @samp{touch -r} typically do not copy
+file timestamps to their full resolutions (@pxref{touch, , Limitations of Usual
+Tools}). Hence you should be wary of rules like this:
+
+ at example
+dest: src
+ cp -p src dest
+ at end example
+
+as @file{dest} often appears to be older than @file{src} after the
+timestamp is truncated, and this can cause @command{make} to do
+needless rework the next time it is invoked. To work around this
+problem, you can use a timestamp file, e.g.:
+
+ at example
+dest-stamp: src
+ cp -p src dest
+ date >dest-stamp
+ at end example
+
+Apart from timestamp resolution, there are also differences in handling
+equal timestamps. HP-UX @command{make} updates targets if it has the
+same time stamp as one of its prerequisites, in violation of Posix rules.
+
+This can cause spurious rebuilds for repeated runs of @command{make}.
+This in turn can cause @command{make} to fail if it tries to rebuild
+generated files in a possibly read-only source tree with tools not
+present on the end-user machine. Use GNU @command{make} instead.
+
+
+
+ at c ======================================== Portable C and C++ Programming
+
+ at node Portable C and C++
+ at chapter Portable C and C++ Programming
+ at cindex Portable C and C++ programming
+
+C and C++ programs often use low-level features of the underlying
+system, and therefore are often more difficult to make portable to other
+platforms.
+
+Several standards have been developed to help make your programs more
+portable. If you write programs with these standards in mind, you can
+have greater confidence that your programs work on a wide variety
+of systems.
+ at ifhtml
+ at uref{http://@/gcc.gnu.org/@/onlinedocs/@/gcc/@/Standards.html, Language
+Standards Supported by GCC}
+ at end ifhtml
+ at ifnothtml
+ at xref{Standards, , Language Standards Supported by
+GCC, gcc, Using the GNU Compiler Collection
+(GCC)},
+ at end ifnothtml
+for a list of C-related standards. Many programs also assume the
+ at uref{http://@/www.opengroup.org/@/susv3, Posix standard}.
+
+Some old code is written to be portable to K&R C, which predates any C
+standard. K&R C compilers are no longer of practical interest, though,
+and the rest of section assumes at least C89, the first C standard.
+
+Program portability is a huge topic, and this section can only briefly
+introduce common pitfalls. @xref{System Portability, , Portability
+between System Types, standards, The GNU Coding Standards}, for
+more information.
+
+ at menu
+* Varieties of Unportability:: How to make your programs unportable
+* Integer Overflow:: When integers get too large
+* Preprocessor Arithmetic:: @code{#if} expression problems
+* Null Pointers:: Properties of null pointers
+* Buffer Overruns:: Subscript errors and the like
+* Volatile Objects:: @code{volatile} and signals
+* Floating Point Portability:: Portable floating-point arithmetic
+* Exiting Portably:: Exiting and the exit status
+ at end menu
+
+ at node Varieties of Unportability
+ at section Varieties of Unportability
+ at cindex portability
+
+Autoconf tests and ordinary programs often need to test what is allowed
+on a system, and therefore they may need to deliberately exceed the
+boundaries of what the standards allow, if only to see whether an
+optional feature is present. When you write such a program, you should
+keep in mind the difference between constraints, unspecified behavior,
+and undefined behavior.
+
+In C, a @dfn{constraint} is a rule that the compiler must enforce. An
+example constraint is that C programs must not declare a bit-field with
+negative width. Tests can therefore reliably assume that programs with
+negative-width bit-fields are rejected by a compiler that conforms
+to the standard.
+
+ at dfn{Unspecified behavior} is valid behavior, where the standard allows
+multiple possibilities. For example, the order of evaluation of
+function arguments is unspecified. Some unspecified behavior is
+ at dfn{implementation-defined}, i.e., documented by the implementation,
+but since Autoconf tests cannot read the documentation they cannot
+distinguish between implementation-defined and other unspecified
+behavior. It is common for Autoconf tests to probe implementations to
+determine otherwise-unspecified behavior.
+
+ at dfn{Undefined behavior} is invalid behavior, where the standard allows
+the implementation to do anything it pleases. For example,
+dereferencing a null pointer leads to undefined behavior. If possible,
+test programs should avoid undefined behavior, since a program with
+undefined behavior might succeed on a test that should fail.
+
+The above rules apply to programs that are intended to conform to the
+standard. However, strictly-conforming programs are quite rare, since
+the standards are so limiting. A major goal of Autoconf is to support
+programs that use implementation features not described by the standard,
+and it is fairly common for test programs to violate the above rules, if
+the programs work well enough in practice.
+
+ at node Integer Overflow
+ at section Integer Overflow
+ at cindex integer overflow
+ at cindex overflow, signed integer
+ at cindex signed integer overflow
+ at cindex wraparound arithmetic
+
+In practice many portable C programs assume that signed integer overflow wraps
+around reliably using two's complement arithmetic. Yet the C standard
+says that program behavior is undefined on overflow, and in a few cases
+C programs do not work on some modern implementations because their
+overflows do not wrap around as their authors expected. Conversely, in
+signed integer remainder, the C standard requires overflow
+behavior that is commonly not implemented.
+
+ at menu
+* 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:: @code{INT_MIN / -1} and @code{INT_MIN % -1}
+ at end menu
+
+ at node Integer Overflow Basics
+ at subsection Basics of Integer Overflow
+ at cindex integer overflow
+ at cindex overflow, signed integer
+ at cindex signed integer overflow
+ at cindex wraparound arithmetic
+
+In languages like C, unsigned integer overflow reliably wraps around;
+e.g., @code{UINT_MAX + 1} yields zero.
+This is guaranteed by the C standard and is
+portable in practice, unless you specify aggressive,
+nonstandard optimization options
+suitable only for special applications.
+
+In contrast, the C standard says that signed integer overflow leads to
+undefined behavior where a program can do anything, including dumping
+core or overrunning a buffer. The misbehavior can even precede the
+overflow. Such an overflow can occur during addition, subtraction,
+multiplication, division, and left shift.
+
+Despite this requirement of the standard, many C programs and Autoconf
+tests assume that signed integer overflow silently wraps around modulo a
+power of two, using two's complement arithmetic, so long as you cast the
+resulting value to a signed integer type or store it into a signed
+integer variable. If you use conservative optimization flags, such
+programs are generally portable to the vast majority of modern
+platforms, with a few exceptions discussed later.
+
+For historical reasons the C standard also allows implementations with
+ones' complement or signed magnitude arithmetic, but it is safe to
+assume two's complement nowadays.
+
+Also, overflow can occur when converting an out-of-range value to a
+signed integer type. Here a standard implementation must define what
+happens, but this might include raising an exception. In practice all
+known implementations support silent wraparound in this case, so you need
+not worry about other possibilities.
+
+ at node Signed Overflow Examples
+ at subsection Examples of Code Assuming Wraparound Overflow
+ at cindex integer overflow
+ at cindex overflow, signed integer
+ at cindex signed integer overflow
+ at cindex wraparound arithmetic
+
+There has long been a tension between what the C standard requires for
+signed integer overflow, and what C programs commonly assume. The
+standard allows aggressive optimizations based on assumptions that
+overflow never occurs, but many practical C programs rely on overflow
+wrapping around. These programs do not conform to the standard, but
+they commonly work in practice because compiler writers are
+understandably reluctant to implement optimizations that would break
+many programs, unless perhaps a user specifies aggressive optimization.
+
+The C Standard says that if a program has signed integer overflow its
+behavior is undefined, and the undefined behavior can even precede the
+overflow. To take an extreme example:
+
+ at c Inspired by Robert Dewar's example in
+ at c <http://gcc.gnu.org/ml/gcc/2007-01/msg00038.html> (2007-01-01).
+ at example
+if (password == expected_password)
+ allow_superuser_privileges ();
+else if (counter++ == INT_MAX)
+ abort ();
+else
+ printf ("%d password mismatches\n", counter);
+ at end example
+
+ at noindent
+If the @code{int} variable @code{counter} equals @code{INT_MAX},
+ at code{counter++} must overflow and the behavior is undefined, so the C
+standard allows the compiler to optimize away the test against
+ at code{INT_MAX} and the @code{abort} call.
+Worse, if an earlier bug in the program lets the compiler deduce that
+ at code{counter == INT_MAX} or that @code{counter} previously overflowed,
+the C standard allows the compiler to optimize away the password test
+and generate code that allows superuser privileges unconditionally.
+
+Despite this requirement by the standard, it has long been common for C
+code to assume wraparound arithmetic after signed overflow, and all
+known practical C implementations support some C idioms that assume
+wraparound signed arithmetic, even if the idioms do not conform
+strictly to the standard. If your code looks like the following
+examples it will almost surely work with real-world compilers.
+
+Here is an example derived from the 7th Edition Unix implementation of
+ at code{atoi} (1979-01-10):
+
+ at example
+char *p;
+int f, n;
+ at dots{}
+while (*p >= '0' && *p <= '9')
+ n = n * 10 + *p++ - '0';
+return (f ? -n : n);
+ at end example
+
+ at noindent
+Even if the input string is in range, on most modern machines this has
+signed overflow when computing the most negative integer (the @code{-n}
+overflows) or a value near an extreme integer (the first @code{+}
+overflows).
+
+Here is another example, derived from the 7th Edition implementation of
+ at code{rand} (1979-01-10). Here the programmer expects both
+multiplication and addition to wrap on overflow:
+
+ at example
+static long int randx = 1;
+ at dots{}
+randx = randx * 1103515245 + 12345;
+return (randx >> 16) & 077777;
+ at end example
+
+In the following example, derived from the GNU C Library 2.5
+implementation of @code{mktime} (2006-09-09), the code assumes
+wraparound arithmetic in @code{+} to detect signed overflow:
+
+ at example
+time_t t, t1, t2;
+int sec_requested, sec_adjustment;
+ at dots{}
+t1 = t + sec_requested;
+t2 = t1 + sec_adjustment;
+if (((t1 < t) != (sec_requested < 0))
+ | ((t2 < t1) != (sec_adjustment < 0)))
+ return -1;
+ at end example
+
+If your code looks like these examples, it is probably safe even though
+it does not strictly conform to the C standard. This might lead one to
+believe that one can generally assume wraparound on overflow, but that
+is not always true, as can be seen in the next section.
+
+ at node Optimization and Wraparound
+ at subsection Optimizations That Break Wraparound Arithmetic
+ at cindex loop induction
+
+Compilers sometimes generate code that is incompatible with wraparound
+integer arithmetic. A simple example is an algebraic simplification: a
+compiler might translate @code{(i * 2000) / 1000} to @code{i * 2}
+because it assumes that @code{i * 2000} does not overflow. The
+translation is not equivalent to the original when overflow occurs:
+e.g., in the typical case of 32-bit signed two's complement wraparound
+ at code{int}, if @code{i} has type @code{int} and value @code{1073742},
+the original expression returns @minus{}2147483 but the optimized
+version returns the mathematically correct value 2147484.
+
+More subtly, loop induction optimizations often exploit the undefined
+behavior of signed overflow. Consider the following contrived function
+ at code{sumc}:
+
+ at example
+int
+sumc (int lo, int hi)
+@{
+ int sum = 0;
+ int i;
+ for (i = lo; i <= hi; i++)
+ sum ^= i * 53;
+ return sum;
+@}
+ at end example
+
+ at noindent
+To avoid multiplying by 53 each time through the loop, an optimizing
+compiler might internally transform @code{sumc} to the equivalent of the
+following:
+
+ at example
+int
+transformed_sumc (int lo, int hi)
+@{
+ int sum = 0;
+ int hic = hi * 53;
+ int ic;
+ for (ic = lo * 53; ic <= hic; ic += 53)
+ sum ^= ic;
+ return sum;
+@}
+ at end example
+
+ at noindent
+This transformation is allowed by the C standard, but it is invalid for
+wraparound arithmetic when @code{INT_MAX / 53 < hi}, because then the
+overflow in computing expressions like @code{hi * 53} can cause the
+expression @code{i <= hi} to yield a different value from the
+transformed expression @code{ic <= hic}.
+
+For this reason, compilers that use loop induction and similar
+techniques often do not support reliable wraparound arithmetic when a
+loop induction variable like @code{ic} is involved. Since loop
+induction variables are generated by the compiler, and are not visible
+in the source code, it is not always trivial to say whether the problem
+affects your code.
+
+Hardly any code actually depends on wraparound arithmetic in cases like
+these, so in practice these loop induction optimizations are almost
+always useful. However, edge cases in this area can cause problems.
+For example:
+
+ at example
+int j;
+for (j = 1; 0 < j; j *= 2)
+ test (j);
+ at end example
+
+ at noindent
+Here, the loop attempts to iterate through all powers of 2 that
+ at code{int} can represent, but the C standard allows a compiler to
+optimize away the comparison and generate an infinite loop,
+under the argument that behavior is undefined on overflow. As of this
+writing this optimization is not done by any production version of
+GCC with @option{-O2}, but it might be performed by other
+compilers, or by more aggressive GCC optimization options,
+and the GCC developers have not decided whether it will
+continue to work with GCC and @option{-O2}.
+
+ at node Signed Overflow Advice
+ at subsection Practical Advice for Signed Overflow Issues
+ at cindex integer overflow
+ at cindex overflow, signed integer
+ at cindex signed integer overflow
+ at cindex wraparound arithmetic
+
+Ideally the safest approach is to avoid signed integer overflow
+entirely. For example, instead of multiplying two signed integers, you
+can convert them to unsigned integers, multiply the unsigned values,
+then test whether the result is in signed range.
+
+Rewriting code in this way will be inconvenient, though, particularly if
+the signed values might be negative. Also, it may hurt
+performance. Using unsigned arithmetic to check for overflow is
+particularly painful to do portably and efficiently when dealing with an
+integer type like @code{uid_t} whose width and signedness vary from
+platform to platform.
+
+Furthermore, many C applications pervasively assume wraparound behavior
+and typically it is not easy to find and remove all these assumptions.
+Hence it is often useful to maintain nonstandard code that assumes
+wraparound on overflow, instead of rewriting the code. The rest of this
+section attempts to give practical advice for this situation.
+
+If your code wants to detect signed integer overflow in @code{sum = a +
+b}, it is generally safe to use an expression like @code{(sum < a) != (b
+< 0)}.
+
+If your code uses a signed loop index, make sure that the index cannot
+overflow, along with all signed expressions derived from the index.
+Here is a contrived example of problematic code with two instances of
+overflow.
+
+ at example
+for (i = INT_MAX - 10; i <= INT_MAX; i++)
+ if (i + 1 < 0)
+ @{
+ report_overflow ();
+ break;
+ @}
+ at end example
+
+ at noindent
+Because of the two overflows, a compiler might optimize away or
+transform the two comparisons in a way that is incompatible with the
+wraparound assumption.
+
+If your code uses an expression like @code{(i * 2000) / 1000} and you
+actually want the multiplication to wrap around on overflow, use
+unsigned arithmetic
+to do it, e.g., @code{((int) (i * 2000u)) / 1000}.
+
+If your code assumes wraparound behavior and you want to insulate it
+against any GCC optimizations that would fail to support that
+behavior, you should use GCC's @option{-fwrapv} option, which
+causes signed overflow to wrap around reliably (except for division and
+remainder, as discussed in the next section).
+
+If you need to port to platforms where signed integer overflow does not
+reliably wrap around (e.g., due to hardware overflow checking, or to
+highly aggressive optimizations), you should consider debugging with
+GCC's @option{-ftrapv} option, which causes signed overflow to
+raise an exception.
+
+ at node Signed Integer Division
+ at subsection Signed Integer Division and Integer Overflow
+ at cindex division, integer
+
+Overflow in signed
+integer division is not always harmless: for example, on CPUs of the
+i386 family, dividing @code{INT_MIN} by @code{-1} yields a SIGFPE signal
+which by default terminates the program. Worse, taking the remainder
+of these two values typically yields the same signal on these CPUs,
+even though the C standard requires @code{INT_MIN % -1} to yield zero
+because the expression does not overflow.
+
+ at node Preprocessor Arithmetic
+ at section Preprocessor Arithmetic
+ at cindex preprocessor arithmetic
+
+In C99, preprocessor arithmetic, used for @code{#if} expressions, must
+be evaluated as if all signed values are of type @code{intmax_t} and all
+unsigned values of type @code{uintmax_t}. Many compilers are buggy in
+this area, though. For example, as of 2007, Sun C mishandles @code{#if
+LLONG_MIN < 0} on a platform with 32-bit @code{long int} and 64-bit
+ at code{long long int}. Also, some older preprocessors mishandle
+constants ending in @code{LL}. To work around these problems, you can
+compute the value of expressions like @code{LONG_MAX < LLONG_MAX} at
+ at code{configure}-time rather than at @code{#if}-time.
+
+ at node Null Pointers
+ at section Properties of Null Pointers
+ at cindex null pointers
+
+Most modern hosts reliably fail when you attempt to dereference a null
+pointer.
+
+On almost all modern hosts, null pointers use an all-bits-zero internal
+representation, so you can reliably use @code{memset} with 0 to set all
+the pointers in an array to null values.
+
+If @code{p} is a null pointer to an object type, the C expression
+ at code{p + 0} always evaluates to @code{p} on modern hosts, even though
+the standard says that it has undefined behavior.
+
+ at node Buffer Overruns
+ at section Buffer Overruns and Subscript Errors
+ at cindex buffer overruns
+
+Buffer overruns and subscript errors are the most common dangerous
+errors in C programs. They result in undefined behavior because storing
+outside an array typically modifies storage that is used by some other
+object, and most modern systems lack runtime checks to catch these
+errors. Programs should not rely on buffer overruns being caught.
+
+There is one exception to the usual rule that a portable program cannot
+address outside an array. In C, it is valid to compute the address just
+past an object, e.g., @code{&a[N]} where @code{a} has @code{N} elements,
+so long as you do not dereference the resulting pointer. But it is not
+valid to compute the address just before an object, e.g., @code{&a[-1]};
+nor is it valid to compute two past the end, e.g., @code{&a[N+1]}. On
+most platforms @code{&a[-1] < &a[0] && &a[N] < &a[N+1]}, but this is not
+reliable in general, and it is usually easy enough to avoid the
+potential portability problem, e.g., by allocating an extra unused array
+element at the start or end.
+
+ at uref{http://@/valgrind.org/, Valgrind} can catch many overruns.
+GCC
+users might also consider using the @option{-fmudflap} option to catch
+overruns.
+
+Buffer overruns are usually caused by off-by-one errors, but there are
+more subtle ways to get them.
+
+Using @code{int} values to index into an array or compute array sizes
+causes problems on typical 64-bit hosts where an array index might
+be @math{2^{31}} or larger. Index values of type @code{size_t} avoid this
+problem, but cannot be negative. Index values of type @code{ptrdiff_t}
+are signed, and are wide enough in practice.
+
+If you add or multiply two numbers to calculate an array size, e.g.,
+ at code{malloc (x * sizeof y + z)}, havoc ensues if the addition or
+multiplication overflows.
+
+Many implementations of the @code{alloca} function silently misbehave
+and can generate buffer overflows if given sizes that are too large.
+The size limits are implementation dependent, but are at least 4000
+bytes on all platforms that we know about.
+
+The standard functions @code{asctime}, @code{asctime_r}, @code{ctime},
+ at code{ctime_r}, and @code{gets} are prone to buffer overflows, and
+portable code should not use them unless the inputs are known to be
+within certain limits. The time-related functions can overflow their
+buffers if given timestamps out of range (e.g., a year less than -999
+or greater than 9999). Time-related buffer overflows cannot happen with
+recent-enough versions of the GNU C library, but are possible
+with other
+implementations. The @code{gets} function is the worst, since it almost
+invariably overflows its buffer when presented with an input line larger
+than the buffer.
+
+ at node Volatile Objects
+ at section Volatile Objects
+ at cindex volatile objects
+
+The keyword @code{volatile} is often misunderstood in portable code.
+Its use inhibits some memory-access optimizations, but programmers often
+wish that it had a different meaning than it actually does.
+
+ at code{volatile} was designed for code that accesses special objects like
+memory-mapped device registers whose contents spontaneously change.
+Such code is inherently low-level, and it is difficult to specify
+portably what @code{volatile} means in these cases. The C standard
+says, ``What constitutes an access to an object that has
+volatile-qualified type is implementation-defined,'' so in theory each
+implementation is supposed to fill in the gap by documenting what
+ at code{volatile} means for that implementation. In practice, though,
+this documentation is usually absent or incomplete.
+
+One area of confusion is the distinction between objects defined with
+volatile types, and volatile lvalues. From the C standard's point of
+view, an object defined with a volatile type has externally visible
+behavior. You can think of such objects as having little oscilloscope
+probes attached to them, so that the user can observe some properties of
+accesses to them, just as the user can observe data written to output
+files. However, the standard does not make it clear whether users can
+observe accesses by volatile lvalues to ordinary objects. For example:
+
+ at example
+/* Declare and access a volatile object.
+ Accesses to X are "visible" to users. */
+static int volatile x;
+x = 1;
+
+/* Access two ordinary objects via a volatile lvalue.
+ It's not clear whether accesses to *P are "visible". */
+int y;
+int *z = malloc (sizeof (int));
+int volatile *p;
+p = &y;
+*p = 1;
+p = z;
+*p = 1;
+ at end example
+
+Programmers often wish that @code{volatile} meant ``Perform the memory
+access here and now, without merging several memory accesses, without
+changing the memory word size, and without reordering.'' But the C
+standard does not require this. For objects defined with a volatile
+type, accesses must be done before the next sequence point; but
+otherwise merging, reordering, and word-size change is allowed. Worse,
+it is not clear from the standard whether volatile lvalues provide more
+guarantees in general than nonvolatile lvalues, if the underlying
+objects are ordinary.
+
+Even when accessing objects defined with a volatile type,
+the C standard allows only
+extremely limited signal handlers: the behavior is undefined if a signal
+handler reads any nonlocal object, or writes to any nonlocal object
+whose type is not @code{sig_atomic_t volatile}, or calls any standard
+library function other than @code{abort}, @code{signal}, and (if C99)
+ at code{_Exit}. Hence C compilers need not worry about a signal handler
+disturbing ordinary computation, unless the computation accesses a
+ at code{sig_atomic_t volatile} lvalue that is not a local variable.
+(There is an obscure exception for accesses via a pointer to a volatile
+character, since it may point into part of a @code{sig_atomic_t
+volatile} object.) Posix
+adds to the list of library functions callable from a portable signal
+handler, but otherwise is like the C standard in this area.
+
+Some C implementations allow memory-access optimizations within each
+translation unit, such that actual behavior agrees with the behavior
+required by the standard only when calling a function in some other
+translation unit, and a signal handler acts like it was called from a
+different translation unit. The C standard hints that in these
+implementations, objects referred to by signal handlers ``would require
+explicit specification of @code{volatile} storage, as well as other
+implementation-defined restrictions.'' But unfortunately even for this
+special case these other restrictions are often not documented well.
+ at xref{Volatiles, , When is a Volatile Object Accessed?, gcc, Using the
+GNU Compiler Collection (GCC)}, for some
+restrictions imposed by GCC. @xref{Defining Handlers, ,
+Defining Signal Handlers, libc, The GNU C Library}, for some
+restrictions imposed by the GNU C library. Restrictions
+differ on other platforms.
+
+If possible, it is best to use a signal handler that fits within the
+limits imposed by the C and Posix standards.
+
+If this is not practical, you can try the following rules of thumb. A
+signal handler should access only volatile lvalues, preferably lvalues
+that refer to objects defined with a volatile type, and should not
+assume that the accessed objects have an internally consistent state
+if they are larger than a machine word. Furthermore, installers
+should employ compilers and compiler options that are commonly used
+for building operating system kernels, because kernels often need more
+from @code{volatile} than the C Standard requires, and installers who
+compile an application in a similar environment can sometimes benefit
+from the extra constraints imposed by kernels on compilers.
+Admittedly we are handwaving somewhat here, as there are few
+guarantees in this area; the rules of thumb may help to fix some bugs
+but there is a good chance that they will not fix them all.
+
+For @code{volatile}, C++ has the same problems that C does.
+Multithreaded applications have even more problems with @code{volatile},
+but they are beyond the scope of this section.
+
+The bottom line is that using @code{volatile} typically hurts
+performance but should not hurt correctness. In some cases its use
+does help correctness, but these cases are often so poorly understood
+that all too often adding @code{volatile} to a data structure merely
+alleviates some symptoms of a bug while not fixing the bug in general.
+
+ at node Floating Point Portability
+ at section Floating Point Portability
+ at cindex floating point
+
+Almost all modern systems use IEEE-754 floating point, and it is safe to
+assume IEEE-754 in most portable code these days. For more information,
+please see David Goldberg's classic paper
+ at uref{http://@/www.validlab.com/@/goldberg/@/paper.pdf, What Every Computer
+Scientist Should Know About Floating-Point Arithmetic}.
+
+ at node Exiting Portably
+ at section Exiting Portably
+ at cindex exiting portably
+
+A C or C++ program can exit with status @var{N} by returning
+ at var{N} from the @code{main} function. Portable programs are supposed
+to exit either with status 0 or @code{EXIT_SUCCESS} to succeed, or with
+status @code{EXIT_FAILURE} to fail, but in practice it is portable to
+fail by exiting with status 1, and test programs that assume Posix can
+fail by exiting with status values from 1 through 255. Programs on
+SunOS 2.0 (1985) through 3.5.2 (1988) incorrectly exited with zero
+status when @code{main} returned nonzero, but ancient systems like these
+are no longer of practical concern.
+
+A program can also exit with status @var{N} by passing @var{N} to the
+ at code{exit} function, and a program can fail by calling the @code{abort}
+function. If a program is specialized to just some platforms, it can fail
+by calling functions specific to those platforms, e.g., @code{_exit}
+(Posix) and @code{_Exit} (C99). However, like other functions, an exit
+function should be declared, typically by including a header. For
+example, if a C program calls @code{exit}, it should include @file{stdlib.h}
+either directly or via the default includes (@pxref{Default Includes}).
+
+A program can fail due to undefined behavior such as dereferencing a null
+pointer, but this is not recommended as undefined behavior allows an
+implementation to do whatever it pleases and this includes exiting
+successfully.
+
+
+ at c ================================================== Manual Configuration
+
+ at node Manual Configuration
+ at chapter Manual Configuration
+
+A few kinds of features can't be guessed automatically by running test
+programs. For example, the details of the object-file format, or
+special options that need to be passed to the compiler or linker. You
+can check for such features using ad-hoc means, such as having
+ at command{configure} check the output of the @code{uname} program, or
+looking for libraries that are unique to particular systems. However,
+Autoconf provides a uniform method for handling unguessable features.
+
+ at menu
+* Specifying Target Triplets:: Specifying target triplets
+* Canonicalizing:: Getting the canonical system type
+* Using System Type:: What to do with the system type
+ at end menu
+
+ at node Specifying Target Triplets
+ at section Specifying target triplets
+ at cindex System type
+ at cindex Target triplet
+ at c This node used to be named Specifying Names. The @anchor allows old
+ at c links to still work.
+ at anchor{Specifying Names}
+
+Autoconf-generated
+ at command{configure} scripts can make decisions based on a canonical name
+for the system type, or @dfn{target triplet}, which has the form:
+ at samp{@var{cpu}- at var{vendor}- at var{os}}, where @var{os} can be
+ at samp{@var{system}} or @samp{@var{kernel}- at var{system}}
+
+ at command{configure} can usually guess the canonical name for the type of
+system it's running on. To do so it runs a script called
+ at command{config.guess}, which infers the name using the @code{uname}
+command or symbols predefined by the C preprocessor.
+
+Alternately, the user can specify the system type with command line
+arguments to @command{configure} (@pxref{System Type}. Doing so is
+necessary when
+cross-compiling. In the most complex case of cross-compiling, three
+system types are involved. The options to specify them are:
+
+ at table @option
+ at item --build=@var{build-type}
+the type of system on which the package is being configured and
+compiled. It defaults to the result of running @command{config.guess}.
+Specifying a @var{build-type} that differs from @var{host-type} enables
+cross-compilation mode.
+
+ at item --host=@var{host-type}
+the type of system on which the package runs. By default it is the
+same as the build machine. Specifying a @var{host-type} that differs
+from @var{build-type}, when @var{build-type} was also explicitly
+specified, enables cross-compilation mode.
+
+ at item --target=@var{target-type}
+the type of system for which any compiler tools in the package
+produce code (rarely needed). By default, it is the same as host.
+ at end table
+
+If you mean to override the result of @command{config.guess}, use
+ at option{--build}, not @option{--host}, since the latter enables
+cross-compilation. For historical reasons,
+whenever you specify @option{--host},
+be sure to specify @option{--build} too; this will be fixed in the
+future. So, to enter cross-compilation mode, use a command like this
+
+ at example
+./configure --build=i686-pc-linux-gnu --host=m68k-coff
+ at end example
+
+ at noindent
+Note that if you do not specify @option{--host}, @command{configure}
+fails if it can't run the code generated by the specified compiler. For
+example, configuring as follows fails:
+
+ at example
+./configure CC=m68k-coff-gcc
+ at end example
+
+When cross-compiling, @command{configure} will warn about any tools
+(compilers, linkers, assemblers) whose name is not prefixed with the
+host type. This is an aid to users performing cross-compilation.
+Continuing the example above, if a cross-compiler named @command{cc} is
+used with a native @command{pkg-config}, then libraries found by
+ at command{pkg-config} will likely cause subtle build failures; but using
+the names @command{m68k-coff-cc} and @command{m68k-coff-pkg-config}
+avoids any confusion. Avoiding the warning is as simple as creating the
+correct symlinks naming the cross tools.
+
+ at cindex @command{config.sub}
+ at command{configure} recognizes short aliases for many system types; for
+example, @samp{decstation} can be used instead of
+ at samp{mips-dec-ultrix4.2}. @command{configure} runs a script called
+ at command{config.sub} to canonicalize system type aliases.
+
+This section deliberately omits the description of the obsolete
+interface; see @ref{Hosts and Cross-Compilation}.
+
+
+ at node Canonicalizing
+ at section Getting the Canonical System Type
+ at cindex System type
+ at cindex Canonical system type
+
+The following macros make the system type available to @command{configure}
+scripts.
+
+ at ovindex build_alias
+ at ovindex host_alias
+ at ovindex target_alias
+
+The variables @samp{build_alias}, @samp{host_alias}, and
+ at samp{target_alias} are always exactly the arguments of @option{--build},
+ at option{--host}, and @option{--target}; in particular, they are left empty
+if the user did not use them, even if the corresponding
+ at code{AC_CANONICAL} macro was run. Any configure script may use these
+variables anywhere. These are the variables that should be used when in
+interaction with the user.
+
+If you need to recognize some special environments based on their system
+type, run the following macros to get canonical system names. These
+variables are not set before the macro call.
+
+If you use these macros, you must distribute @command{config.guess} and
+ at command{config.sub} along with your source code. @xref{Output}, for
+information about the @code{AC_CONFIG_AUX_DIR} macro which you can use
+to control in which directory @command{configure} looks for those scripts.
+
+
+ at defmac AC_CANONICAL_BUILD
+ at acindex{CANONICAL_BUILD}
+ at ovindex build
+ at ovindex build_cpu
+ at ovindex build_vendor
+ at ovindex build_os
+Compute the canonical build-system type variable, @code{build}, and its
+three individual parts @code{build_cpu}, @code{build_vendor}, and
+ at code{build_os}.
+
+If @option{--build} was specified, then @code{build} is the
+canonicalization of @code{build_alias} by @command{config.sub},
+otherwise it is determined by the shell script @command{config.guess}.
+ at end defmac
+
+ at defmac AC_CANONICAL_HOST
+ at acindex{CANONICAL_HOST}
+ at ovindex host
+ at ovindex host_cpu
+ at ovindex host_vendor
+ at ovindex host_os
+Compute the canonical host-system type variable, @code{host}, and its
+three individual parts @code{host_cpu}, @code{host_vendor}, and
+ at code{host_os}.
+
+If @option{--host} was specified, then @code{host} is the
+canonicalization of @code{host_alias} by @command{config.sub},
+otherwise it defaults to @code{build}.
+ at end defmac
+
+ at defmac AC_CANONICAL_TARGET
+ at acindex{CANONICAL_TARGET}
+ at ovindex target
+ at ovindex target_cpu
+ at ovindex target_vendor
+ at ovindex target_os
+Compute the canonical target-system type variable, @code{target}, and its
+three individual parts @code{target_cpu}, @code{target_vendor}, and
+ at code{target_os}.
+
+If @option{--target} was specified, then @code{target} is the
+canonicalization of @code{target_alias} by @command{config.sub},
+otherwise it defaults to @code{host}.
+ at end defmac
+
+Note that there can be artifacts due to the backward compatibility
+code. @xref{Hosts and Cross-Compilation}, for more.
+
+ at node Using System Type
+ at section Using the System Type
+
+In @file{configure.ac} the system type is generally used by one or more
+ at code{case} statements to select system-specifics. Shell wildcards can
+be used to match a group of system types.
+
+For example, an extra assembler code object file could be chosen, giving
+access to a CPU cycle counter register. @code{$(CYCLE_OBJ)} in the
+following would be used in a makefile to add the object to a
+program or library.
+
+ at example
+AS_CASE([$host],
+ [alpha*-*-*], [CYCLE_OBJ=rpcc.o],
+ [i?86-*-*], [CYCLE_OBJ=rdtsc.o],
+ [CYCLE_OBJ=""]
+)
+AC_SUBST([CYCLE_OBJ])
+ at end example
+
+ at code{AC_CONFIG_LINKS} (@pxref{Configuration Links}) is another good way
+to select variant source files, for example optimized code for some
+CPUs. The configured CPU type doesn't always indicate exact CPU types,
+so some runtime capability checks may be necessary too.
+
+ at example
+case $host in
+ alpha*-*-*) AC_CONFIG_LINKS([dither.c:alpha/dither.c]) ;;
+ powerpc*-*-*) AC_CONFIG_LINKS([dither.c:powerpc/dither.c]) ;;
+ *-*-*) AC_CONFIG_LINKS([dither.c:generic/dither.c]) ;;
+esac
+ at end example
+
+The host system type can also be used to find cross-compilation tools
+with @code{AC_CHECK_TOOL} (@pxref{Generic Programs}).
+
+The above examples all show @samp{$host}, since this is where the code
+is going to run. Only rarely is it necessary to test @samp{$build}
+(which is where the build is being done).
+
+Whenever you're tempted to use @samp{$host} it's worth considering
+whether some sort of probe would be better. New system types come along
+periodically or previously missing features are added. Well-written
+probes can adapt themselves to such things, but hard-coded lists of
+names can't. Here are some guidelines,
+
+ at itemize @bullet
+ at item
+Availability of libraries and library functions should always be checked
+by probing.
+ at item
+Variant behavior of system calls is best identified with runtime tests
+if possible, but bug workarounds or obscure difficulties might have to
+be driven from @samp{$host}.
+ at item
+Assembler code is inevitably highly CPU-specific and is best selected
+according to @samp{$host_cpu}.
+ at item
+Assembler variations like underscore prefix on globals or ELF versus
+COFF type directives are however best determined by probing, perhaps
+even examining the compiler output.
+ at end itemize
+
+ at samp{$target} is for use by a package creating a compiler or similar.
+For ordinary packages it's meaningless and should not be used. It
+indicates what the created compiler should generate code for, if it can
+cross-compile. @samp{$target} generally selects various hard-coded CPU
+and system conventions, since usually the compiler or tools under
+construction themselves determine how the target works.
+
+
+ at c ===================================================== Site Configuration.
+
+ at node Site Configuration
+ at chapter Site Configuration
+
+ at command{configure} scripts support several kinds of local configuration
+decisions. There are ways for users to specify where external software
+packages are, include or exclude optional features, install programs
+under modified names, and set default values for @command{configure}
+options.
+
+ at menu
+* Help Formatting:: Customizing @samp{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 @command{configure} options
+* Site Details:: Configuring site details
+* Transforming Names:: Changing program names when installing
+* Site Defaults:: Giving @command{configure} local defaults
+ at end menu
+
+ at node Help Formatting
+ at section Controlling Help Output
+
+Users consult @samp{configure --help} to learn of configuration
+decisions specific to your package. By default, @command{configure}
+breaks this output into sections for each type of option; within each
+section, help strings appear in the order @file{configure.ac} defines
+them:
+
+ at example
+Optional Features:
+ @dots{}
+ --enable-bar include bar
+
+Optional Packages:
+ @dots{}
+ --with-foo use foo
+ at end example
+
+ at defmac AC_PRESERVE_HELP_ORDER
+ at acindex{PRESERVE_HELP_ORDER}
+
+Request an alternate @option{--help} format, in which options of all
+types appear together, in the order defined. Call this macro before any
+ at code{AC_ARG_ENABLE} or @code{AC_ARG_WITH}.
+
+ at example
+Optional Features and Packages:
+ @dots{}
+ --enable-bar include bar
+ --with-foo use foo
+ at end example
+
+ at end defmac
+
+ at node External Software
+ at section Working With External Software
+ at cindex External software
+
+Some packages require, or can optionally use, other software packages
+that are already installed. The user can give @command{configure}
+command line options to specify which such external software to use.
+The options have one of these forms:
+
+ at c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
+ at c awful.
+ at example
+--with- at var{package}@r{[}=@var{arg}@r{]}
+--without- at var{package}
+ at end example
+
+For example, @option{--with-gnu-ld} means work with the GNU linker
+instead of some other linker. @option{--with-x} means work with The X
+Window System.
+
+The user can give an argument by following the package name with
+ at samp{=} and the argument. Giving an argument of @samp{no} is for
+packages that are used by default; it says to @emph{not} use the
+package. An argument that is neither @samp{yes} nor @samp{no} could
+include a name or number of a version of the other package, to specify
+more precisely which other package this program is supposed to work
+with. If no argument is given, it defaults to @samp{yes}.
+ at option{--without- at var{package}} is equivalent to
+ at option{--with- at var{package}=no}.
+
+Normally @command{configure} scripts complain about
+ at option{--with- at var{package}} options that they do not support.
+ at xref{Option Checking}, for details, and for how to override the
+defaults.
+
+For each external software package that may be used, @file{configure.ac}
+should call @code{AC_ARG_WITH} to detect whether the @command{configure}
+user asked to use it. Whether each package is used or not by default,
+and which arguments are valid, is up to you.
+
+ at anchor{AC_ARG_WITH}
+ at defmac AC_ARG_WITH (@var{package}, @var{help-string}, @
+ @ovar{action-if-given}, @ovar{action-if-not-given})
+ at acindex{ARG_WITH}
+If the user gave @command{configure} the option @option{--with- at var{package}}
+or @option{--without- at var{package}}, run shell commands
+ at var{action-if-given}. If neither option was given, run shell commands
+ at var{action-if-not-given}. The name @var{package} indicates another
+software package that this program should work with. It should consist
+only of alphanumeric characters, dashes, plus signs, and dots.
+
+The option's argument is available to the shell commands
+ at var{action-if-given} in the shell variable @code{withval}, which is
+actually just the value of the shell variable named
+ at code{with_ at var{package}}, with any non-alphanumeric characters in
+ at var{package} changed into @samp{_}. You may use that variable instead,
+if you wish.
+
+The argument @var{help-string} is a description of the option that
+looks like this:
+ at example
+ --with-readline support fancy command line editing
+ at end example
+
+ at noindent
+ at var{help-string} may be more than one line long, if more detail is
+needed. Just make sure the columns line up in @samp{configure
+--help}. Avoid tabs in the help string. The easiest way to provide the
+proper leading whitespace is to format your @var{help-string} with the macro
+ at code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
+
+The following example shows how to use the @code{AC_ARG_WITH} macro in
+a common situation. You want to let the user decide whether to enable
+support for an external library (e.g., the readline library); if the user
+specified neither @option{--with-readline} nor @option{--without-readline},
+you want to enable support for readline only if the library is available
+on the system.
+
+ at c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
+ at example
+AC_ARG_WITH([readline],
+ [AS_HELP_STRING([--with-readline],
+ [support fancy command line editing @@<:@@default=check@@:>@@])],
+ [],
+ [with_readline=check])
+
+LIBREADLINE=
+AS_IF([test "x$with_readline" != xno],
+ [AC_CHECK_LIB([readline], [main],
+ [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
+ AC_DEFINE([HAVE_LIBREADLINE], [1],
+ [Define if you have libreadline])
+ ],
+ [if test "x$with_readline" != xcheck; then
+ AC_MSG_FAILURE(
+ [--with-readline was given, but test for readline failed])
+ fi
+ ], -lncurses)])
+ at end example
+
+The next example shows how to use @code{AC_ARG_WITH} to give the user the
+possibility to enable support for the readline library, in case it is still
+experimental and not well tested, and is therefore disabled by default.
+
+ at c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
+ at example
+AC_ARG_WITH([readline],
+ [AS_HELP_STRING([--with-readline],
+ [enable experimental support for readline])],
+ [],
+ [with_readline=no])
+
+LIBREADLINE=
+AS_IF([test "x$with_readline" != xno],
+ [AC_CHECK_LIB([readline], [main],
+ [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
+ AC_DEFINE([HAVE_LIBREADLINE], [1],
+ [Define if you have libreadline])
+ ],
+ [AC_MSG_FAILURE(
+ [--with-readline was given, but test for readline failed])],
+ [-lncurses])])
+ at end example
+
+The last example shows how to use @code{AC_ARG_WITH} to give the user the
+possibility to disable support for the readline library, given that it is
+an important feature and that it should be enabled by default.
+
+ at c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
+ at example
+AC_ARG_WITH([readline],
+ [AS_HELP_STRING([--without-readline],
+ [disable support for readline])],
+ [],
+ [with_readline=yes])
+
+LIBREADLINE=
+AS_IF([test "x$with_readline" != xno],
+ [AC_CHECK_LIB([readline], [main],
+ [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
+ AC_DEFINE([HAVE_LIBREADLINE], [1],
+ [Define if you have libreadline])
+ ],
+ [AC_MSG_FAILURE(
+ [readline test failed (--without-readline to disable)])],
+ [-lncurses])])
+ at end example
+
+These three examples can be easily adapted to the case where
+ at code{AC_ARG_ENABLE} should be preferred to @code{AC_ARG_WITH} (see
+ at ref{Package Options}).
+ at end defmac
+
+ at node Package Options
+ at section Choosing Package Options
+ at cindex Package options
+ at cindex Options, package
+
+If a software package has optional compile-time features, the user can
+give @command{configure} command line options to specify whether to
+compile them. The options have one of these forms:
+
+ at c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
+ at c awful.
+ at example
+--enable- at var{feature}@r{[}=@var{arg}@r{]}
+--disable- at var{feature}
+ at end example
+
+These options allow users to choose which optional features to build and
+install. @option{--enable- at var{feature}} options should never make a
+feature behave differently or cause one feature to replace another.
+They should only cause parts of the program to be built rather than left
+out.
+
+The user can give an argument by following the feature name with
+ at samp{=} and the argument. Giving an argument of @samp{no} requests
+that the feature @emph{not} be made available. A feature with an
+argument looks like @option{--enable-debug=stabs}. If no argument is
+given, it defaults to @samp{yes}. @option{--disable- at var{feature}} is
+equivalent to @option{--enable- at var{feature}=no}.
+
+Normally @command{configure} scripts complain about
+ at option{--enable- at var{package}} options that they do not support.
+ at xref{Option Checking}, for details, and for how to override the
+defaults.
+
+For each optional feature, @file{configure.ac} should call
+ at code{AC_ARG_ENABLE} to detect whether the @command{configure} user asked
+to include it. Whether each feature is included or not by default, and
+which arguments are valid, is up to you.
+
+ at anchor{AC_ARG_ENABLE}
+ at defmac AC_ARG_ENABLE (@var{feature}, @var{help-string}, @
+ @ovar{action-if-given}, @ovar{action-if-not-given})
+ at acindex{ARG_ENABLE}
+If the user gave @command{configure} the option
+ at option{--enable- at var{feature}} or @option{--disable- at var{feature}}, run
+shell commands @var{action-if-given}. If neither option was given, run
+shell commands @var{action-if-not-given}. The name @var{feature}
+indicates an optional user-level facility. It should consist only of
+alphanumeric characters, dashes, plus signs, and dots.
+
+The option's argument is available to the shell commands
+ at var{action-if-given} in the shell variable @code{enableval}, which is
+actually just the value of the shell variable named
+ at code{enable_ at var{feature}}, with any non-alphanumeric characters in
+ at var{feature} changed into @samp{_}. You may use that variable instead,
+if you wish. The @var{help-string} argument is like that of
+ at code{AC_ARG_WITH} (@pxref{External Software}).
+
+You should format your @var{help-string} with the macro
+ at code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
+
+See the examples suggested with the definition of @code{AC_ARG_WITH}
+(@pxref{External Software}) to get an idea of possible applications of
+ at code{AC_ARG_ENABLE}.
+ at end defmac
+
+ at node Pretty Help Strings
+ at section Making Your Help Strings Look Pretty
+ at cindex Help strings
+
+Properly formatting the @samp{help strings} which are used in
+ at code{AC_ARG_WITH} (@pxref{External Software}) and @code{AC_ARG_ENABLE}
+(@pxref{Package Options}) can be challenging. Specifically, you want
+your own @samp{help strings} to line up in the appropriate columns of
+ at samp{configure --help} just like the standard Autoconf @samp{help
+strings} do. This is the purpose of the @code{AS_HELP_STRING} macro.
+
+ at anchor{AS_HELP_STRING}
+ at defmac AS_HELP_STRING (@var{left-hand-side}, @var{right-hand-side} @
+ @dvar{indent-column, 26}, @dvar{wrap-column, 79})
+ at asindex{HELP_STRING}
+
+Expands into a help string that looks pretty when the user executes
+ at samp{configure --help}. It is typically used in @code{AC_ARG_WITH}
+(@pxref{External Software}) or @code{AC_ARG_ENABLE} (@pxref{Package
+Options}). The following example makes this clearer.
+
+ at example
+AC_ARG_WITH([foo],
+ [AS_HELP_STRING([--with-foo],
+ [use foo (default is no)])],
+ [use_foo=$withval],
+ [use_foo=no])
+ at end example
+
+Then the last few lines of @samp{configure --help} appear like
+this:
+
+ at example
+--enable and --with options recognized:
+ --with-foo use foo (default is no)
+ at end example
+
+Macro expansion is performed on the first argument. However, the second
+argument of @code{AS_HELP_STRING} is treated as a whitespace separated
+list of text to be reformatted, and is not subject to macro expansion.
+Since it is not expanded, it should not be double quoted.
+ at xref{Autoconf Language}, for a more detailed explanation.
+
+The @code{AS_HELP_STRING} macro is particularly helpful when the
+ at var{left-hand-side} and/or @var{right-hand-side} are composed of macro
+arguments, as shown in the following example. Be aware that
+ at var{left-hand-side} may not expand to unbalanced quotes,
+although quadrigraphs can be used.
+
+ at example
+AC_DEFUN([MY_ARG_WITH],
+ [AC_ARG_WITH(m4_translit([[$1]], [_], [-]),
+ [AS_HELP_STRING([--with-m4_translit([$1], [_], [-])],
+ [use $1 (default is $2)])],
+ [use_[]$1=$withval],
+ [use_[]$1=$2])])
+MY_ARG_WITH([a_b], [no])
+ at end example
+ at noindent
+Here, the last few lines of @samp{configure --help} will include:
+
+ at example
+--enable and --with options recognized:
+ --with-a-b use a_b (default is no)
+ at end example
+
+The parameters @var{indent-column} and @var{wrap-column} were introduced
+in Autoconf 2.62. Generally, they should not be specified; they exist
+for fine-tuning of the wrapping.
+ at example
+AS_HELP_STRING([--option], [description of option])
+ at result{} --option description of option
+AS_HELP_STRING([--option], [description of option], [15], [30])
+ at result{} --option description of
+ at result{} option
+ at end example
+ at end defmac
+
+
+ at node Option Checking
+ at section Controlling Checking of @command{configure} Options
+ at cindex Options, Package
+
+The @command{configure} script checks its command-line options against a
+list of known options, like @option{--help} or @option{--config-cache}.
+An unknown option ordinarily indicates a mistake by the user and
+ at command{configure} halts with an error. However, by default unknown
+ at option{--with- at var{package}} and @option{--enable- at var{feature}}
+options elicit only a warning, to support configuring entire source
+trees.
+
+Source trees often contain multiple packages with a top-level
+ at command{configure} script that uses the @code{AC_CONFIG_SUBDIRS} macro
+(@pxref{Subdirectories}). Because the packages generally support
+different @option{--with- at var{package}} and
+ at option{--enable- at var{feature}} options, the GNU Coding
+Standards say they must accept unrecognized options without halting.
+Even a warning message is undesirable here, so @code{AC_CONFIG_SUBDIRS}
+automatically disables the warnings.
+
+This default behavior may be modified in two ways. First, the installer
+can invoke @code{configure --disable-option-checking} to disable
+these warnings, or invoke @code{configure --enable-option-checking=fatal}
+options to turn them into fatal errors, respectively. Second, the
+maintainer can use @code{AC_DISABLE_OPTION_CHECKING}.
+
+ at defmac AC_DISABLE_OPTION_CHECKING
+ at acindex{DISABLE_OPTION_CHECKING}
+
+By default, disable warnings related to any unrecognized
+ at option{--with- at var{package}} or @option{--enable- at var{feature}}
+options. This is implied by @code{AC_CONFIG_SUBDIRS}.
+
+The installer can override this behavior by passing
+ at option{--enable-option-checking} (enable warnings) or
+ at option{--enable-option-checking=fatal} (enable errors) to
+ at command{configure}.
+ at end defmac
+
+
+ at node Site Details
+ at section Configuring Site Details
+ at cindex Site details
+
+Some software packages require complex site-specific information. Some
+examples are host names to use for certain services, company names, and
+email addresses to contact. Since some configuration scripts generated
+by Metaconfig ask for such information interactively, people sometimes
+wonder how to get that information in Autoconf-generated configuration
+scripts, which aren't interactive.
+
+Such site configuration information should be put in a file that is
+edited @emph{only by users}, not by programs. The location of the file
+can either be based on the @code{prefix} variable, or be a standard
+location such as the user's home directory. It could even be specified
+by an environment variable. The programs should examine that file at
+runtime, rather than at compile time. Runtime configuration is more
+convenient for users and makes the configuration process simpler than
+getting the information while configuring. @xref{Directory Variables, ,
+Variables for Installation Directories, standards, The GNU Coding
+Standards}, for more information on where to put data files.
+
+ at node Transforming Names
+ at section Transforming Program Names When Installing
+ at cindex Transforming program names
+ at cindex Program names, transforming
+
+Autoconf supports changing the names of programs when installing them.
+In order to use these transformations, @file{configure.ac} must call the
+macro @code{AC_ARG_PROGRAM}.
+
+ at defmac AC_ARG_PROGRAM
+ at acindex{ARG_PROGRAM}
+ at ovindex program_transform_name
+Place in output variable @code{program_transform_name} a sequence of
+ at code{sed} commands for changing the names of installed programs.
+
+If any of the options described below are given to @command{configure},
+program names are transformed accordingly. Otherwise, if
+ at code{AC_CANONICAL_TARGET} has been called and a @option{--target} value
+is given, the target type followed by a dash is used as a prefix.
+Otherwise, no program name transformation is done.
+ at end defmac
+
+ at menu
+* Transformation Options:: @command{configure} options to transform names
+* Transformation Examples:: Sample uses of transforming names
+* Transformation Rules:: Makefile uses of transforming names
+ at end menu
+
+ at node Transformation Options
+ at subsection Transformation Options
+
+You can specify name transformations by giving @command{configure} these
+command line options:
+
+ at table @option
+ at item --program-prefix=@var{prefix}
+prepend @var{prefix} to the names;
+
+ at item --program-suffix=@var{suffix}
+append @var{suffix} to the names;
+
+ at item --program-transform-name=@var{expression}
+perform @code{sed} substitution @var{expression} on the names.
+ at end table
+
+ at node Transformation Examples
+ at subsection Transformation Examples
+
+These transformations are useful with programs that can be part of a
+cross-compilation development environment. For example, a
+cross-assembler running on a Sun 4 configured with
+ at option{--target=i960-vxworks} is normally installed as
+ at file{i960-vxworks-as}, rather than @file{as}, which could be confused
+with a native Sun 4 assembler.
+
+You can force a program name to begin with @file{g}, if you don't want
+GNU programs installed on your system to shadow other programs with
+the same name. For example, if you configure GNU @code{diff} with
+ at option{--program-prefix=g}, then when you run @samp{make install} it is
+installed as @file{/usr/local/bin/gdiff}.
+
+As a more sophisticated example, you could use
+
+ at example
+--program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/'
+ at end example
+ at noindent
+
+to prepend @samp{g} to most of the program names in a source tree,
+excepting those like @code{gdb} that already have one and those like
+ at code{less} and @code{lesskey} that aren't GNU programs. (That is
+assuming that you have a source tree containing those programs that is
+set up to use this feature.)
+
+One way to install multiple versions of some programs simultaneously is
+to append a version number to the name of one or both. For example, if
+you want to keep Autoconf version 1 around for awhile, you can configure
+Autoconf version 2 using @option{--program-suffix=2} to install the
+programs as @file{/usr/local/bin/autoconf2},
+ at file{/usr/local/bin/autoheader2}, etc. Nevertheless, pay attention
+that only the binaries are renamed, therefore you'd have problems with
+the library files which might overlap.
+
+ at node Transformation Rules
+ at subsection Transformation Rules
+
+Here is how to use the variable @code{program_transform_name} in a
+ at file{Makefile.in}:
+
+ at example
+PROGRAMS = cp ls rm
+transform = @@program_transform_name@@
+install:
+ for p in $(PROGRAMS); do \
+ $(INSTALL_PROGRAM) $$p $(DESTDIR)$(bindir)/`echo $$p | \
+ sed '$(transform)'`; \
+ done
+
+uninstall:
+ for p in $(PROGRAMS); do \
+ rm -f $(DESTDIR)$(bindir)/`echo $$p | sed '$(transform)'`; \
+ at c $$ restore font-lock
+ done
+ at end example
+
+It is guaranteed that @code{program_transform_name} is never empty, and
+that there are no useless separators. Therefore you may safely embed
+ at code{program_transform_name} within a sed program using @samp{;}:
+
+ at example
+transform = @@program_transform_name@@
+transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/
+ at end example
+
+Whether to do the transformations on documentation files (Texinfo or
+ at code{man}) is a tricky question; there seems to be no perfect answer,
+due to the several reasons for name transforming. Documentation is not
+usually particular to a specific architecture, and Texinfo files do not
+conflict with system documentation. But they might conflict with
+earlier versions of the same files, and @code{man} pages sometimes do
+conflict with system documentation. As a compromise, it is probably
+best to do name transformations on @code{man} pages but not on Texinfo
+manuals.
+
+ at node Site Defaults
+ at section Setting Site Defaults
+ at cindex Site defaults
+ at cindex config.site
+
+Autoconf-generated @command{configure} scripts allow your site to provide
+default values for some configuration values. You do this by creating
+site- and system-wide initialization files.
+
+ at evindex CONFIG_SITE
+If the environment variable @code{CONFIG_SITE} is set, @command{configure}
+uses its value as the name of a shell script to read; it is recommended
+that this be an absolute file name. Otherwise, it
+reads the shell script @file{@var{prefix}/share/config.site} if it exists,
+then @file{@var{prefix}/etc/config.site} if it exists. Thus,
+settings in machine-specific files override those in machine-independent
+ones in case of conflict.
+
+Site files can be arbitrary shell scripts, but only certain kinds of
+code are really appropriate to be in them. Because @command{configure}
+reads any cache file after it has read any site files, a site file can
+define a default cache file to be shared between all Autoconf-generated
+ at command{configure} scripts run on that system (@pxref{Cache Files}). If
+you set a default cache file in a site file, it is a good idea to also
+set the output variable @code{CC} in that site file, because the cache
+file is only valid for a particular compiler, but many systems have
+several available.
+
+You can examine or override the value set by a command line option to
+ at command{configure} in a site file; options set shell variables that have
+the same names as the options, with any dashes turned into underscores.
+The exceptions are that @option{--without-} and @option{--disable-} options
+are like giving the corresponding @option{--with-} or @option{--enable-}
+option and the value @samp{no}. Thus, @option{--cache-file=localcache}
+sets the variable @code{cache_file} to the value @samp{localcache};
+ at option{--enable-warnings=no} or @option{--disable-warnings} sets the variable
+ at code{enable_warnings} to the value @samp{no}; @option{--prefix=/usr} sets the
+variable @code{prefix} to the value @samp{/usr}; etc.
+
+Site files are also good places to set default values for other output
+variables, such as @code{CFLAGS}, if you need to give them non-default
+values: anything you would normally do, repetitively, on the command
+line. If you use non-default values for @var{prefix} or
+ at var{exec_prefix} (wherever you locate the site file), you can set them
+in the site file if you specify it with the @code{CONFIG_SITE}
+environment variable.
+
+You can set some cache values in the site file itself. Doing this is
+useful if you are cross-compiling, where it is impossible to check features
+that require running a test program. You could ``prime the cache'' by
+setting those values correctly for that system in
+ at file{@var{prefix}/etc/config.site}. To find out the names of the cache
+variables you need to set, see the documentation of the respective
+Autoconf macro. If the variables or their semantics are undocumented,
+you may need to look for shell variables with @samp{_cv_} in their names
+in the affected @command{configure} scripts, or in the Autoconf M4
+source code for those macros; but in that case, their name or semantics
+may change in a future Autoconf version.
+
+The cache file is careful to not override any variables set in the site
+files. Similarly, you should not override command-line options in the
+site files. Your code should check that variables such as @code{prefix}
+and @code{cache_file} have their default values (as set near the top of
+ at command{configure}) before changing them.
+
+Here is a sample file @file{/usr/share/local/@/gnu/share/@/config.site}. The
+command @samp{configure --prefix=/usr/share/local/gnu} would read this
+file (if @code{CONFIG_SITE} is not set to a different file).
+
+ at example
+# /usr/share/local/gnu/share/config.site for configure
+#
+# Change some defaults.
+test "$prefix" = NONE && prefix=/usr/share/local/gnu
+test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu
+test "$sharedstatedir" = '$@{prefix@}/com' && sharedstatedir=/var
+test "$localstatedir" = '$@{prefix@}/var' && localstatedir=/var
+
+# Give Autoconf 2.x generated configure scripts a shared default
+# cache file for feature test results, architecture-specific.
+if test "$cache_file" = /dev/null; then
+ cache_file="$prefix/var/config.cache"
+ # A cache file is only valid for one C compiler.
+ CC=gcc
+fi
+ at end example
+
+ at c Leave this use of ``File system'' rendered as one word, but
+ at c slightly obfuscated so as not to trigger the syntax-check prohibition.
+ at cindex File@/system Hierarchy Standard
+ at cindex FHS
+
+Another use of @file{config.site} is for priming the directory variables
+ at c ``File system'', but slightly obfuscated, as above.
+in a manner consistent with the File@/system Hierarchy Standard
+(FHS). Once the following file is installed at
+ at file{/usr/share/config.site}, a user can execute simply
+ at code{./configure --prefix=/usr} to get all the directories chosen in
+the locations recommended by FHS.
+
+ at example
+# /usr/share/config.site for FHS defaults when installing below /usr,
+# and the respective settings were not changed on the command line.
+if test "$prefix" = /usr; then
+ test "$sysconfdir" = '$@{prefix@}/etc' && sysconfdir=/etc
+ test "$sharedstatedir" = '$@{prefix@}/com' && sharedstatedir=/var
+ test "$localstatedir" = '$@{prefix@}/var' && localstatedir=/var
+fi
+ at end example
+
+ at cindex @file{lib64}
+ at cindex 64-bit libraries
+Likewise, on platforms where 64-bit libraries are built by default, then
+installed in @file{/usr/local/@/lib64} instead of @file{/usr/local/@/lib},
+it is appropriate to install @file{/usr/local/@/share/config.site}:
+
+ at example
+# /usr/local/share/config.site for platforms that prefer
+# the directory /usr/local/lib64 over /usr/local/lib.
+test "$libdir" = '$@{exec_prefix@}/lib' && libdir='$@{exec_prefix@}/lib64'
+ at end example
+
+
+ at c ============================================== Running configure Scripts.
+
+ at node Running configure Scripts
+ at chapter Running @command{configure} Scripts
+ at cindex @command{configure}
+
+Below are instructions on how to configure a package that uses a
+ at command{configure} script, suitable for inclusion as an @file{INSTALL}
+file in the package. A plain-text version of @file{INSTALL} which you
+may use comes with Autoconf.
+
+ at menu
+* 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 @command{configure}
+* Defining Variables:: Specifying the compiler etc.
+* configure Invocation:: Changing how @command{configure} runs
+ at end menu
+
+ at set autoconf
+ at include install.texi
+
+
+ at c ============================================== config.status Invocation
+
+ at node config.status Invocation
+ at chapter config.status Invocation
+ at cindex @command{config.status}
+
+The @command{configure} script creates a file named @file{config.status},
+which actually configures, @dfn{instantiates}, the template files. It
+also records the configuration options that were specified when the
+package was last configured in case reconfiguring is needed.
+
+Synopsis:
+ at example
+./config.status @ovar{option}@dots{} @ovar{tag}@dots{}
+ at end example
+
+It configures each @var{tag}; if none are specified, all the templates
+are instantiated. A @var{tag} refers to a file or other tag associated
+with a configuration action, as specified by an @code{AC_CONFIG_ at var{ITEMS}}
+macro (@pxref{Configuration Actions}). The files must be specified
+without their dependencies, as in
+
+ at example
+./config.status foobar
+ at end example
+
+ at noindent
+not
+
+ at example
+./config.status foobar:foo.in:bar.in
+ at end example
+
+The supported options are:
+
+ at table @option
+ at item --help
+ at itemx -h
+Print a summary of the command line options, the list of the template
+files, and exit.
+
+ at item --version
+ at itemx -V
+Print the version number of Autoconf and the configuration settings,
+and exit.
+
+ at item --config
+Print the configuration settings in reusable way, quoted for the shell,
+and exit. For example, for a debugging build that otherwise reuses the
+configuration from a different build directory @var{build-dir} of a
+package in @var{src-dir}, you could use the following:
+
+ at example
+args=`@var{build-dir}/config.status --config`
+eval @var{src-dir}/configure "$args" CFLAGS=-g --srcdir=@var{src-dir}
+ at end example
+
+ at noindent
+Note that it may be necessary to override a @option{--srcdir} setting
+that was saved in the configuration, if the arguments are used in a
+different build directory.
+
+ at item --silent
+ at itemx --quiet
+ at itemx -q
+Do not print progress messages.
+
+ at item --debug
+ at itemx -d
+Don't remove the temporary files.
+
+ at item --file=@var{file}[:@var{template}]
+Require that @var{file} be instantiated as if
+ at samp{AC_CONFIG_FILES(@var{file}:@var{template})} was used. Both
+ at var{file} and @var{template} may be @samp{-} in which case the standard
+output and/or standard input, respectively, is used. If a
+ at var{template} file name is relative, it is first looked for in the build
+tree, and then in the source tree. @xref{Configuration Actions}, for
+more details.
+
+This option and the following ones provide one way for separately
+distributed packages to share the values computed by @command{configure}.
+Doing so can be useful if some of the packages need a superset of the
+features that one of them, perhaps a common library, does. These
+options allow a @file{config.status} file to create files other than the
+ones that its @file{configure.ac} specifies, so it can be used for a
+different package, or for extracting a subset of values. For example,
+
+ at example
+echo '@@CC@@' | ./config.status --file=-
+ at end example
+
+ at noindent
+provides the value of @code{@@CC@@} on standard output.
+
+ at item --header=@var{file}[:@var{template}]
+Same as @option{--file} above, but with @samp{AC_CONFIG_HEADERS}.
+
+ at item --recheck
+Ask @file{config.status} to update itself and exit (no instantiation).
+This option is useful if you change @command{configure}, so that the
+results of some tests might be different from the previous run. The
+ at option{--recheck} option reruns @command{configure} with the same arguments
+you used before, plus the @option{--no-create} option, which prevents
+ at command{configure} from running @file{config.status} and creating
+ at file{Makefile} and other files, and the @option{--no-recursion} option,
+which prevents @command{configure} from running other @command{configure}
+scripts in subdirectories. (This is so other Make rules can
+run @file{config.status} when it changes; @pxref{Automatic Remaking},
+for an example).
+ at end table
+
+ at file{config.status} checks several optional environment variables that
+can alter its behavior:
+
+ at anchor{CONFIG_SHELL}
+ at defvar CONFIG_SHELL
+ at evindex CONFIG_SHELL
+The shell with which to run @command{configure}. It must be
+Bourne-compatible, and the absolute name of the shell should be passed.
+The default is a shell that supports @code{LINENO} if available, and
+ at file{/bin/sh} otherwise.
+ at end defvar
+
+ at defvar CONFIG_STATUS
+ at evindex CONFIG_STATUS
+The file name to use for the shell script that records the
+configuration. The default is @file{./config.status}. This variable is
+useful when one package uses parts of another and the @command{configure}
+scripts shouldn't be merged because they are maintained separately.
+ at end defvar
+
+You can use @file{./config.status} in your makefiles. For example, in
+the dependencies given above (@pxref{Automatic Remaking}),
+ at file{config.status} is run twice when @file{configure.ac} has changed.
+If that bothers you, you can make each run only regenerate the files for
+that rule:
+ at example
+ at group
+config.h: stamp-h
+stamp-h: config.h.in config.status
+ ./config.status config.h
+ echo > stamp-h
+
+Makefile: Makefile.in config.status
+ ./config.status Makefile
+ at end group
+ at end example
+
+The calling convention of @file{config.status} has changed; see
+ at ref{Obsolete config.status Use}, for details.
+
+
+ at c =================================================== Obsolete Constructs
+
+ at node Obsolete Constructs
+ at chapter Obsolete Constructs
+ at cindex Obsolete constructs
+
+Autoconf changes, and throughout the years some constructs have been
+obsoleted. Most of the changes involve the macros, but in some cases
+the tools themselves, or even some concepts, are now considered
+obsolete.
+
+You may completely skip this chapter if you are new to Autoconf. Its
+intention is mainly to help maintainers updating their packages by
+understanding how to move to more modern constructs.
+
+ at menu
+* Obsolete config.status Use:: Obsolete convention for @command{config.status}
+* acconfig Header:: Additional entries in @file{config.h.in}
+* autoupdate Invocation:: Automatic update of @file{configure.ac}
+* Obsolete Macros:: Backward compatibility macros
+* Autoconf 1:: Tips for upgrading your files
+* Autoconf 2.13:: Some fresher tips
+ at end menu
+
+ at node Obsolete config.status Use
+ at section Obsolete @file{config.status} Invocation
+
+ at file{config.status} now supports arguments to specify the files to
+instantiate; see @ref{config.status Invocation}, for more details.
+Before, environment variables had to be used.
+
+ at defvar CONFIG_COMMANDS
+ at evindex CONFIG_COMMANDS
+The tags of the commands to execute. The default is the arguments given
+to @code{AC_OUTPUT} and @code{AC_CONFIG_COMMANDS} in
+ at file{configure.ac}.
+ at end defvar
+
+ at defvar CONFIG_FILES
+ at evindex CONFIG_FILES
+The files in which to perform @samp{@@@var{variable}@@} substitutions.
+The default is the arguments given to @code{AC_OUTPUT} and
+ at code{AC_CONFIG_FILES} in @file{configure.ac}.
+ at end defvar
+
+ at defvar CONFIG_HEADERS
+ at evindex CONFIG_HEADERS
+The files in which to substitute C @code{#define} statements. The
+default is the arguments given to @code{AC_CONFIG_HEADERS}; if that
+macro was not called, @file{config.status} ignores this variable.
+ at end defvar
+
+ at defvar CONFIG_LINKS
+ at evindex CONFIG_LINKS
+The symbolic links to establish. The default is the arguments given to
+ at code{AC_CONFIG_LINKS}; if that macro was not called,
+ at file{config.status} ignores this variable.
+ at end defvar
+
+In @ref{config.status Invocation}, using this old interface, the example
+would be:
+
+ at example
+ at group
+config.h: stamp-h
+stamp-h: config.h.in config.status
+ CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_FILES= \
+ CONFIG_HEADERS=config.h ./config.status
+ echo > stamp-h
+
+Makefile: Makefile.in config.status
+ CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_HEADERS= \
+ CONFIG_FILES=Makefile ./config.status
+ at end group
+ at end example
+
+ at noindent
+(If @file{configure.ac} does not call @code{AC_CONFIG_HEADERS}, there is
+no need to set @code{CONFIG_HEADERS} in the @command{make} rules. Equally
+for @code{CONFIG_COMMANDS}, etc.)
+
+
+ at node acconfig Header
+ at section @file{acconfig.h}
+
+ at cindex @file{acconfig.h}
+ at cindex @file{config.h.top}
+ at cindex @file{config.h.bot}
+
+In order to produce @file{config.h.in}, @command{autoheader} needs to
+build or to find templates for each symbol. Modern releases of Autoconf
+use @code{AH_VERBATIM} and @code{AH_TEMPLATE} (@pxref{Autoheader
+Macros}), but in older releases a file, @file{acconfig.h}, contained the
+list of needed templates. @command{autoheader} copied comments and
+ at code{#define} and @code{#undef} statements from @file{acconfig.h} in
+the current directory, if present. This file used to be mandatory if
+you @code{AC_DEFINE} any additional symbols.
+
+Modern releases of Autoconf also provide @code{AH_TOP} and
+ at code{AH_BOTTOM} if you need to prepend/append some information to
+ at file{config.h.in}. Ancient versions of Autoconf had a similar feature:
+if @file{./acconfig.h} contains the string @samp{@@TOP@@},
+ at command{autoheader} copies the lines before the line containing
+ at samp{@@TOP@@} into the top of the file that it generates. Similarly,
+if @file{./acconfig.h} contains the string @samp{@@BOTTOM@@},
+ at command{autoheader} copies the lines after that line to the end of the
+file it generates. Either or both of those strings may be omitted. An
+even older alternate way to produce the same effect in ancient versions
+of Autoconf is to create the files @file{@var{file}.top} (typically
+ at file{config.h.top}) and/or @file{@var{file}.bot} in the current
+directory. If they exist, @command{autoheader} copies them to the
+beginning and end, respectively, of its output.
+
+In former versions of Autoconf, the files used in preparing a software
+package for distribution were:
+ at example
+ at group
+configure.ac --. .------> autoconf* -----> configure
+ +---+
+[aclocal.m4] --+ `---.
+[acsite.m4] ---' |
+ +--> [autoheader*] -> [config.h.in]
+[acconfig.h] ----. |
+ +-----'
+[config.h.top] --+
+[config.h.bot] --'
+ at end group
+ at end example
+
+Using only the @code{AH_} macros, @file{configure.ac} should be
+self-contained, and should not depend upon @file{acconfig.h} etc.
+
+
+ at node autoupdate Invocation
+ at section Using @command{autoupdate} to Modernize @file{configure.ac}
+ at cindex @command{autoupdate}
+
+The @command{autoupdate} program updates a @file{configure.ac} file that
+calls Autoconf macros by their old names to use the current macro names.
+In version 2 of Autoconf, most of the macros were renamed to use a more
+uniform and descriptive naming scheme. @xref{Macro Names}, for a
+description of the new scheme. Although the old names still work
+(@pxref{Obsolete Macros}, for a list of the old macros and the corresponding
+new names), you can make your @file{configure.ac} files more readable
+and make it easier to use the current Autoconf documentation if you
+update them to use the new macro names.
+
+ at evindex SIMPLE_BACKUP_SUFFIX
+If given no arguments, @command{autoupdate} updates @file{configure.ac},
+backing up the original version with the suffix @file{~} (or the value
+of the environment variable @code{SIMPLE_BACKUP_SUFFIX}, if that is
+set). If you give @command{autoupdate} an argument, it reads that file
+instead of @file{configure.ac} and writes the updated file to the
+standard output.
+
+ at noindent
+ at command{autoupdate} accepts the following options:
+
+ at table @option
+ at item --help
+ at itemx -h
+Print a summary of the command line options and exit.
+
+ at item --version
+ at itemx -V
+Print the version number of Autoconf and exit.
+
+ at item --verbose
+ at itemx -v
+Report processing steps.
+
+ at item --debug
+ at itemx -d
+Don't remove the temporary files.
+
+ at item --force
+ at itemx -f
+Force the update even if the file has not changed. Disregard the cache.
+
+ at item --include=@var{dir}
+ at itemx -I @var{dir}
+Also look for input files in @var{dir}. Multiple invocations accumulate.
+Directories are browsed from last to first.
+
+ at item --prepend-include=@var{dir}
+ at itemx -B @var{dir}
+Prepend directory @var{dir} to the search path. This is used to include
+the language-specific files before any third-party macros.
+ at end table
+
+ at node Obsolete Macros
+ at section Obsolete Macros
+
+Several macros are obsoleted in Autoconf, for various reasons (typically
+they failed to quote properly, couldn't be extended for more recent
+issues, etc.). They are still supported, but deprecated: their use
+should be avoided.
+
+During the jump from Autoconf version 1 to version 2, most of the
+macros were renamed to use a more uniform and descriptive naming scheme,
+but their signature did not change. @xref{Macro Names}, for a
+description of the new naming scheme. Below, if there is just the mapping
+from old names to new names for these macros, the reader is invited to
+refer to the definition of the new macro for the signature and the
+description.
+
+ at defmac AC_AIX
+ at acindex{AIX}
+ at cvindex _ALL_SOURCE
+This macro is a platform-specific subset of
+ at code{AC_USE_SYSTEM_EXTENSIONS} (@pxref{AC_USE_SYSTEM_EXTENSIONS}).
+ at end defmac
+
+ at defmac AC_ALLOCA
+ at acindex{ALLOCA}
+Replaced by @code{AC_FUNC_ALLOCA} (@pxref{AC_FUNC_ALLOCA}).
+ at end defmac
+
+ at defmac AC_ARG_ARRAY
+ at acindex{ARG_ARRAY}
+Removed because of limited usefulness.
+ at end defmac
+
+ at defmac AC_C_CROSS
+ at acindex{C_CROSS}
+This macro is obsolete; it does nothing.
+ at end defmac
+
+ at defmac AC_C_LONG_DOUBLE
+ at acindex{C_LONG_DOUBLE}
+ at cvindex HAVE_LONG_DOUBLE
+If the C compiler supports a working @code{long double} type with more
+range or precision than the @code{double} type, define
+ at code{HAVE_LONG_DOUBLE}.
+
+You should use @code{AC_TYPE_LONG_DOUBLE} or
+ at code{AC_TYPE_LONG_DOUBLE_WIDER} instead. @xref{Particular Types}.
+ at end defmac
+
+ at defmac AC_CANONICAL_SYSTEM
+ at acindex{CANONICAL_SYSTEM}
+Determine the system type and set output variables to the names of the
+canonical system types. @xref{Canonicalizing}, for details about the
+variables this macro sets.
+
+The user is encouraged to use either @code{AC_CANONICAL_BUILD}, or
+ at code{AC_CANONICAL_HOST}, or @code{AC_CANONICAL_TARGET}, depending on
+the needs. Using @code{AC_CANONICAL_TARGET} is enough to run the two
+other macros (@pxref{Canonicalizing}).
+ at end defmac
+
+ at defmac AC_CHAR_UNSIGNED
+ at acindex{CHAR_UNSIGNED}
+Replaced by @code{AC_C_CHAR_UNSIGNED} (@pxref{AC_C_CHAR_UNSIGNED}).
+ at end defmac
+
+ at defmac AC_CHECK_TYPE (@var{type}, @var{default})
+ at acindex{CHECK_TYPE}
+Autoconf, up to 2.13, used to provide this version of
+ at code{AC_CHECK_TYPE}, deprecated because of its flaws. First, although
+it is a member of the @code{CHECK} clan, it does
+more than just checking. Secondly, missing types are defined
+using @code{#define}, not @code{typedef}, and this can lead to
+problems in the case of pointer types.
+
+This use of @code{AC_CHECK_TYPE} is obsolete and discouraged; see
+ at ref{Generic Types}, for the description of the current macro.
+
+If the type @var{type} is not defined, define it to be the C (or C++)
+builtin type @var{default}, e.g., @samp{short int} or @samp{unsigned int}.
+
+This macro is equivalent to:
+
+ at example
+AC_CHECK_TYPE([@var{type}], [],
+ [AC_DEFINE_UNQUOTED([@var{type}], [@var{default}],
+ [Define to `@var{default}'
+ if <sys/types.h> does not define.])])
+ at end example
+
+In order to keep backward compatibility, the two versions of
+ at code{AC_CHECK_TYPE} are implemented, selected using these heuristics:
+
+ at enumerate
+ at item
+If there are three or four arguments, the modern version is used.
+
+ at item
+If the second argument appears to be a C or C++ type, then the
+obsolete version is used. This happens if the argument is a C or C++
+ at emph{builtin} type or a C identifier ending in @samp{_t}, optionally
+followed by one of @samp{[(* } and then by a string of zero or more
+characters taken from the set @samp{[]()* _a-zA-Z0-9}.
+
+ at item
+If the second argument is spelled with the alphabet of valid C and C++
+types, the user is warned and the modern version is used.
+
+ at item
+Otherwise, the modern version is used.
+ at end enumerate
+
+ at noindent
+You are encouraged either to use a valid builtin type, or to use the
+equivalent modern code (see above), or better yet, to use
+ at code{AC_CHECK_TYPES} together with
+
+ at example
+#ifndef HAVE_LOFF_T
+typedef loff_t off_t;
+#endif
+ at end example
+ at end defmac
+ at c end of AC_CHECK_TYPE
+
+ at defmac AC_CHECKING (@var{feature-description})
+ at acindex{CHECKING}
+Same as
+
+ at example
+AC_MSG_NOTICE([checking @var{feature-description}@dots{}]
+ at end example
+
+ at noindent
+ at xref{AC_MSG_NOTICE}.
+ at end defmac
+
+ at defmac AC_COMPILE_CHECK (@var{echo-text}, @var{includes}, @
+ @var{function-body}, @var{action-if-true}, @ovar{action-if-false})
+ at acindex{COMPILE_CHECK}
+This is an obsolete version of @code{AC_TRY_COMPILE} itself replaced by
+ at code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}), with the
+addition that it prints @samp{checking for @var{echo-text}} to the
+standard output first, if @var{echo-text} is non-empty. Use
+ at code{AC_MSG_CHECKING} and @code{AC_MSG_RESULT} instead to print
+messages (@pxref{Printing Messages}).
+ at end defmac
+
+ at defmac AC_CONST
+ at acindex{CONST}
+Replaced by @code{AC_C_CONST} (@pxref{AC_C_CONST}).
+ at end defmac
+
+ at defmac AC_CROSS_CHECK
+ at acindex{CROSS_CHECK}
+Same as @code{AC_C_CROSS}, which is obsolete too, and does nothing
+ at code{:-)}.
+ at end defmac
+
+ at defmac AC_CYGWIN
+ at acindex{CYGWIN}
+ at evindex CYGWIN
+Check for the Cygwin environment in which case the shell variable
+ at code{CYGWIN} is set to @samp{yes}. Don't use this macro, the dignified
+means to check the nature of the host is using @code{AC_CANONICAL_HOST}
+(@pxref{Canonicalizing}). As a matter of fact this macro is defined as:
+
+ at example
+AC_REQUIRE([AC_CANONICAL_HOST])[]dnl
+case $host_os in
+ *cygwin* ) CYGWIN=yes;;
+ * ) CYGWIN=no;;
+esac
+ at end example
+
+Beware that the variable @env{CYGWIN} has a special meaning when
+running Cygwin, and should not be changed. That's yet another reason
+not to use this macro.
+ at end defmac
+
+ at defmac AC_DECL_SYS_SIGLIST
+ at acindex{DECL_SYS_SIGLIST}
+ at cvindex SYS_SIGLIST_DECLARED
+Same as:
+
+ at example
+AC_CHECK_DECLS([sys_siglist], [], [],
+[#include <signal.h>
+/* NetBSD declares sys_siglist in unistd.h. */
+#ifdef HAVE_UNISTD_H
+# include <unistd.h>
+#endif
+])
+ at end example
+
+ at noindent
+ at xref{AC_CHECK_DECLS}.
+ at end defmac
+
+ at defmac AC_DECL_YYTEXT
+ at acindex{DECL_YYTEXT}
+Does nothing, now integrated in @code{AC_PROG_LEX} (@pxref{AC_PROG_LEX}).
+ at end defmac
+
+ at defmac AC_DIR_HEADER
+ at acindex{DIR_HEADER}
+ at cvindex DIRENT
+ at cvindex SYSNDIR
+ at cvindex SYSDIR
+ at cvindex NDIR
+Like calling @code{AC_FUNC_CLOSEDIR_VOID}
+(@pxref{AC_FUNC_CLOSEDIR_VOID}) and @code{AC_HEADER_DIRENT}
+(@pxref{AC_HEADER_DIRENT}),
+but defines a different set of C preprocessor macros to indicate which
+header file is found:
+
+ at multitable {@file{sys/ndir.h}} {Old Symbol} {@code{HAVE_SYS_NDIR_H}}
+ at item Header @tab Old Symbol @tab New Symbol
+ at item @file{dirent.h} @tab @code{DIRENT} @tab @code{HAVE_DIRENT_H}
+ at item @file{sys/ndir.h} @tab @code{SYSNDIR} @tab @code{HAVE_SYS_NDIR_H}
+ at item @file{sys/dir.h} @tab @code{SYSDIR} @tab @code{HAVE_SYS_DIR_H}
+ at item @file{ndir.h} @tab @code{NDIR} @tab @code{HAVE_NDIR_H}
+ at end multitable
+ at end defmac
+
+ at defmac AC_DYNIX_SEQ
+ at acindex{DYNIX_SEQ}
+If on DYNIX/ptx, add @option{-lseq} to output variable
+ at code{LIBS}. This macro used to be defined as
+
+ at example
+AC_CHECK_LIB([seq], [getmntent], [LIBS="-lseq $LIBS"])
+ at end example
+
+ at noindent
+now it is just @code{AC_FUNC_GETMNTENT} (@pxref{AC_FUNC_GETMNTENT}).
+ at end defmac
+
+ at defmac AC_EXEEXT
+ at acindex{EXEEXT}
+ at ovindex EXEEXT
+Defined the output variable @code{EXEEXT} based on the output of the
+compiler, which is now done automatically. Typically set to empty
+string if Posix and @samp{.exe} if a DOS variant.
+ at end defmac
+
+ at defmac AC_EMXOS2
+ at acindex{EMXOS2}
+Similar to @code{AC_CYGWIN} but checks for the EMX environment on OS/2
+and sets @code{EMXOS2}. Don't use this macro, the dignified means to
+check the nature of the host is using @code{AC_CANONICAL_HOST}
+(@pxref{Canonicalizing}).
+ at end defmac
+
+ at defmac AC_ENABLE (@var{feature}, @var{action-if-given}, @
+ @ovar{action-if-not-given})
+ at acindex{ENABLE}
+This is an obsolete version of @code{AC_ARG_ENABLE} that does not
+support providing a help string (@pxref{AC_ARG_ENABLE}).
+ at end defmac
+
+ at defmac AC_ERROR
+ at acindex{ERROR}
+Replaced by @code{AC_MSG_ERROR} (@pxref{AC_MSG_ERROR}).
+ at end defmac
+
+ at defmac AC_FIND_X
+ at acindex{FIND_X}
+Replaced by @code{AC_PATH_X} (@pxref{AC_PATH_X}).
+ at end defmac
+
+ at defmac AC_FIND_XTRA
+ at acindex{FIND_XTRA}
+Replaced by @code{AC_PATH_XTRA} (@pxref{AC_PATH_XTRA}).
+ at end defmac
+
+ at defmac AC_FOREACH
+ at acindex{FOREACH}
+Replaced by @code{m4_foreach_w} (@pxref{m4_foreach_w}).
+ at end defmac
+
+ at defmac AC_FUNC_CHECK
+ at acindex{FUNC_CHECK}
+Replaced by @code{AC_CHECK_FUNC} (@pxref{AC_CHECK_FUNC}).
+ at end defmac
+
+ at anchor{AC_FUNC_SETVBUF_REVERSED}
+ at defmac AC_FUNC_SETVBUF_REVERSED
+ at acindex{FUNC_SETVBUF_REVERSED}
+ at cvindex SETVBUF_REVERSED
+ at c @fuindex setvbuf
+ at prindex @code{setvbuf}
+Do nothing. Formerly, this macro checked whether @code{setvbuf} takes
+the buffering type as its second argument and the buffer pointer as the
+third, instead of the other way around, and defined
+ at code{SETVBUF_REVERSED}. However, the last systems to have the problem
+were those based on SVR2, which became obsolete in 1987, and the macro
+is no longer needed.
+ at end defmac
+
+ at defmac AC_FUNC_WAIT3
+ at acindex{FUNC_WAIT3}
+ at cvindex HAVE_WAIT3
+ at c @fuindex wait3
+ at prindex @code{wait3}
+If @code{wait3} is found and fills in the contents of its third argument
+(a @samp{struct rusage *}), which HP-UX does not do, define
+ at code{HAVE_WAIT3}.
+
+These days portable programs should use @code{waitpid}, not
+ at code{wait3}, as @code{wait3} has been removed from Posix.
+ at end defmac
+
+ at defmac AC_GCC_TRADITIONAL
+ at acindex{GCC_TRADITIONAL}
+Replaced by @code{AC_PROG_GCC_TRADITIONAL} (@pxref{AC_PROG_GCC_TRADITIONAL}).
+ at end defmac
+
+ at defmac AC_GETGROUPS_T
+ at acindex{GETGROUPS_T}
+Replaced by @code{AC_TYPE_GETGROUPS} (@pxref{AC_TYPE_GETGROUPS}).
+ at end defmac
+
+ at defmac AC_GETLOADAVG
+ at acindex{GETLOADAVG}
+Replaced by @code{AC_FUNC_GETLOADAVG} (@pxref{AC_FUNC_GETLOADAVG}).
+ at end defmac
+
+ at defmac AC_GNU_SOURCE
+ at acindex{GNU_SOURCE}
+ at cvindex _GNU_SOURCE
+This macro is a platform-specific subset of
+ at code{AC_USE_SYSTEM_EXTENSIONS} (@pxref{AC_USE_SYSTEM_EXTENSIONS}).
+ at end defmac
+
+ at defmac AC_HAVE_FUNCS
+ at acindex{HAVE_FUNCS}
+Replaced by @code{AC_CHECK_FUNCS} (@pxref{AC_CHECK_FUNCS}).
+ at end defmac
+
+ at defmac AC_HAVE_HEADERS
+ at acindex{HAVE_HEADERS}
+Replaced by @code{AC_CHECK_HEADERS} (@pxref{AC_CHECK_HEADERS}).
+ at end defmac
+
+ at defmac AC_HAVE_LIBRARY (@var{library}, @ovar{action-if-found}, @
+ @ovar{action-if-not-found}, @ovar{other-libraries})
+ at acindex{HAVE_LIBRARY}
+This macro is equivalent to calling @code{AC_CHECK_LIB} with a
+ at var{function} argument of @code{main}. In addition, @var{library} can
+be written as any of @samp{foo}, @option{-lfoo}, or @samp{libfoo.a}. In
+all of those cases, the compiler is passed @option{-lfoo}. However,
+ at var{library} cannot be a shell variable; it must be a literal name.
+ at xref{AC_CHECK_LIB}.
+ at end defmac
+
+ at defmac AC_HAVE_POUNDBANG
+ at acindex{HAVE_POUNDBANG}
+Replaced by @code{AC_SYS_INTERPRETER} (@pxref{AC_SYS_INTERPRETER}).
+ at end defmac
+
+ at defmac AC_HEADER_CHECK
+ at acindex{HEADER_CHECK}
+Replaced by @code{AC_CHECK_HEADER} (@pxref{AC_CHECK_HEADER}).
+ at end defmac
+
+ at defmac AC_HEADER_EGREP
+ at acindex{HEADER_EGREP}
+Replaced by @code{AC_EGREP_HEADER} (@pxref{AC_EGREP_HEADER}).
+ at end defmac
+
+ at defmac AC_HELP_STRING
+ at acindex{HELP_STRING}
+Replaced by @code{AS_HELP_STRING} (@pxref{AS_HELP_STRING}).
+ at end defmac
+
+ at defmac AC_INIT (@var{unique-file-in-source-dir})
+ at acindex{INIT}
+Formerly @code{AC_INIT} used to have a single argument, and was
+equivalent to:
+
+ at example
+AC_INIT
+AC_CONFIG_SRCDIR(@var{unique-file-in-source-dir})
+ at end example
+See @ref{AC_INIT} and @ref{AC_CONFIG_SRCDIR}.
+ at end defmac
+
+ at defmac AC_INLINE
+ at acindex{INLINE}
+Replaced by @code{AC_C_INLINE} (@pxref{AC_C_INLINE}).
+ at end defmac
+
+ at defmac AC_INT_16_BITS
+ at acindex{INT_16_BITS}
+ at cvindex INT_16_BITS
+If the C type @code{int} is 16 bits wide, define @code{INT_16_BITS}.
+Use @samp{AC_CHECK_SIZEOF(int)} instead (@pxref{AC_CHECK_SIZEOF}).
+ at end defmac
+
+ at defmac AC_IRIX_SUN
+ at acindex{IRIX_SUN}
+If on IRIX (Silicon Graphics Unix), add @option{-lsun} to output
+ at code{LIBS}. If you were using it to get @code{getmntent}, use
+ at code{AC_FUNC_GETMNTENT} instead. If you used it for the NIS versions
+of the password and group functions, use @samp{AC_CHECK_LIB(sun,
+getpwnam)}. Up to Autoconf 2.13, it used to be
+
+ at example
+AC_CHECK_LIB([sun], [getmntent], [LIBS="-lsun $LIBS"])
+ at end example
+
+ at noindent
+now it is defined as
+
+ at example
+AC_FUNC_GETMNTENT
+AC_CHECK_LIB([sun], [getpwnam])
+ at end example
+
+ at noindent
+See @ref{AC_FUNC_GETMNTENT} and @ref{AC_CHECK_LIB}.
+ at end defmac
+
+ at defmac AC_ISC_POSIX
+ at acindex{ISC_POSIX}
+ at ovindex LIBS
+This macro adds @option{-lcposix} to output variable @code{LIBS} if
+necessary for Posix facilities. Sun dropped support for the obsolete
+INTERACTIVE Systems Corporation Unix on 2006-07-23. New programs
+need not use this macro. It is implemented as
+ at code{AC_SEARCH_LIBS([strerror], [cposix])} (@pxref{AC_SEARCH_LIBS}).
+ at end defmac
+
+ at defmac AC_LANG_C
+ at acindex{LANG_C}
+Same as @samp{AC_LANG([C])} (@pxref{AC_LANG}).
+ at end defmac
+
+ at defmac AC_LANG_CPLUSPLUS
+ at acindex{LANG_CPLUSPLUS}
+Same as @samp{AC_LANG([C++])} (@pxref{AC_LANG}).
+ at end defmac
+
+ at defmac AC_LANG_FORTRAN77
+ at acindex{LANG_FORTRAN77}
+Same as @samp{AC_LANG([Fortran 77])} (@pxref{AC_LANG}).
+ at end defmac
+
+ at defmac AC_LANG_RESTORE
+ at acindex{LANG_RESTORE}
+Select the @var{language} that is saved on the top of the stack, as set
+by @code{AC_LANG_SAVE}, remove it from the stack, and call
+ at code{AC_LANG(@var{language})}. @xref{Language Choice}, for the
+preferred way to change languages.
+ at end defmac
+
+ at defmac AC_LANG_SAVE
+ at acindex{LANG_SAVE}
+Remember the current language (as set by @code{AC_LANG}) on a stack.
+The current language does not change. @code{AC_LANG_PUSH} is preferred
+(@pxref{AC_LANG_PUSH}).
+ at end defmac
+
+ at defmac AC_LINK_FILES (@var{source}@dots{}, @var{dest}@dots{})
+ at acindex{LINK_FILES}
+This is an obsolete version of @code{AC_CONFIG_LINKS}
+(@pxref{AC_CONFIG_LINKS}. An updated version of:
+
+ at example
+AC_LINK_FILES(config/$machine.h config/$obj_format.h,
+ host.h object.h)
+ at end example
+
+ at noindent
+is:
+
+ at example
+AC_CONFIG_LINKS([host.h:config/$machine.h
+ object.h:config/$obj_format.h])
+ at end example
+ at end defmac
+
+ at defmac AC_LN_S
+ at acindex{LN_S}
+Replaced by @code{AC_PROG_LN_S} (@pxref{AC_PROG_LN_S}).
+ at end defmac
+
+ at defmac AC_LONG_64_BITS
+ at acindex{LONG_64_BITS}
+ at cvindex LONG_64_BITS
+Define @code{LONG_64_BITS} if the C type @code{long int} is 64 bits wide.
+Use the generic macro @samp{AC_CHECK_SIZEOF([long int])} instead
+(@pxref{AC_CHECK_SIZEOF}).
+ at end defmac
+
+ at defmac AC_LONG_DOUBLE
+ at acindex{LONG_DOUBLE}
+If the C compiler supports a working @code{long double} type with more
+range or precision than the @code{double} type, define
+ at code{HAVE_LONG_DOUBLE}.
+
+You should use @code{AC_TYPE_LONG_DOUBLE} or
+ at code{AC_TYPE_LONG_DOUBLE_WIDER} instead. @xref{Particular Types}.
+ at end defmac
+
+ at defmac AC_LONG_FILE_NAMES
+ at acindex{LONG_FILE_NAMES}
+Replaced by
+ at example
+AC_SYS_LONG_FILE_NAMES
+ at end example
+ at noindent
+ at xref{AC_SYS_LONG_FILE_NAMES}.
+ at end defmac
+
+ at defmac AC_MAJOR_HEADER
+ at acindex{MAJOR_HEADER}
+Replaced by @code{AC_HEADER_MAJOR} (@pxref{AC_HEADER_MAJOR}).
+ at end defmac
+
+ at defmac AC_MEMORY_H
+ at acindex{MEMORY_H}
+ at cvindex NEED_MEMORY_H
+Used to define @code{NEED_MEMORY_H} if the @code{mem} functions were
+defined in @file{memory.h}. Today it is equivalent to
+ at samp{AC_CHECK_HEADERS([memory.h])} (@pxref{AC_CHECK_HEADERS}). Adjust
+your code to depend upon
+ at code{HAVE_MEMORY_H}, not @code{NEED_MEMORY_H}; see @ref{Standard
+Symbols}.
+ at end defmac
+
+ at defmac AC_MINGW32
+ at acindex{MINGW32}
+Similar to @code{AC_CYGWIN} but checks for the MinGW compiler
+environment and sets @code{MINGW32}. Don't use this macro, the
+dignified means to check the nature of the host is using
+ at code{AC_CANONICAL_HOST} (@pxref{Canonicalizing}).
+ at end defmac
+
+ at defmac AC_MINIX
+ at acindex{MINIX}
+ at cvindex _MINIX
+ at cvindex _POSIX_SOURCE
+ at cvindex _POSIX_1_SOURCE
+This macro is a platform-specific subset of
+ at code{AC_USE_SYSTEM_EXTENSIONS} (@pxref{AC_USE_SYSTEM_EXTENSIONS}).
+ at end defmac
+
+ at defmac AC_MINUS_C_MINUS_O
+ at acindex{MINUS_C_MINUS_O}
+Replaced by @code{AC_PROG_CC_C_O} (@pxref{AC_PROG_CC_C_O}).
+ at end defmac
+
+ at defmac AC_MMAP
+ at acindex{MMAP}
+Replaced by @code{AC_FUNC_MMAP} (@pxref{AC_FUNC_MMAP}).
+ at end defmac
+
+ at defmac AC_MODE_T
+ at acindex{MODE_T}
+Replaced by @code{AC_TYPE_MODE_T} (@pxref{AC_TYPE_MODE_T}).
+ at end defmac
+
+ at defmac AC_OBJEXT
+ at acindex{OBJEXT}
+ at ovindex OBJEXT
+Defined the output variable @code{OBJEXT} based on the output of the
+compiler, after .c files have been excluded. Typically set to @samp{o}
+if Posix, @samp{obj} if a DOS variant.
+Now the compiler checking macros handle
+this automatically.
+ at end defmac
+
+ at defmac AC_OBSOLETE (@var{this-macro-name}, @ovar{suggestion})
+ at acindex{OBSOLETE}
+Make M4 print a message to the standard error output warning that
+ at var{this-macro-name} is obsolete, and giving the file and line number
+where it was called. @var{this-macro-name} should be the name of the
+macro that is calling @code{AC_OBSOLETE}. If @var{suggestion} is given,
+it is printed at the end of the warning message; for example, it can be
+a suggestion for what to use instead of @var{this-macro-name}.
+
+For instance
+
+ at example
+AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl
+ at end example
+
+ at noindent
+You are encouraged to use @code{AU_DEFUN} instead, since it gives better
+services to the user (@pxref{AU_DEFUN}).
+ at end defmac
+
+ at defmac AC_OFF_T
+ at acindex{OFF_T}
+Replaced by @code{AC_TYPE_OFF_T} (@pxref{AC_TYPE_OFF_T}).
+ at end defmac
+
+ at defmac AC_OUTPUT (@ovar{file}@dots{}, @ovar{extra-cmds}, @ovar{init-cmds})
+ at acindex{OUTPUT}
+The use of @code{AC_OUTPUT} with arguments is deprecated. This obsoleted
+interface is equivalent to:
+
+ at example
+ at group
+AC_CONFIG_FILES(@var{file}@dots{})
+AC_CONFIG_COMMANDS([default],
+ @var{extra-cmds}, @var{init-cmds})
+AC_OUTPUT
+ at end group
+ at end example
+
+ at noindent
+See @ref{AC_CONFIG_FILES}, @ref{AC_CONFIG_COMMANDS}, and @ref{AC_OUTPUT}.
+ at end defmac
+
+ at defmac AC_OUTPUT_COMMANDS (@var{extra-cmds}, @ovar{init-cmds})
+ at acindex{OUTPUT_COMMANDS}
+Specify additional shell commands to run at the end of
+ at file{config.status}, and shell commands to initialize any variables
+from @command{configure}. This macro may be called multiple times. It is
+obsolete, replaced by @code{AC_CONFIG_COMMANDS} (@pxref{AC_CONFIG_COMMANDS}).
+
+Here is an unrealistic example:
+
+ at example
+fubar=27
+AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.],
+ [fubar=$fubar])
+AC_OUTPUT_COMMANDS([echo this is another, extra, bit],
+ [echo init bit])
+ at end example
+
+Aside from the fact that @code{AC_CONFIG_COMMANDS} requires an
+additional key, an important difference is that
+ at code{AC_OUTPUT_COMMANDS} is quoting its arguments twice, unlike
+ at code{AC_CONFIG_COMMANDS}. This means that @code{AC_CONFIG_COMMANDS}
+can safely be given macro calls as arguments:
+
+ at example
+AC_CONFIG_COMMANDS(foo, [my_FOO()])
+ at end example
+
+ at noindent
+Conversely, where one level of quoting was enough for literal strings
+with @code{AC_OUTPUT_COMMANDS}, you need two with
+ at code{AC_CONFIG_COMMANDS}. The following lines are equivalent:
+
+ at example
+ at group
+AC_OUTPUT_COMMANDS([echo "Square brackets: []"])
+AC_CONFIG_COMMANDS([default], [[echo "Square brackets: []"]])
+ at end group
+ at end example
+ at end defmac
+
+ at defmac AC_PID_T
+ at acindex{PID_T}
+Replaced by @code{AC_TYPE_PID_T} (@pxref{AC_TYPE_PID_T}).
+ at end defmac
+
+ at defmac AC_PREFIX
+ at acindex{PREFIX}
+Replaced by @code{AC_PREFIX_PROGRAM} (@pxref{AC_PREFIX_PROGRAM}).
+ at end defmac
+
+ at defmac AC_PROGRAMS_CHECK
+ at acindex{PROGRAMS_CHECK}
+Replaced by @code{AC_CHECK_PROGS} (@pxref{AC_CHECK_PROGS}).
+ at end defmac
+
+ at defmac AC_PROGRAMS_PATH
+ at acindex{PROGRAMS_PATH}
+Replaced by @code{AC_PATH_PROGS} (@pxref{AC_PATH_PROGS}).
+ at end defmac
+
+ at defmac AC_PROGRAM_CHECK
+ at acindex{PROGRAM_CHECK}
+Replaced by @code{AC_CHECK_PROG} (@pxref{AC_CHECK_PROG}).
+ at end defmac
+
+ at defmac AC_PROGRAM_EGREP
+ at acindex{PROGRAM_EGREP}
+Replaced by @code{AC_EGREP_CPP} (@pxref{AC_EGREP_CPP}).
+ at end defmac
+
+ at defmac AC_PROGRAM_PATH
+ at acindex{PROGRAM_PATH}
+Replaced by @code{AC_PATH_PROG} (@pxref{AC_PATH_PROG}).
+ at end defmac
+
+ at defmac AC_REMOTE_TAPE
+ at acindex{REMOTE_TAPE}
+Removed because of limited usefulness.
+ at end defmac
+
+ at defmac AC_RESTARTABLE_SYSCALLS
+ at acindex{RESTARTABLE_SYSCALLS}
+This macro was renamed @code{AC_SYS_RESTARTABLE_SYSCALLS}. However,
+these days portable programs should use @code{sigaction} with
+ at code{SA_RESTART} if they want restartable system calls. They should
+not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a
+system call is restartable is a dynamic issue, not a configuration-time
+issue.
+ at end defmac
+
+ at defmac AC_RETSIGTYPE
+ at acindex{RETSIGTYPE}
+Replaced by @code{AC_TYPE_SIGNAL} (@pxref{AC_TYPE_SIGNAL}), which itself
+is obsolete when assuming C89 or better.
+ at end defmac
+
+ at defmac AC_RSH
+ at acindex{RSH}
+Removed because of limited usefulness.
+ at end defmac
+
+ at defmac AC_SCO_INTL
+ at acindex{SCO_INTL}
+ at ovindex LIBS
+If on SCO Unix, add @option{-lintl} to output variable @code{LIBS}. This
+macro used to do this:
+
+ at example
+AC_CHECK_LIB([intl], [strftime], [LIBS="-lintl $LIBS"])
+ at end example
+
+ at noindent
+Now it just calls @code{AC_FUNC_STRFTIME} instead (@pxref{AC_FUNC_STRFTIME}).
+ at end defmac
+
+ at defmac AC_SETVBUF_REVERSED
+ at acindex{SETVBUF_REVERSED}
+Replaced by
+ at example
+AC_FUNC_SETVBUF_REVERSED
+ at end example
+ at noindent
+ at xref{AC_FUNC_SETVBUF_REVERSED}.
+ at end defmac
+
+ at defmac AC_SET_MAKE
+ at acindex{SET_MAKE}
+Replaced by @code{AC_PROG_MAKE_SET} (@pxref{AC_PROG_MAKE_SET}).
+ at end defmac
+
+ at defmac AC_SIZEOF_TYPE
+ at acindex{SIZEOF_TYPE}
+Replaced by @code{AC_CHECK_SIZEOF} (@pxref{AC_CHECK_SIZEOF}).
+ at end defmac
+
+ at defmac AC_SIZE_T
+ at acindex{SIZE_T}
+Replaced by @code{AC_TYPE_SIZE_T} (@pxref{AC_TYPE_SIZE_T}).
+ at end defmac
+
+ at defmac AC_STAT_MACROS_BROKEN
+ at acindex{STAT_MACROS_BROKEN}
+Replaced by @code{AC_HEADER_STAT} (@pxref{AC_HEADER_STAT}).
+ at end defmac
+
+ at defmac AC_STDC_HEADERS
+ at acindex{STDC_HEADERS}
+Replaced by @code{AC_HEADER_STDC} (@pxref{AC_HEADER_STDC}).
+ at end defmac
+
+ at defmac AC_STRCOLL
+ at acindex{STRCOLL}
+Replaced by @code{AC_FUNC_STRCOLL} (@pxref{AC_FUNC_STRCOLL}).
+ at end defmac
+
+ at defmac AC_STRUCT_ST_BLKSIZE
+ at acindex{STRUCT_ST_BLKSIZE}
+ at cvindex HAVE_STRUCT_STAT_ST_BLKSIZE
+ at cvindex HAVE_ST_BLKSIZE
+If @code{struct stat} contains an @code{st_blksize} member, define
+ at code{HAVE_STRUCT_STAT_ST_BLKSIZE}. The former name,
+ at code{HAVE_ST_BLKSIZE} is to be avoided, as its support will cease in
+the future. This macro is obsoleted, and should be replaced by
+
+ at example
+AC_CHECK_MEMBERS([struct stat.st_blksize])
+ at end example
+ at noindent
+ at xref{AC_CHECK_MEMBERS}.
+ at end defmac
+
+ at defmac AC_STRUCT_ST_RDEV
+ at acindex{STRUCT_ST_RDEV}
+ at cvindex HAVE_ST_RDEV
+ at cvindex HAVE_STRUCT_STAT_ST_RDEV
+If @code{struct stat} contains an @code{st_rdev} member, define
+ at code{HAVE_STRUCT_STAT_ST_RDEV}. The former name for this macro,
+ at code{HAVE_ST_RDEV}, is to be avoided as it will cease to be supported
+in the future. Actually, even the new macro is obsolete and should be
+replaced by:
+ at example
+AC_CHECK_MEMBERS([struct stat.st_rdev])
+ at end example
+ at noindent
+ at xref{AC_CHECK_MEMBERS}.
+ at end defmac
+
+ at defmac AC_ST_BLKSIZE
+ at acindex{ST_BLKSIZE}
+Replaced by @code{AC_CHECK_MEMBERS} (@pxref{AC_CHECK_MEMBERS}).
+ at end defmac
+
+ at defmac AC_ST_BLOCKS
+ at acindex{ST_BLOCKS}
+Replaced by @code{AC_STRUCT_ST_BLOCKS} (@pxref{AC_STRUCT_ST_BLOCKS}).
+ at end defmac
+
+ at defmac AC_ST_RDEV
+ at acindex{ST_RDEV}
+Replaced by @code{AC_CHECK_MEMBERS} (@pxref{AC_CHECK_MEMBERS}).
+ at end defmac
+
+ at defmac AC_SYS_RESTARTABLE_SYSCALLS
+ at acindex{SYS_RESTARTABLE_SYSCALLS}
+ at cvindex HAVE_RESTARTABLE_SYSCALLS
+If the system automatically restarts a system call that is interrupted
+by a signal, define @code{HAVE_RESTARTABLE_SYSCALLS}. This macro does
+not check whether system calls are restarted in general---it checks whether a
+signal handler installed with @code{signal} (but not @code{sigaction})
+causes system calls to be restarted. It does not check whether system calls
+can be restarted when interrupted by signals that have no handler.
+
+These days portable programs should use @code{sigaction} with
+ at code{SA_RESTART} if they want restartable system calls. They should
+not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a
+system call is restartable is a dynamic issue, not a configuration-time
+issue.
+ at end defmac
+
+ at defmac AC_SYS_SIGLIST_DECLARED
+ at acindex{SYS_SIGLIST_DECLARED}
+This macro was renamed @code{AC_DECL_SYS_SIGLIST}. However, even that
+name is obsolete, as the same functionality is now achieved via
+ at code{AC_CHECK_DECLS} (@pxref{AC_CHECK_DECLS}).
+ at end defmac
+
+ at defmac AC_TEST_CPP
+ at acindex{TEST_CPP}
+This macro was renamed @code{AC_TRY_CPP}, which in turn was replaced by
+ at code{AC_PREPROC_IFELSE} (@pxref{AC_PREPROC_IFELSE}).
+ at end defmac
+
+ at defmac AC_TEST_PROGRAM
+ at acindex{TEST_PROGRAM}
+This macro was renamed @code{AC_TRY_RUN}, which in turn was replaced by
+ at code{AC_RUN_IFELSE} (@pxref{AC_RUN_IFELSE}).
+ at end defmac
+
+ at defmac AC_TIMEZONE
+ at acindex{TIMEZONE}
+Replaced by @code{AC_STRUCT_TIMEZONE} (@pxref{AC_STRUCT_TIMEZONE}).
+ at end defmac
+
+ at defmac AC_TIME_WITH_SYS_TIME
+ at acindex{TIME_WITH_SYS_TIME}
+Replaced by @code{AC_HEADER_TIME} (@pxref{AC_HEADER_TIME}).
+ at end defmac
+
+ at defmac AC_TRY_COMPILE (@var{includes}, @var{function-body}, @
+ @ovar{action-if-true}, @ovar{action-if-false})
+ at acindex{TRY_COMPILE}
+Same as:
+
+ at example
+AC_COMPILE_IFELSE(
+ [AC_LANG_PROGRAM([[@var{includes}]],
+ [[@var{function-body}]])],
+ [@var{action-if-true}],
+ [@var{action-if-false}])
+ at end example
+
+ at noindent
+ at xref{Running the Compiler}.
+
+This macro double quotes both @var{includes} and @var{function-body}.
+
+For C and C++, @var{includes} is any @code{#include} statements needed
+by the code in @var{function-body} (@var{includes} is ignored if
+the currently selected language is Fortran or Fortran 77). The compiler
+and compilation flags are determined by the current language
+(@pxref{Language Choice}).
+ at end defmac
+
+ at defmac AC_TRY_CPP (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
+ at acindex{TRY_CPP}
+Same as:
+
+ at example
+AC_PREPROC_IFELSE(
+ [AC_LANG_SOURCE([[@var{input}]])],
+ [@var{action-if-true}],
+ [@var{action-if-false}])
+ at end example
+
+ at noindent
+ at xref{Running the Preprocessor}.
+
+This macro double quotes the @var{input}.
+ at end defmac
+
+ at defmac AC_TRY_LINK (@var{includes}, @var{function-body}, @
+ @ovar{action-if-true}, @ovar{action-if-false})
+ at acindex{TRY_LINK}
+Same as:
+
+ at example
+AC_LINK_IFELSE(
+ [AC_LANG_PROGRAM([[@var{includes}]],
+ [[@var{function-body}]])],
+ [@var{action-if-true}],
+ [@var{action-if-false}])
+ at end example
+
+ at noindent
+ at xref{Running the Compiler}.
+
+This macro double quotes both @var{includes} and @var{function-body}.
+
+Depending on the current language (@pxref{Language Choice}), create a
+test program to see whether a function whose body consists of
+ at var{function-body} can be compiled and linked. If the file compiles
+and links successfully, run shell commands @var{action-if-found},
+otherwise run @var{action-if-not-found}.
+
+This macro double quotes both @var{includes} and @var{function-body}.
+
+For C and C++, @var{includes} is any @code{#include} statements needed
+by the code in @var{function-body} (@var{includes} is ignored if
+the currently selected language is Fortran or Fortran 77). The compiler
+and compilation flags are determined by the current language
+(@pxref{Language Choice}), and in addition @code{LDFLAGS} and
+ at code{LIBS} are used for linking.
+ at end defmac
+
+ at defmac AC_TRY_LINK_FUNC (@var{function}, @ovar{action-if-found}, @
+ @ovar{action-if-not-found})
+ at acindex{TRY_LINK_FUNC}
+This macro is equivalent to
+ at example
+AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])],
+ [@var{action-if-found}], [@var{action-if-not-found}])
+ at end example
+ at noindent
+ at xref{AC_LINK_IFELSE}.
+ at end defmac
+
+ at defmac AC_TRY_RUN (@var{program}, @ovar{action-if-true}, @
+ @ovar{action-if-false}, @dvar{action-if-cross-compiling, AC_MSG_FAILURE})
+ at acindex{TRY_RUN}
+Same as:
+
+ at example
+AC_RUN_IFELSE(
+ [AC_LANG_SOURCE([[@var{program}]])],
+ [@var{action-if-true}],
+ [@var{action-if-false}],
+ [@var{action-if-cross-compiling}])
+ at end example
+
+ at noindent
+ at xref{Runtime}.
+ at end defmac
+
+ at anchor{AC_TYPE_SIGNAL}
+ at defmac AC_TYPE_SIGNAL
+ at acindex{TYPE_SIGNAL}
+ at cvindex RETSIGTYPE
+ at hdrindex{signal.h}
+If @file{signal.h} declares @code{signal} as returning a pointer to a
+function returning @code{void}, define @code{RETSIGTYPE} to be
+ at code{void}; otherwise, define it to be @code{int}. These days, it is
+portable to assume C89, and that signal handlers return @code{void},
+without needing to use this macro or @code{RETSIGTYPE}.
+
+When targeting older K&R C, it is possible to define signal handlers as
+returning type @code{RETSIGTYPE}, and omit a return statement:
+
+ at example
+ at group
+RETSIGTYPE
+hup_handler ()
+@{
+ at dots{}
+@}
+ at end group
+ at end example
+ at end defmac
+
+ at defmac AC_UID_T
+ at acindex{UID_T}
+Replaced by @code{AC_TYPE_UID_T} (@pxref{AC_TYPE_UID_T}).
+ at end defmac
+
+ at defmac AC_UNISTD_H
+ at acindex{UNISTD_H}
+Same as @samp{AC_CHECK_HEADERS([unistd.h])} (@pxref{AC_CHECK_HEADERS}).
+ at end defmac
+
+ at defmac AC_USG
+ at acindex{USG}
+ at cvindex USG
+Define @code{USG} if the BSD string functions are defined in
+ at file{strings.h}. You should no longer depend upon @code{USG}, but on
+ at code{HAVE_STRING_H}; see @ref{Standard Symbols}.
+ at end defmac
+
+ at defmac AC_UTIME_NULL
+ at acindex{UTIME_NULL}
+Replaced by @code{AC_FUNC_UTIME_NULL} (@pxref{AC_FUNC_UTIME_NULL}).
+ at end defmac
+
+ at defmac AC_VALIDATE_CACHED_SYSTEM_TUPLE (@ovar{cmd})
+ at acindex{VALIDATE_CACHED_SYSTEM_TUPLE}
+If the cache file is inconsistent with the current host, target and
+build system types, it used to execute @var{cmd} or print a default
+error message. This is now handled by default.
+ at end defmac
+
+ at defmac AC_VERBOSE (@var{result-description})
+ at acindex{VERBOSE}
+Replaced by @code{AC_MSG_RESULT} (@pxref{AC_MSG_RESULT}).
+ at end defmac
+
+ at defmac AC_VFORK
+ at acindex{VFORK}
+Replaced by @code{AC_FUNC_FORK} (@pxref{AC_FUNC_FORK}).
+ at end defmac
+
+ at defmac AC_VPRINTF
+ at acindex{VPRINTF}
+Replaced by @code{AC_FUNC_VPRINTF} (@pxref{AC_FUNC_VPRINTF}).
+ at end defmac
+
+ at defmac AC_WAIT3
+ at acindex{WAIT3}
+This macro was renamed @code{AC_FUNC_WAIT3}. However, these days
+portable programs should use @code{waitpid}, not @code{wait3}, as
+ at code{wait3} has been removed from Posix.
+ at end defmac
+
+ at defmac AC_WARN
+ at acindex{WARN}
+Replaced by @code{AC_MSG_WARN} (@pxref{AC_MSG_WARN}).
+ at end defmac
+
+ at defmac AC_WITH (@var{package}, @var{action-if-given}, @
+ @ovar{action-if-not-given})
+ at acindex{WITH}
+This is an obsolete version of @code{AC_ARG_WITH} that does not
+support providing a help string (@pxref{AC_ARG_WITH}).
+ at end defmac
+
+ at defmac AC_WORDS_BIGENDIAN
+ at acindex{WORDS_BIGENDIAN}
+Replaced by @code{AC_C_BIGENDIAN} (@pxref{AC_C_BIGENDIAN}).
+ at end defmac
+
+ at defmac AC_XENIX_DIR
+ at acindex{XENIX_DIR}
+ at ovindex LIBS
+This macro used to add @option{-lx} to output variable @code{LIBS} if on
+Xenix. Also, if @file{dirent.h} is being checked for, added
+ at option{-ldir} to @code{LIBS}. Now it is merely an alias of
+ at code{AC_HEADER_DIRENT} instead, plus some code to detect whether
+running XENIX on which you should not depend:
+
+ at example
+AC_MSG_CHECKING([for Xenix])
+AC_EGREP_CPP([yes],
+[#if defined M_XENIX && !defined M_UNIX
+ yes
+#endif],
+ [AC_MSG_RESULT([yes]); XENIX=yes],
+ [AC_MSG_RESULT([no]); XENIX=])
+ at end example
+ at noindent
+Don't use this macro, the dignified means to check the nature of the
+host is using @code{AC_CANONICAL_HOST} (@pxref{Canonicalizing}).
+ at end defmac
+
+ at defmac AC_YYTEXT_POINTER
+ at acindex{YYTEXT_POINTER}
+This macro was renamed @code{AC_DECL_YYTEXT}, which in turn was
+integrated into @code{AC_PROG_LEX} (@pxref{AC_PROG_LEX}).
+ at end defmac
+
+ at node Autoconf 1
+ at section Upgrading From Version 1
+ at cindex Upgrading autoconf
+ at cindex Autoconf upgrading
+
+Autoconf version 2 is mostly backward compatible with version 1.
+However, it introduces better ways to do some things, and doesn't
+support some of the ugly things in version 1. So, depending on how
+sophisticated your @file{configure.ac} files are, you might have to do
+some manual work in order to upgrade to version 2. This chapter points
+out some problems to watch for when upgrading. Also, perhaps your
+ at command{configure} scripts could benefit from some of the new features in
+version 2; the changes are summarized in the file @file{NEWS} in the
+Autoconf distribution.
+
+ at menu
+* Changed File Names:: Files you might rename
+* Changed Makefiles:: New things to put in @file{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
+ at end menu
+
+ at node Changed File Names
+ at subsection Changed File Names
+
+If you have an @file{aclocal.m4} installed with Autoconf (as opposed to
+in a particular package's source directory), you must rename it to
+ at file{acsite.m4}. @xref{autoconf Invocation}.
+
+If you distribute @file{install.sh} with your package, rename it to
+ at file{install-sh} so @command{make} builtin rules don't inadvertently
+create a file called @file{install} from it. @code{AC_PROG_INSTALL}
+looks for the script under both names, but it is best to use the new name.
+
+If you were using @file{config.h.top}, @file{config.h.bot}, or
+ at file{acconfig.h}, you still can, but you have less clutter if you
+use the @code{AH_} macros. @xref{Autoheader Macros}.
+
+ at node Changed Makefiles
+ at subsection Changed Makefiles
+
+Add @samp{@@CFLAGS@@}, @samp{@@CPPFLAGS@@}, and @samp{@@LDFLAGS@@} in
+your @file{Makefile.in} files, so they can take advantage of the values
+of those variables in the environment when @command{configure} is run.
+Doing this isn't necessary, but it's a convenience for users.
+
+Also add @samp{@@configure_input@@} in a comment to each input file for
+ at code{AC_OUTPUT}, so that the output files contain a comment saying
+they were produced by @command{configure}. Automatically selecting the
+right comment syntax for all the kinds of files that people call
+ at code{AC_OUTPUT} on became too much work.
+
+Add @file{config.log} and @file{config.cache} to the list of files you
+remove in @code{distclean} targets.
+
+If you have the following in @file{Makefile.in}:
+
+ at example
+prefix = /usr/local
+exec_prefix = $(prefix)
+ at end example
+
+ at noindent
+you must change it to:
+
+ at example
+prefix = @@prefix@@
+exec_prefix = @@exec_prefix@@
+ at end example
+
+ at noindent
+The old behavior of replacing those variables without @samp{@@}
+characters around them has been removed.
+
+ at node Changed Macros
+ at subsection Changed Macros
+
+Many of the macros were renamed in Autoconf version 2. You can still
+use the old names, but the new ones are clearer, and it's easier to find
+the documentation for them. @xref{Obsolete Macros}, for a table showing the
+new names for the old macros. Use the @command{autoupdate} program to
+convert your @file{configure.ac} to using the new macro names.
+ at xref{autoupdate Invocation}.
+
+Some macros have been superseded by similar ones that do the job better,
+but are not call-compatible. If you get warnings about calling obsolete
+macros while running @command{autoconf}, you may safely ignore them, but
+your @command{configure} script generally works better if you follow
+the advice that is printed about what to replace the obsolete macros with. In
+particular, the mechanism for reporting the results of tests has
+changed. If you were using @command{echo} or @code{AC_VERBOSE} (perhaps
+via @code{AC_COMPILE_CHECK}), your @command{configure} script's output
+looks better if you switch to @code{AC_MSG_CHECKING} and
+ at code{AC_MSG_RESULT}. @xref{Printing Messages}. Those macros work best
+in conjunction with cache variables. @xref{Caching Results}.
+
+
+
+ at node Changed Results
+ at subsection Changed Results
+
+If you were checking the results of previous tests by examining the
+shell variable @code{DEFS}, you need to switch to checking the values of
+the cache variables for those tests. @code{DEFS} no longer exists while
+ at command{configure} is running; it is only created when generating output
+files. This difference from version 1 is because properly quoting the
+contents of that variable turned out to be too cumbersome and
+inefficient to do every time @code{AC_DEFINE} is called. @xref{Cache
+Variable Names}.
+
+For example, here is a @file{configure.ac} fragment written for Autoconf
+version 1:
+
+ at example
+AC_HAVE_FUNCS(syslog)
+case "$DEFS" in
+*-DHAVE_SYSLOG*) ;;
+*) # syslog is not in the default libraries. See if it's in some other.
+ saved_LIBS="$LIBS"
+ for lib in bsd socket inet; do
+ AC_CHECKING(for syslog in -l$lib)
+ LIBS="-l$lib $saved_LIBS"
+ AC_HAVE_FUNCS(syslog)
+ case "$DEFS" in
+ *-DHAVE_SYSLOG*) break ;;
+ *) ;;
+ esac
+ LIBS="$saved_LIBS"
+ done ;;
+esac
+ at end example
+
+Here is a way to write it for version 2:
+
+ at example
+AC_CHECK_FUNCS([syslog])
+if test "x$ac_cv_func_syslog" = xno; then
+ # syslog is not in the default libraries. See if it's in some other.
+ for lib in bsd socket inet; do
+ AC_CHECK_LIB([$lib], [syslog], [AC_DEFINE([HAVE_SYSLOG])
+ LIBS="-l$lib $LIBS"; break])
+ done
+fi
+ at end example
+
+If you were working around bugs in @code{AC_DEFINE_UNQUOTED} by adding
+backslashes before quotes, you need to remove them. It now works
+predictably, and does not treat quotes (except back quotes) specially.
+ at xref{Setting Output Variables}.
+
+All of the Boolean shell variables set by Autoconf macros now use
+ at samp{yes} for the true value. Most of them use @samp{no} for false,
+though for backward compatibility some use the empty string instead. If
+you were relying on a shell variable being set to something like 1 or
+ at samp{t} for true, you need to change your tests.
+
+ at node Changed Macro Writing
+ at subsection Changed Macro Writing
+
+When defining your own macros, you should now use @code{AC_DEFUN}
+instead of @code{define}. @code{AC_DEFUN} automatically calls
+ at code{AC_PROVIDE} and ensures that macros called via @code{AC_REQUIRE}
+do not interrupt other macros, to prevent nested @samp{checking at dots{}}
+messages on the screen. There's no actual harm in continuing to use the
+older way, but it's less convenient and attractive. @xref{Macro
+Definitions}.
+
+You probably looked at the macros that came with Autoconf as a guide for
+how to do things. It would be a good idea to take a look at the new
+versions of them, as the style is somewhat improved and they take
+advantage of some new features.
+
+If you were doing tricky things with undocumented Autoconf internals
+(macros, variables, diversions), check whether you need to change
+anything to account for changes that have been made. Perhaps you can
+even use an officially supported technique in version 2 instead of
+kludging. Or perhaps not.
+
+To speed up your locally written feature tests, add caching to them.
+See whether any of your tests are of general enough usefulness to
+encapsulate them into macros that you can share.
+
+
+ at node Autoconf 2.13
+ at section Upgrading From Version 2.13
+ at cindex Upgrading autoconf
+ at cindex Autoconf upgrading
+
+The introduction of the previous section (@pxref{Autoconf 1}) perfectly
+suits this section at enddots{}
+
+ at quotation
+Autoconf version 2.50 is mostly backward compatible with version 2.13.
+However, it introduces better ways to do some things, and doesn't
+support some of the ugly things in version 2.13. So, depending on how
+sophisticated your @file{configure.ac} files are, you might have to do
+some manual work in order to upgrade to version 2.50. This chapter
+points out some problems to watch for when upgrading. Also, perhaps
+your @command{configure} scripts could benefit from some of the new
+features in version 2.50; the changes are summarized in the file
+ at file{NEWS} in the Autoconf distribution.
+ at end quotation
+
+ at menu
+* 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
+ at end menu
+
+ at node Changed Quotation
+ at subsection Changed Quotation
+
+The most important changes are invisible to you: the implementation of
+most macros have completely changed. This allowed more factorization of
+the code, better error messages, a higher uniformity of the user's
+interface etc. Unfortunately, as a side effect, some construct which
+used to (miraculously) work might break starting with Autoconf 2.50.
+The most common culprit is bad quotation.
+
+For instance, in the following example, the message is not properly
+quoted:
+
+ at example
+AC_INIT
+AC_CHECK_HEADERS(foo.h, ,
+ AC_MSG_ERROR(cannot find foo.h, bailing out))
+AC_OUTPUT
+ at end example
+
+ at noindent
+Autoconf 2.13 simply ignores it:
+
+ at example
+$ @kbd{autoconf-2.13; ./configure --silent}
+creating cache ./config.cache
+configure: error: cannot find foo.h
+$
+ at end example
+
+ at noindent
+while Autoconf 2.50 produces a broken @file{configure}:
+
+ at example
+$ @kbd{autoconf-2.50; ./configure --silent}
+configure: error: cannot find foo.h
+./configure: exit: bad non-numeric arg `bailing'
+./configure: exit: bad non-numeric arg `bailing'
+$
+ at end example
+
+The message needs to be quoted, and the @code{AC_MSG_ERROR} invocation
+too!
+
+ at example
+AC_INIT([Example], [1.0], [bug-example@@example.org])
+AC_CHECK_HEADERS([foo.h], [],
+ [AC_MSG_ERROR([cannot find foo.h, bailing out])])
+AC_OUTPUT
+ at end example
+
+Many many (and many more) Autoconf macros were lacking proper quotation,
+including no less than at dots{} @code{AC_DEFUN} itself!
+
+ at example
+$ @kbd{cat configure.in}
+AC_DEFUN([AC_PROG_INSTALL],
+[# My own much better version
+])
+AC_INIT
+AC_PROG_INSTALL
+AC_OUTPUT
+$ @kbd{autoconf-2.13}
+autoconf: Undefined macros:
+***BUG in Autoconf--please report*** AC_FD_MSG
+***BUG in Autoconf--please report*** AC_EPI
+configure.in:1:AC_DEFUN([AC_PROG_INSTALL],
+configure.in:5:AC_PROG_INSTALL
+$ @kbd{autoconf-2.50}
+$
+ at end example
+
+
+ at node New Macros
+ at subsection New Macros
+
+ at cindex undefined macro
+ at cindex @code{_m4_divert_diversion}
+
+While Autoconf was relatively dormant in the late 1990s, Automake
+provided Autoconf-like macros for a while. Starting with Autoconf 2.50
+in 2001, Autoconf provided
+versions of these macros, integrated in the @code{AC_} namespace,
+instead of @code{AM_}. But in order to ease the upgrading via
+ at command{autoupdate}, bindings to such @code{AM_} macros are provided.
+
+Unfortunately older versions of Automake (e.g., Automake 1.4)
+did not quote the names of these macros.
+Therefore, when @command{m4} finds something like
+ at samp{AC_DEFUN(AM_TYPE_PTRDIFF_T, @dots{})} in @file{aclocal.m4},
+ at code{AM_TYPE_PTRDIFF_T} is
+expanded, replaced with its Autoconf definition.
+
+Fortunately Autoconf catches pre- at code{AC_INIT} expansions, and
+complains, in its own words:
+
+ at example
+$ @kbd{cat configure.ac}
+AC_INIT([Example], [1.0], [bug-example@@example.org])
+AM_TYPE_PTRDIFF_T
+$ @kbd{aclocal-1.4}
+$ @kbd{autoconf}
+aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion
+aclocal.m4:17: the top level
+autom4te: m4 failed with exit status: 1
+$
+ at end example
+
+Modern versions of Automake no longer define most of these
+macros, and properly quote the names of the remaining macros.
+If you must use an old Automake, do not depend upon macros from Automake
+as it is simply not its job
+to provide macros (but the one it requires itself):
+
+ at example
+$ @kbd{cat configure.ac}
+AC_INIT([Example], [1.0], [bug-example@@example.org])
+AM_TYPE_PTRDIFF_T
+$ @kbd{rm aclocal.m4}
+$ @kbd{autoupdate}
+autoupdate: `configure.ac' is updated
+$ @kbd{cat configure.ac}
+AC_INIT([Example], [1.0], [bug-example@@example.org])
+AC_CHECK_TYPES([ptrdiff_t])
+$ @kbd{aclocal-1.4}
+$ @kbd{autoconf}
+$
+ at end example
+
+
+ at node Hosts and Cross-Compilation
+ at subsection Hosts and Cross-Compilation
+ at cindex Cross compilation
+
+Based on the experience of compiler writers, and after long public
+debates, many aspects of the cross-compilation chain have changed:
+
+ at itemize @minus
+ at item
+the relationship between the build, host, and target architecture types,
+
+ at item
+the command line interface for specifying them to @command{configure},
+
+ at item
+the variables defined in @command{configure},
+
+ at item
+the enabling of cross-compilation mode.
+ at end itemize
+
+ at sp 1
+
+The relationship between build, host, and target have been cleaned up:
+the chain of default is now simply: target defaults to host, host to
+build, and build to the result of @command{config.guess}. Nevertheless,
+in order to ease the transition from 2.13 to 2.50, the following
+transition scheme is implemented. @emph{Do not rely on it}, as it will
+be completely disabled in a couple of releases (we cannot keep it, as it
+proves to cause more problems than it cures).
+
+They all default to the result of running @command{config.guess}, unless
+you specify either @option{--build} or @option{--host}. In this case,
+the default becomes the system type you specified. If you specify both,
+and they're different, @command{configure} enters cross compilation
+mode, so it doesn't run any tests that require execution.
+
+Hint: if you mean to override the result of @command{config.guess},
+prefer @option{--build} over @option{--host}.
+
+ at sp 1
+
+For backward compatibility, @command{configure} accepts a system
+type as an option by itself. Such an option overrides the
+defaults for build, host, and target system types. The following
+configure statement configures a cross toolchain that runs on
+NetBSD/alpha but generates code for GNU Hurd/sparc,
+which is also the build platform.
+
+ at example
+./configure --host=alpha-netbsd sparc-gnu
+ at end example
+
+ at sp 1
+
+In Autoconf 2.13 and before, the variables @code{build}, @code{host},
+and @code{target} had a different semantics before and after the
+invocation of @code{AC_CANONICAL_BUILD} etc. Now, the argument of
+ at option{--build} is strictly copied into @code{build_alias}, and is left
+empty otherwise. After the @code{AC_CANONICAL_BUILD}, @code{build} is
+set to the canonicalized build type. To ease the transition, before,
+its contents is the same as that of @code{build_alias}. Do @emph{not}
+rely on this broken feature.
+
+For consistency with the backward compatibility scheme exposed above,
+when @option{--host} is specified but @option{--build} isn't, the build
+system is assumed to be the same as @option{--host}, and
+ at samp{build_alias} is set to that value. Eventually, this
+historically incorrect behavior will go away.
+
+ at sp 1
+
+The former scheme to enable cross-compilation proved to cause more harm
+than good, in particular, it used to be triggered too easily, leaving
+regular end users puzzled in front of cryptic error messages.
+ at command{configure} could even enter cross-compilation mode only
+because the compiler was not functional. This is mainly because
+ at command{configure} used to try to detect cross-compilation, instead of
+waiting for an explicit flag from the user.
+
+Now, @command{configure} enters cross-compilation mode if and only if
+ at option{--host} is passed.
+
+That's the short documentation. To ease the transition between 2.13 and
+its successors, a more complicated scheme is implemented. @emph{Do not
+rely on the following}, as it will be removed in the near future.
+
+If you specify @option{--host}, but not @option{--build}, when
+ at command{configure} performs the first compiler test it tries to run
+an executable produced by the compiler. If the execution fails, it
+enters cross-compilation mode. This is fragile. Moreover, by the time
+the compiler test is performed, it may be too late to modify the
+build-system type: other tests may have already been performed.
+Therefore, whenever you specify @option{--host}, be sure to specify
+ at option{--build} too.
+
+ at example
+./configure --build=i686-pc-linux-gnu --host=m68k-coff
+ at end example
+
+ at noindent
+enters cross-compilation mode. The former interface, which
+consisted in setting the compiler to a cross-compiler without informing
+ at command{configure} is obsolete. For instance, @command{configure}
+fails if it can't run the code generated by the specified compiler if you
+configure as follows:
+
+ at example
+./configure CC=m68k-coff-gcc
+ at end example
+
+
+ at node AC_LIBOBJ vs LIBOBJS
+ at subsection @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}
+
+Up to Autoconf 2.13, the replacement of functions was triggered via the
+variable @code{LIBOBJS}. Since Autoconf 2.50, the macro
+ at code{AC_LIBOBJ} should be used instead (@pxref{Generic Functions}).
+Starting at Autoconf 2.53, the use of @code{LIBOBJS} is an error.
+
+This change is mandated by the unification of the GNU Build System
+components. In particular, the various fragile techniques used to parse
+a @file{configure.ac} are all replaced with the use of traces. As a
+consequence, any action must be traceable, which obsoletes critical
+variable assignments. Fortunately, @code{LIBOBJS} was the only problem,
+and it can even be handled gracefully (read, ``without your having to
+change something'').
+
+There were two typical uses of @code{LIBOBJS}: asking for a replacement
+function, and adjusting @code{LIBOBJS} for Automake and/or Libtool.
+
+ at sp 1
+
+As for function replacement, the fix is immediate: use
+ at code{AC_LIBOBJ}. For instance:
+
+ at example
+LIBOBJS="$LIBOBJS fnmatch.o"
+LIBOBJS="$LIBOBJS malloc.$ac_objext"
+ at end example
+
+ at noindent
+should be replaced with:
+
+ at example
+AC_LIBOBJ([fnmatch])
+AC_LIBOBJ([malloc])
+ at end example
+
+ at sp 1
+
+ at ovindex LIBOBJDIR
+When used with Automake 1.10 or newer, a suitable value for
+ at code{LIBOBJDIR} is set so that the @code{LIBOBJS} and @code{LTLIBOBJS}
+can be referenced from any @file{Makefile.am}. Even without Automake,
+arranging for @code{LIBOBJDIR} to be set correctly enables
+referencing @code{LIBOBJS} and @code{LTLIBOBJS} in another directory.
+The @code{LIBOBJDIR} feature is experimental.
+
+
+ at node AC_ACT_IFELSE vs AC_TRY_ACT
+ at subsection @code{AC_ at var{ACT}_IFELSE} vs.@: @code{AC_TRY_ at var{ACT}}
+ at c the anchor keeps the old node name, to try to avoid breaking links
+ at anchor{AC_FOO_IFELSE vs AC_TRY_FOO}
+
+ at acindex{@var{ACT}_IFELSE}
+ at acindex{TRY_ at var{ACT}}
+Since Autoconf 2.50, internal codes uses @code{AC_PREPROC_IFELSE},
+ at code{AC_COMPILE_IFELSE}, @code{AC_LINK_IFELSE}, and
+ at code{AC_RUN_IFELSE} on one hand and @code{AC_LANG_SOURCE},
+and @code{AC_LANG_PROGRAM} on the other hand instead of the deprecated
+ at code{AC_TRY_CPP}, @code{AC_TRY_COMPILE}, @code{AC_TRY_LINK}, and
+ at code{AC_TRY_RUN}. The motivations where:
+ at itemize @minus
+ at item
+a more consistent interface: @code{AC_TRY_COMPILE} etc.@: were double
+quoting their arguments;
+
+ at item
+the combinatoric explosion is solved by decomposing on the one hand the
+generation of sources, and on the other hand executing the program;
+
+ at item
+this scheme helps supporting more languages than plain C and C++.
+ at end itemize
+
+In addition to the change of syntax, the philosophy has changed too:
+while emphasis was put on speed at the expense of accuracy, today's
+Autoconf promotes accuracy of the testing framework at, ahem at dots{}, the
+expense of speed.
+
+
+As a perfect example of what is @emph{not} to be done, here is how to
+find out whether a header file contains a particular declaration, such
+as a typedef, a structure, a structure member, or a function. Use
+ at code{AC_EGREP_HEADER} instead of running @code{grep} directly on the
+header file; on some systems the symbol might be defined in another
+header file that the file you are checking includes.
+
+As a (bad) example, here is how you should not check for C preprocessor
+symbols, either defined by header files or predefined by the C
+preprocessor: using @code{AC_EGREP_CPP}:
+
+ at example
+ at group
+AC_EGREP_CPP(yes,
+[#ifdef _AIX
+ yes
+#endif
+], is_aix=yes, is_aix=no)
+ at end group
+ at end example
+
+The above example, properly written would (i) use
+ at code{AC_LANG_PROGRAM}, and (ii) run the compiler:
+
+ at example
+ at group
+AC_COMPILE_IFELSE([AC_LANG_PROGRAM(
+[[#ifndef _AIX
+ error: This isn't AIX!
+#endif
+]])],
+ [is_aix=yes],
+ [is_aix=no])
+ at end group
+ at end example
+
+
+ at c ============================= Generating Test Suites with Autotest
+
+ at node Using Autotest
+ at chapter Generating Test Suites with Autotest
+
+ at cindex Autotest
+
+ at display
+ at strong{N.B.: This section describes a feature which is still
+stabilizing. Although we believe that Autotest is useful as-is, this
+documentation describes an interface which might change in the future:
+do not depend upon Autotest without subscribing to the Autoconf mailing
+lists.}
+ at end display
+
+It is paradoxical that portable projects depend on nonportable tools
+to run their test suite. Autoconf by itself is the paragon of this
+problem: although it aims at perfectly portability, up to 2.13 its
+test suite was using DejaGNU, a rich and complex testing
+framework, but which is far from being standard on Posix systems.
+Worse yet, it was likely to be missing on the most fragile platforms,
+the very platforms that are most likely to torture Autoconf and
+exhibit deficiencies.
+
+To circumvent this problem, many package maintainers have developed their
+own testing framework, based on simple shell scripts whose sole outputs
+are exit status values describing whether the test succeeded. Most of
+these tests share common patterns, and this can result in lots of
+duplicated code and tedious maintenance.
+
+Following exactly the same reasoning that yielded to the inception of
+Autoconf, Autotest provides a test suite generation framework, based on
+M4 macros building a portable shell script. The suite itself is
+equipped with automatic logging and tracing facilities which greatly
+diminish the interaction with bug reporters, and simple timing reports.
+
+Autoconf itself has been using Autotest for years, and we do attest that
+it has considerably improved the strength of the test suite and the
+quality of bug reports. Other projects are known to use some generation
+of Autotest, such as Bison, Free Recode, Free Wdiff, GNU Tar, each of
+them with different needs, and this usage has validated Autotest as a general
+testing framework.
+
+Nonetheless, compared to DejaGNU, Autotest is inadequate for
+interactive tool testing, which is probably its main limitation.
+
+ at menu
+* Using an Autotest Test Suite:: Autotest and the user
+* Writing Testsuites:: Autotest macros
+* testsuite Invocation:: Running @command{testsuite} scripts
+* Making testsuite Scripts:: Using autom4te to create @command{testsuite}
+ at end menu
+
+ at node Using an Autotest Test Suite
+ at section Using an Autotest Test Suite
+
+ at menu
+* testsuite Scripts:: The concepts of Autotest
+* Autotest Logs:: Their contents
+ at end menu
+
+ at node testsuite Scripts
+ at subsection @command{testsuite} Scripts
+
+ at cindex @command{testsuite}
+
+Generating testing or validation suites using Autotest is rather easy.
+The whole validation suite is held in a file to be processed through
+ at command{autom4te}, itself using GNU M4 under the hood, to
+produce a stand-alone Bourne shell script which then gets distributed.
+Neither @command{autom4te} nor GNU M4 are needed at
+the installer's end.
+
+ at cindex test group
+Each test of the validation suite should be part of some test group. A
+ at dfn{test group} is a sequence of interwoven tests that ought to be
+executed together, usually because one test in the group creates data
+files that a later test in the same group needs to read. Complex test
+groups make later debugging more tedious. It is much better to
+keep only a few tests per test group. Ideally there is only one test
+per test group.
+
+For all but the simplest packages, some file such as @file{testsuite.at}
+does not fully hold all test sources, as these are often easier to
+maintain in separate files. Each of these separate files holds a single
+test group, or a sequence of test groups all addressing some common
+functionality in the package. In such cases, @file{testsuite.at}
+merely initializes the validation suite, and sometimes does elementary
+health checking, before listing include statements for all other test
+files. The special file @file{package.m4}, containing the
+identification of the package, is automatically included if found.
+
+A convenient alternative consists in moving all the global issues
+(local Autotest macros, elementary health checking, and @code{AT_INIT}
+invocation) into the file @code{local.at}, and making
+ at file{testsuite.at} be a simple list of @code{m4_include}s of sub test
+suites. In such case, generating the whole test suite or pieces of it
+is only a matter of choosing the @command{autom4te} command line
+arguments.
+
+The validation scripts that Autotest produces are by convention called
+ at command{testsuite}. When run, @command{testsuite} executes each test
+group in turn, producing only one summary line per test to say if that
+particular test succeeded or failed. At end of all tests, summarizing
+counters get printed. One debugging directory is left for each test
+group which failed, if any: such directories are named
+ at file{testsuite.dir/@var{nn}}, where @var{nn} is the sequence number of
+the test group, and they include:
+
+ at itemize @bullet
+ at item a debugging script named @file{run} which reruns the test in
+ at dfn{debug mode} (@pxref{testsuite Invocation}). The automatic generation
+of debugging scripts has the purpose of easing the chase for bugs.
+
+ at item all the files created with @code{AT_DATA}
+
+ at item all the Erlang source code files created with @code{AT_CHECK_EUNIT}
+
+ at item a log of the run, named @file{testsuite.log}
+ at end itemize
+
+In the ideal situation, none of the tests fail, and consequently no
+debugging directory is left behind for validation.
+
+It often happens in practice that individual tests in the validation
+suite need to get information coming out of the configuration process.
+Some of this information, common for all validation suites, is provided
+through the file @file{atconfig}, automatically created by
+ at code{AC_CONFIG_TESTDIR}. For configuration information which your
+testing environment specifically needs, you might prepare an optional
+file named @file{atlocal.in}, instantiated by @code{AC_CONFIG_FILES}.
+The configuration process produces @file{atconfig} and @file{atlocal}
+out of these two input files, and these two produced files are
+automatically read by the @file{testsuite} script.
+
+Here is a diagram showing the relationship between files.
+
+ at noindent
+Files used in preparing a software package for distribution:
+
+ at example
+ [package.m4] -->.
+ \
+subfile-1.at ->. [local.at] ---->+
+ ... \ \
+subfile-i.at ---->-- testsuite.at -->-- autom4te* -->testsuite
+ ... /
+subfile-n.at ->'
+ at end example
+
+ at noindent
+Files used in configuring a software package:
+
+ at example
+ .--> atconfig
+ /
+[atlocal.in] --> config.status* --<
+ \
+ `--> [atlocal]
+ at end example
+
+ at noindent
+Files created during test suite execution:
+
+ at example
+atconfig -->. .--> testsuite.log
+ \ /
+ >-- testsuite* --<
+ / \
+[atlocal] ->' `--> [testsuite.dir]
+ at end example
+
+
+ at node Autotest Logs
+ at subsection Autotest Logs
+
+When run, the test suite creates a log file named after itself, e.g., a
+test suite named @command{testsuite} creates @file{testsuite.log}. It
+contains a lot of information, usually more than maintainers actually
+need, but therefore most of the time it contains all that is needed:
+
+ at table @asis
+ at item command line arguments
+A bad but unfortunately widespread habit consists of
+setting environment variables before the command, such as in
+ at samp{CC=my-home-grown-cc ./testsuite}. The test suite does not
+know this change, hence (i) it cannot report it to you, and (ii)
+it cannot preserve the value of @code{CC} for subsequent runs.
+Autoconf faced exactly the same problem, and solved it by asking
+users to pass the variable definitions as command line arguments.
+Autotest requires this rule, too, but has no means to enforce it; the log
+then contains a trace of the variables that were changed by the user.
+
+ at item @file{ChangeLog} excerpts
+The topmost lines of all the @file{ChangeLog} files found in the source
+hierarchy. This is especially useful when bugs are reported against
+development versions of the package, since the version string does not
+provide sufficient information to know the exact state of the sources
+the user compiled. Of course, this relies on the use of a
+ at file{ChangeLog}.
+
+ at item build machine
+Running a test suite in a cross-compile environment is not an easy task,
+since it would mean having the test suite run on a machine @var{build},
+while running programs on a machine @var{host}. It is much simpler to
+run both the test suite and the programs on @var{host}, but then, from
+the point of view of the test suite, there remains a single environment,
+ at var{host} = @var{build}. The log contains relevant information on the
+state of the @var{build} machine, including some important environment
+variables.
+ at c FIXME: How about having an M4sh macro to say `hey, log the value
+ at c of `@dots{}'? This would help both Autoconf and Autotest.
+
+ at item tested programs
+The absolute file name and answers to @option{--version} of the tested
+programs (see @ref{Writing Testsuites}, @code{AT_TESTED}).
+
+ at item configuration log
+The contents of @file{config.log}, as created by @command{configure},
+are appended. It contains the configuration flags and a detailed report
+on the configuration itself.
+ at end table
+
+
+ at node Writing Testsuites
+ at section Writing @file{testsuite.at}
+
+The @file{testsuite.at} is a Bourne shell script making use of special
+Autotest M4 macros. It often contains a call to @code{AT_INIT} near
+its beginning followed by one call to @code{m4_include} per source file
+for tests. Each such included file, or the remainder of
+ at file{testsuite.at} if include files are not used, contain a sequence of
+test groups. Each test group begins with a call to @code{AT_SETUP},
+then an arbitrary number of shell commands or calls to @code{AT_CHECK},
+and then completes with a call to @code{AT_CLEANUP}. Multiple test
+groups can be categorized by a call to @code{AT_BANNER}.
+
+All of the public Autotest macros have all-uppercase names in the
+namespace @samp{^AT_} to prevent them from accidentally conflicting with
+other text; Autoconf also reserves the namespace @samp{^_AT_} for
+internal macros. All shell variables used in the testsuite for internal
+purposes have mostly-lowercase names starting with @samp{at_}. Autotest
+also uses here-document delimiters in the namespace @samp{^_AT[A-Z]}, and
+makes use of the file system namespace @samp{^at-}.
+
+Since Autoconf is built on top of M4sugar (@pxref{Programming in
+M4sugar}) and M4sh (@pxref{Programming in M4sh}), you must also be aware
+of those namespaces (@samp{^_?\(m4\|AS\)_}). In general, you
+ at emph{should not use} the namespace of a package that does not own the
+macro or shell code you are writing.
+
+ at defmac AT_INIT (@ovar{name})
+ at atindex{INIT}
+ at c FIXME: Not clear, plus duplication of the information.
+Initialize Autotest. Giving a @var{name} to the test suite is
+encouraged if your package includes several test suites. Before this
+macro is called, @code{AT_PACKAGE_STRING} and
+ at code{AT_PACKAGE_BUGREPORT} must be defined, which are used to display
+information about the testsuite to the user. Typically, these macros
+are provided by a file @file{package.m4} built by @command{make}
+(@pxref{Making testsuite Scripts}), in order to inherit the package
+name, version, and bug reporting address from @file{configure.ac}.
+ at end defmac
+
+ at defmac AT_COPYRIGHT (@var{copyright-notice})
+ at atindex{COPYRIGHT}
+ at cindex Copyright Notice
+State that, in addition to the Free Software Foundation's copyright on
+the Autotest macros, parts of your test suite are covered by
+ at var{copyright-notice}.
+
+The @var{copyright-notice} shows up in both the head of
+ at command{testsuite} and in @samp{testsuite --version}.
+ at end defmac
+
+ at defmac AT_ARG_OPTION (@var{options}, @var{help-text}, @
+ @ovar{action-if-given}, @ovar{action-if-not-given})
+ at atindex{ARG_OPTION}
+ at vrindex at_arg_ at var{option}
+Accept options from the space-separated list @var{options}, a list that
+has leading dashes removed from the options. Long options will be
+prefixed with @samp{--}, single-character options with @samp{-}. The
+first word in this list is the primary @var{option}, any others are
+assumed to be short-hand aliases. The variable associated with it
+is @code{at_arg_ at var{option}}, with any dashes in @var{option} replaced
+with underscores.
+
+If the user passes @option{-- at var{option}} to the @command{testsuite},
+the variable will be set to @samp{:}. If the user does not pass the
+option, or passes @option{--no- at var{option}}, then the variable will be
+set to @samp{false}.
+
+ at vrindex at_optarg
+ at vrindex at_optarg_ at var{option}
+ at var{action-if-given} is run each time the option is encountered; here,
+the variable @code{at_optarg} will be set to @samp{:} or @samp{false} as
+appropriate. @code{at_optarg} is actually just a copy of
+ at code{at_arg_ at var{option}}.
+
+ at var{action-if-not-given} will be run once after option parsing is
+complete and if no option from @var{options} was used.
+
+ at var{help-text} is added to the end of the list of options shown in
+ at command{testsuite --help} (@pxref{AS_HELP_STRING}).
+
+It is recommended that you use a package-specific prefix to @var{options}
+names in order to avoid clashes with future Autotest built-in options.
+ at end defmac
+
+ at defmac AT_ARG_OPTION_ARG (@var{options}, @var{help-text}, @
+ @ovar{action-if-given}, @ovar{action-if-not-given})
+ at atindex{ARG_OPTION_ARG}
+ at vrindex at_arg_ at var{option}
+Accept options with arguments from the space-separated list
+ at var{options}, a list that has leading dashes removed from the options.
+Long options will be prefixed with @samp{--}, single-character options
+with @samp{-}. The first word in this list is the primary @var{option},
+any others are assumed to be short-hand aliases. The variable associated
+with it is @code{at_arg_ at var{option}}, with any dashes in @var{option}
+replaced with underscores.
+
+If the user passes @option{-- at var{option}=@var{arg}} or
+ at option{-- at var{option} @var{arg}} to the @command{testsuite}, the
+variable will be set to @samp{@var{arg}}.
+
+ at vrindex at_optarg
+ at var{action-if-given} is run each time the option is encountered; here,
+the variable @code{at_optarg} will be set to @samp{@var{arg}}.
+ at code{at_optarg} is actually just a copy of @code{at_arg_ at var{option}}.
+
+ at var{action-if-not-given} will be run once after option parsing is
+complete and if no option from @var{options} was used.
+
+ at var{help-text} is added to the end of the list of options shown in
+ at command{testsuite --help} (@pxref{AS_HELP_STRING}).
+
+It is recommended that you use a package-specific prefix to @var{options}
+names in order to avoid clashes with future Autotest built-in options.
+ at end defmac
+
+ at defmac AT_COLOR_TESTS
+ at atindex{COLOR_TESTS}
+Enable colored test results by default when the output is connected to
+a terminal.
+ at end defmac
+
+ at defmac AT_TESTED (@var{executables})
+ at atindex{TESTED}
+Log the file name and answer to @option{--version} of each program in
+space-separated list @var{executables}. Several invocations register
+new executables, in other words, don't fear registering one program
+several times.
+
+Autotest test suites rely on @env{PATH} to find the tested program.
+This avoids the need to generate absolute names of the various tools, and
+makes it possible to test installed programs. Therefore, knowing which
+programs are being exercised is crucial to understanding problems in
+the test suite itself, or its occasional misuses. It is a good idea to
+also subscribe foreign programs you depend upon, to avoid incompatible
+diagnostics.
+ at end defmac
+
+ at sp 1
+
+ at defmac AT_BANNER (@var{test-category-name})
+ at atindex{BANNER}
+This macro identifies the start of a category of related test groups.
+When the resulting @file{testsuite} is invoked with more than one test
+group to run, its output will include a banner containing
+ at var{test-category-name} prior to any tests run from that category. The
+banner should be no more than about 40 or 50 characters. A blank banner
+indicates uncategorized tests; an empty line will be inserted after
+tests from an earlier category, effectively ending that category.
+ at end defmac
+
+ at defmac AT_SETUP (@var{test-group-name})
+ at atindex{SETUP}
+This macro starts a group of related tests, all to be executed in the
+same subshell. It accepts a single argument, which holds a few words
+(no more than about 30 or 40 characters) quickly describing the purpose
+of the test group being started. @var{test-group-name} must not expand
+to unbalanced quotes, although quadrigraphs can be used.
+ at end defmac
+
+ at defmac AT_KEYWORDS (@var{keywords})
+ at atindex{KEYWORDS}
+Associate the space-separated list of @var{keywords} to the enclosing
+test group. This makes it possible to run ``slices'' of the test suite.
+For instance, if some of your test groups exercise some @samp{foo}
+feature, then using @samp{AT_KEYWORDS(foo)} lets you run
+ at samp{./testsuite -k foo} to run exclusively these test groups. The
+ at var{test-group-name} of the test group is automatically recorded to
+ at code{AT_KEYWORDS}.
+
+Several invocations within a test group accumulate new keywords. In
+other words, don't fear registering the same keyword several times in a
+test group.
+ at end defmac
+
+ at defmac AT_CAPTURE_FILE (@var{file})
+ at atindex{CAPTURE_FILE}
+If the current test group fails, log the contents of @var{file}.
+Several identical calls within one test group have no additional effect.
+ at end defmac
+
+ at defmac AT_FAIL_IF (@var{shell-condition})
+ at atindex{FAIL_IF}
+Make the test group fail and skip the rest of its execution, if
+ at var{shell-condition} is true. @var{shell-condition} is a shell expression
+such as a @code{test} command. Tests before @command{AT_FAIL_IF}
+will be executed and may still cause the test group to be skipped.
+You can instantiate this macro many times from within the same test group.
+
+You should use this macro only for very simple failure conditions. If the
+ at var{shell-condition} could emit any kind of output you should instead
+use @command{AT_CHECK} like
+ at example
+AT_CHECK([if @var{shell-condition}; then exit 99; fi])
+ at end example
+ at noindent
+so that such output is properly recorded in the @file{testsuite.log}
+file.
+ at end defmac
+
+ at defmac AT_SKIP_IF (@var{shell-condition})
+ at atindex{SKIP_IF}
+Determine whether the test should be skipped because it requires
+features that are unsupported on the machine under test.
+ at var{shell-condition} is a shell expression such as a @code{test}
+command. Tests before @command{AT_SKIP_IF} will be executed
+and may still cause the test group to fail. You can instantiate this
+macro many times from within the same test group.
+
+You should use this macro only for very simple skip conditions. If the
+ at var{shell-condition} could emit any kind of output you should instead
+use @command{AT_CHECK} like
+ at example
+AT_CHECK([if @var{shell-condition}; then exit 77; fi])
+ at end example
+ at noindent
+so that such output is properly recorded in the @file{testsuite.log}
+file.
+ at end defmac
+
+ at defmac AT_XFAIL_IF (@var{shell-condition})
+ at atindex{XFAIL_IF}
+Determine whether the test is expected to fail because it is a known
+bug (for unsupported features, you should skip the test).
+ at var{shell-condition} is a shell expression such as a @code{test}
+command; you can instantiate this macro many times from within the
+same test group, and one of the conditions is enough to turn
+the test into an expected failure.
+ at end defmac
+
+ at defmac AT_CLEANUP
+ at atindex{CLEANUP}
+End the current test group.
+ at end defmac
+
+ at sp 1
+
+ at defmac AT_DATA (@var{file}, @var{contents})
+ at atindex{DATA}
+Initialize an input data @var{file} with given @var{contents}. Of
+course, the @var{contents} have to be properly quoted between square
+brackets to protect against included commas or spurious M4
+expansion. @var{contents} must be empty or end with a newline.
+ at var{file} must
+be a single shell word that expands into a single file name.
+ at end defmac
+
+ at defmac AT_CHECK (@var{commands}, @dvar{status, 0}, @ovar{stdout}, @
+ @ovar{stderr}, @ovar{run-if-fail}, @ovar{run-if-pass})
+ at defmacx AT_CHECK_UNQUOTED (@var{commands}, @dvar{status, 0}, @ovar{stdout}, @
+ @ovar{stderr}, @ovar{run-if-fail}, @ovar{run-if-pass})
+ at atindex{CHECK}
+ at atindex{CHECK_UNQUOTED}
+ at vrindex at_status
+Execute a test by performing given shell @var{commands} in a subshell.
+ at var{commands} is output as-is, so shell expansions are honored. These
+commands should normally exit with @var{status}, while producing expected
+ at var{stdout} and @var{stderr} contents. If @var{commands} exit with
+unexpected status 77, then the rest of the test group is skipped. If
+ at var{commands} exit with unexpected status 99, then the test group is
+immediately failed. Otherwise, if this test fails, run shell commands
+ at var{run-if-fail} or, if this test passes, run shell commands
+ at var{run-if-pass}, both inside the current shell execution environment.
+At the beginning of @var{run-if-fail} and @var{run-if-pass}, the status of
+ at var{commands} is available in the @code{at_status} shell variable.
+
+This macro must be invoked in between @code{AT_SETUP} and @code{AT_CLEANUP}.
+
+If @var{status} is the literal @samp{ignore}, then the corresponding
+exit status is not checked, except for the special cases of 77 (skip)
+and 99 (hard failure). The existence of hard failures allows one to
+mark a test as an expected failure with @code{AT_XFAIL_IF} because a
+feature has not yet been implemented, but to still distinguish between
+gracefully handling the missing feature and dumping core. A hard
+failure also inhibits post-test actions in @var{run-if-fail}.
+
+If the value of the @var{stdout} or @var{stderr} parameter is one of the
+literals in the following table, then the test treats the output
+according to the rules of that literal. Otherwise, the value of the
+parameter is treated as text that must exactly match the output given by
+ at var{commands} on standard output and standard error (including an empty
+parameter for no output); any differences are captured in the testsuite
+log and the test is failed (unless an unexpected exit status of 77
+skipped the test instead). The difference between @code{AT_CHECK} and
+ at code{AT_CHECK_UNQUOTED} is that only the latter performs shell variable
+expansion (@samp{$}), command substitution (@samp{`}), and backslash
+escaping (@samp{\}) on comparison text given in the @var{stdout} and
+ at var{stderr} arguments; if the text includes a trailing newline, this
+would be the same as if it were specified via an unquoted
+here-document. (However, there is no difference in the interpretation
+of @var{commands}).
+
+ at table @samp
+ at item ignore
+The content of the output is ignored, but still captured in the test
+group log (if the testsuite is run with option @option{-v}, the test
+group log is displayed as the test is run; if the test group later
+fails, the test group log is also copied into the overall testsuite
+log). This action is valid for both @var{stdout} and @var{stderr}.
+
+ at item ignore-nolog
+The content of the output is ignored, and nothing is captured in the log
+files. If @var{commands} are likely to produce binary output (including
+long lines) or large amounts of output, then logging the output can make
+it harder to locate details related to subsequent tests within the
+group, and could potentially corrupt terminal display of a user running
+ at command{testsuite -v}.
+
+ at item stdout
+For the @var{stdout} parameter, capture the content of standard output
+to both the file @file{stdout} and the test group log. Subsequent
+commands in the test group can then post-process the file. This action
+is often used when it is desired to use @command{grep} to look for a
+substring in the output, or when the output must be post-processed to
+normalize error messages into a common form.
+
+ at item stderr
+Like @samp{stdout}, except that it only works for the @var{stderr}
+parameter, and the standard error capture file will be named
+ at file{stderr}.
+
+ at item stdout-nolog
+ at itemx stderr-nolog
+Like @samp{stdout} or @samp{stderr}, except that the captured output is
+not duplicated into the test group log. This action is particularly
+useful for an intermediate check that produces large amounts of data,
+which will be followed by another check that filters down to the
+relevant data, as it makes it easier to locate details in the log.
+
+ at item expout
+For the @var{stdout} parameter, compare standard output contents with
+the previously created file @file{expout}, and list any differences in
+the testsuite log.
+
+ at item experr
+Like @samp{expout}, except that it only works for the @var{stderr}
+parameter, and the standard error contents are compared with
+ at file{experr}.
+ at end table
+ at end defmac
+
+ at defmac AT_CHECK_EUNIT (@var{module}, @var{test-spec}, @ovar{erlflags}, @
+ @ovar{run-if-fail}, @ovar{run-if-pass})
+ at atindex{CHECK_EUNIT}
+Initialize and execute an Erlang module named @var{module} that performs
+tests following the @var{test-spec} EUnit test specification.
+ at var{test-spec} must be a valid EUnit test specification, as defined in
+the @uref{http://@/erlang.org/@/doc/@/apps/@/eunit/@/index.html, EUnit
+Reference Manual}. @var{erlflags} are optional command-line options
+passed to the Erlang interpreter to execute the test Erlang module.
+Typically, @var{erlflags} defines at least the paths to directories
+containing the compiled Erlang modules under test, as @samp{-pa path1
+path2 ...}.
+
+For example, the unit tests associated with Erlang module @samp{testme},
+which compiled code is in subdirectory @file{src}, can be performed
+with:
+
+ at example
+AT_CHECK_EUNIT([testme_testsuite], [@{module, testme@}],
+ [-pa "$@{abs_top_builddir@}/src"])
+ at end example
+
+This macro must be invoked in between @code{AT_SETUP} and @code{AT_CLEANUP}.
+
+Variables @code{ERL}, @code{ERLC}, and (optionally) @code{ERLCFLAGS}
+must be defined as the path of the Erlang interpreter, the path of the
+Erlang compiler, and the command-line flags to pass to the compiler,
+respectively. Those variables should be configured in
+ at file{configure.ac} using the @command{AC_ERLANG_PATH_ERL} and
+ at command{AC_ERLANG_PATH_ERLC} macros, and the configured values of those
+variables are automatically defined in the testsuite. If @code{ERL} or
+ at code{ERLC} is not defined, the test group is skipped.
+
+If the EUnit library cannot be found, i.e. if module @code{eunit} cannot
+be loaded, the test group is skipped. Otherwise, if @var{test-spec} is
+an invalid EUnit test specification, the test group fails. Otherwise,
+if the EUnit test passes, shell commands @var{run-if-pass} are executed
+or, if the EUnit test fails, shell commands @var{run-if-fail} are
+executed and the test group fails.
+
+Only the generated test Erlang module is automatically compiled and
+executed. If @var{test-spec} involves testing other Erlang modules,
+e.g. module @samp{testme} in the example above, those modules must be
+already compiled.
+
+If the testsuite is run in verbose mode, with option @option{--verbose},
+EUnit is also run in verbose mode to output more details about
+individual unit tests.
+ at end defmac
+
+
+ at node testsuite Invocation
+ at section Running @command{testsuite} Scripts
+ at cindex @command{testsuite}
+
+Autotest test suites support the following options:
+
+ at table @option
+ at item --help
+ at itemx -h
+Display the list of options and exit successfully.
+
+ at item --version
+ at itemx -V
+Display the version of the test suite and exit successfully.
+
+ at item --directory=@var{dir}
+ at itemx -C @var{dir}
+Change the current directory to @var{dir} before creating any files.
+Useful for running the testsuite in a subdirectory from a top-level
+Makefile.
+
+ at item --jobs at r{[}=@var{n}@r{]}
+ at itemx -j at ovar{n}
+Run @var{n} tests in parallel, if possible. If @var{n} is not given,
+run all given tests in parallel. Note that there should be no space
+before the argument to @option{-j}, as @option{-j @var{number}} denotes
+the separate arguments @option{-j} and @option{@var{number}}, see below.
+
+In parallel mode, the standard input device of the testsuite script is
+not available to commands inside a test group. Furthermore, banner
+lines are not printed, and the summary line for each test group is
+output after the test group completes. Summary lines may appear
+unordered. If verbose and trace output are enabled (see below), they
+may appear intermixed from concurrently running tests.
+
+Parallel mode requires the @command{mkfifo} command to work, and will be
+silently disabled otherwise.
+
+ at item --clean
+ at itemx -c
+Remove all the files the test suite might have created and exit. Meant
+for @code{clean} Make targets.
+
+ at item --list
+ at itemx -l
+List all the tests (or only the selection), including their possible
+keywords.
+ at end table
+
+ at sp 1
+
+By default all tests are performed (or described with @option{--list})
+silently in the default environment, but the environment, set of tests,
+and verbosity level can be tuned:
+
+ at table @samp
+ at item @var{variable}=@var{value}
+Set the environment @var{variable} to @var{value}. Use this rather
+than @samp{FOO=foo ./testsuite} as debugging scripts would then run in a
+different environment.
+
+ at cindex @code{AUTOTEST_PATH}
+The variable @code{AUTOTEST_PATH} specifies the testing path to prepend
+to @env{PATH}. Relative directory names (not starting with
+ at samp{/}) are considered to be relative to the top level of the
+package being built. All directories are made absolute, first
+starting from the top level @emph{build} tree, then from the
+ at emph{source} tree. For instance @samp{./testsuite
+AUTOTEST_PATH=tests:bin} for a @file{/src/foo-1.0} source package built
+in @file{/tmp/foo} results in @samp{/tmp/foo/tests:/tmp/foo/bin} and
+then @samp{/src/foo-1.0/tests:/src/foo-1.0/bin} being prepended to
+ at env{PATH}.
+
+ at item @var{number}
+ at itemx @var{number}- at var{number}
+ at itemx @var{number}-
+ at itemx - at var{number}
+Add the corresponding test groups, with obvious semantics, to the
+selection.
+
+ at item --keywords=@var{keywords}
+ at itemx -k @var{keywords}
+Add to the selection the test groups with title or keywords (arguments
+to @code{AT_SETUP} or @code{AT_KEYWORDS}) that match @emph{all} keywords
+of the comma separated list @var{keywords}, case-insensitively. Use
+ at samp{!} immediately before the keyword to invert the selection for this
+keyword. By default, the keywords match whole words; enclose them in
+ at samp{.*} to also match parts of words.
+
+For example, running
+
+ at example
+ at kbd{./testsuite -k 'autoupdate,.*FUNC.*'}
+ at end example
+
+ at noindent
+selects all tests tagged @samp{autoupdate} @emph{and} with tags
+containing @samp{FUNC} (as in @samp{AC_CHECK_FUNC}, @samp{AC_FUNC_ALLOCA},
+etc.), while
+
+ at example
+ at kbd{./testsuite -k '!autoupdate' -k '.*FUNC.*'}
+ at end example
+
+ at noindent
+selects all tests not tagged @samp{autoupdate} @emph{or} with tags
+containing @samp{FUNC}.
+
+ at item --errexit
+ at itemx -e
+If any test fails, immediately abort testing. This implies
+ at option{--debug}: post test group clean up, and top-level logging
+are inhibited. This option is meant for the full test
+suite, it is not really useful for generated debugging scripts.
+If the testsuite is run in parallel mode using @option{--jobs},
+then concurrently running tests will finish before exiting.
+
+ at item --verbose
+ at itemx -v
+Force more verbosity in the detailed output of what is being done. This
+is the default for debugging scripts.
+
+ at item --color
+ at itemx --color at r{[}=never at r{|}auto at r{|}always at r{]}
+Enable colored test results. Without an argument, or with @samp{always},
+test results will be colored. With @samp{never}, color mode is turned
+off. Otherwise, if either the macro @code{AT_COLOR_TESTS} is used by
+the testsuite author, or the argument @samp{auto} is given, then test
+results are colored if standard output is connected to a terminal.
+
+ at item --debug
+ at itemx -d
+Do not remove the files after a test group was performed---but they are
+still removed @emph{before}, therefore using this option is sane when
+running several test groups. Create debugging scripts. Do not
+overwrite the top-level
+log (in order to preserve a supposedly existing full log file). This is
+the default for debugging scripts, but it can also be useful to debug
+the testsuite itself.
+
+ at item --recheck
+Add to the selection all test groups that failed or passed unexpectedly
+during the last non-debugging test run.
+
+ at item --trace
+ at itemx -x
+Trigger shell tracing of the test groups.
+ at end table
+
+Besides these options accepted by every Autotest testsuite, the
+testsuite author might have added package-specific options
+via the @code{AT_ARG_OPTION} and @code{AT_ARG_OPTION_ARG} macros
+(@pxref{Writing Testsuites}); refer to @command{testsuite --help} and
+the package documentation for details.
+
+
+ at node Making testsuite Scripts
+ at section Making @command{testsuite} Scripts
+
+For putting Autotest into movement, you need some configuration and
+makefile machinery. We recommend, at least if your package uses deep or
+shallow hierarchies, that you use @file{tests/} as the name of the
+directory holding all your tests and their makefile. Here is a
+check list of things to do.
+
+ at itemize @minus
+
+ at item
+ at cindex @file{package.m4}
+ at atindex{PACKAGE_STRING}
+ at atindex{PACKAGE_BUGREPORT}
+ at atindex{PACKAGE_NAME}
+ at atindex{PACKAGE_TARNAME}
+ at atindex{PACKAGE_VERSION}
+ at atindex{PACKAGE_URL}
+Make sure to create the file @file{package.m4}, which defines the
+identity of the package. It must define @code{AT_PACKAGE_STRING}, the
+full signature of the package, and @code{AT_PACKAGE_BUGREPORT}, the
+address to which bug reports should be sent. For sake of completeness,
+we suggest that you also define @code{AT_PACKAGE_NAME},
+ at code{AT_PACKAGE_TARNAME}, @code{AT_PACKAGE_VERSION}, and
+ at code{AT_PACKAGE_URL}.
+ at xref{Initializing configure}, for a description of these variables.
+Be sure to distribute @file{package.m4} and to put it into the source
+hierarchy: the test suite ought to be shipped! See below for an example
+ at file{Makefile} excerpt.
+
+ at item
+Invoke @code{AC_CONFIG_TESTDIR}.
+
+ at defmac AC_CONFIG_TESTDIR (@var{directory}, @dvar{test-path, directory})
+ at acindex{CONFIG_TESTDIR}
+An Autotest test suite is to be configured in @var{directory}. This
+macro causes @file{@var{directory}/atconfig} to be created by
+ at command{config.status} and sets the default @code{AUTOTEST_PATH} to
+ at var{test-path} (@pxref{testsuite Invocation}).
+ at end defmac
+
+ at item
+Still within @file{configure.ac}, as appropriate, ensure that some
+ at code{AC_CONFIG_FILES} command includes substitution for
+ at file{tests/atlocal}.
+
+ at item
+The appropriate @file{Makefile} should be modified so the validation in
+your package is triggered by @samp{make check}. An example is provided
+below.
+ at end itemize
+
+With Automake, here is a minimal example for inclusion in
+ at file{tests/Makefile.am}, in order to link @samp{make check} with a
+validation suite.
+
+ at example
+# The `:;' works around a Bash 3.2 bug when the output is not writable.
+$(srcdir)/package.m4: $(top_srcdir)/configure.ac
+ :;@{ \
+ echo '# Signature of the current package.' && \
+ echo 'm4_define([AT_PACKAGE_NAME],' && \
+ echo ' [$(PACKAGE_NAME)])' && \
+ echo 'm4_define([AT_PACKAGE_TARNAME],' && \
+ echo ' [$(PACKAGE_TARNAME)])' && \
+ echo 'm4_define([AT_PACKAGE_VERSION],' && \
+ echo ' [$(PACKAGE_VERSION)])' && \
+ echo 'm4_define([AT_PACKAGE_STRING],' && \
+ echo ' [$(PACKAGE_STRING)])' && \
+ echo 'm4_define([AT_PACKAGE_BUGREPORT],' && \
+ echo ' [$(PACKAGE_BUGREPORT)])'; \
+ echo 'm4_define([AT_PACKAGE_URL],' && \
+ echo ' [$(PACKAGE_URL)])'; \
+ @} >'$(srcdir)/package.m4'
+
+EXTRA_DIST = testsuite.at $(srcdir)/package.m4 $(TESTSUITE) atlocal.in
+TESTSUITE = $(srcdir)/testsuite
+
+check-local: atconfig atlocal $(TESTSUITE)
+ $(SHELL) '$(TESTSUITE)' $(TESTSUITEFLAGS)
+
+installcheck-local: atconfig atlocal $(TESTSUITE)
+ $(SHELL) '$(TESTSUITE)' AUTOTEST_PATH='$(bindir)' \
+ $(TESTSUITEFLAGS)
+
+clean-local:
+ test ! -f '$(TESTSUITE)' || \
+ $(SHELL) '$(TESTSUITE)' --clean
+
+AUTOM4TE = $(SHELL) $(srcdir)/build-aux/missing --run autom4te
+AUTOTEST = $(AUTOM4TE) --language=autotest
+$(TESTSUITE): $(srcdir)/testsuite.at $(srcdir)/package.m4
+ $(AUTOTEST) -I '$(srcdir)' -o $@@.tmp $@@.at
+ mv $@@.tmp $@@
+ at end example
+
+Note that the built testsuite is distributed; this is necessary because
+users might not have Autoconf installed, and thus would not be able to
+rebuild it. Likewise, the use of @file{missing} provides the user with
+a nicer error message if they modify a source file to the testsuite, and
+accidentally trigger the rebuild rules.
+
+You might want to list explicitly the dependencies, i.e., the list of
+the files @file{testsuite.at} includes.
+
+If you don't use Automake, you should include the above example in
+ at file{tests/@/Makefile.in}, along with additional lines inspired from
+the following:
+
+ at example
+subdir = tests
+PACKAGE_NAME = @@PACKAGE_NAME@@
+PACKAGE_TARNAME = @@PACKAGE_TARNAME@@
+PACKAGE_VERSION = @@PACKAGE_VERSION@@
+PACKAGE_STRING = @@PACKAGE_STRING@@
+PACKAGE_BUGREPORT = @@PACKAGE_BUGREPORT@@
+PACKAGE_URL = @@PACKAGE_URL@@
+
+atconfig: $(top_builddir)/config.status
+ cd $(top_builddir) && \
+ $(SHELL) ./config.status $(subdir)/$@@
+
+atlocal: $(srcdir)/atlocal.in $(top_builddir)/config.status
+ cd $(top_builddir) && \
+ $(SHELL) ./config.status $(subdir)/$@@
+ at end example
+
+ at noindent
+and manage to have @code{$(EXTRA_DIST)} distributed. You will also want
+to distribute the file @file{build-aux/@/missing} from the Automake
+project; a copy of this file resides in the Autoconf source tree.
+
+With all this in place, and if you have not initialized @samp{TESTSUITEFLAGS}
+within your makefile, you can fine-tune test suite execution with this
+variable, for example:
+
+ at example
+make check TESTSUITEFLAGS='-v -d -x 75 -k AC_PROG_CC CFLAGS=-g'
+ at end example
+
+
+
+ at c =============================== Frequent Autoconf Questions, with answers
+
+ at node FAQ
+ at chapter Frequent Autoconf Questions, with answers
+
+Several questions about Autoconf come up occasionally. Here some of them
+are addressed.
+
+ at menu
+* Distributing:: Distributing @command{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 @command{configure} instead of Imake
+* Defining Directories:: Passing @code{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 @command{configure} scripts
+ at end menu
+
+ at node Distributing
+ at section Distributing @command{configure} Scripts
+ at cindex License
+
+ at display
+What are the restrictions on distributing @command{configure}
+scripts that Autoconf generates? How does that affect my
+programs that use them?
+ at end display
+
+There are no restrictions on how the configuration scripts that Autoconf
+produces may be distributed or used. In Autoconf version 1, they were
+covered by the GNU General Public License. We still encourage
+software authors to distribute their work under terms like those of the
+GPL, but doing so is not required to use Autoconf.
+
+Of the other files that might be used with @command{configure},
+ at file{config.h.in} is under whatever copyright you use for your
+ at file{configure.ac}. @file{config.sub} and @file{config.guess} have an
+exception to the GPL when they are used with an Autoconf-generated
+ at command{configure} script, which permits you to distribute them under the
+same terms as the rest of your package. @file{install-sh} is from the X
+Consortium and is not copyrighted.
+
+ at node Why GNU M4
+ at section Why Require GNU M4?
+
+ at display
+Why does Autoconf require GNU M4?
+ at end display
+
+Many M4 implementations have hard-coded limitations on the size and
+number of macros that Autoconf exceeds. They also lack several
+builtin macros that it would be difficult to get along without in a
+sophisticated application like Autoconf, including:
+
+ at example
+m4_builtin
+m4_indir
+m4_bpatsubst
+__file__
+__line__
+ at end example
+
+Autoconf requires version 1.4.6 or later of GNU M4.
+
+Since only software maintainers need to use Autoconf, and since GNU
+M4 is simple to configure and install, it seems reasonable to require
+GNU M4 to be installed also. Many maintainers of GNU and
+other free software already have most of the GNU utilities
+installed, since they prefer them.
+
+ at node Bootstrapping
+ at section How Can I Bootstrap?
+ at cindex Bootstrap
+
+ at display
+If Autoconf requires GNU M4 and GNU M4 has an Autoconf
+ at command{configure} script, how do I bootstrap? It seems like a chicken
+and egg problem!
+ at end display
+
+This is a misunderstanding. Although GNU M4 does come with a
+ at command{configure} script produced by Autoconf, Autoconf is not required
+in order to run the script and install GNU M4. Autoconf is only
+required if you want to change the M4 @command{configure} script, which few
+people have to do (mainly its maintainer).
+
+ at node Why Not Imake
+ at section Why Not Imake?
+ at cindex Imake
+
+ at display
+Why not use Imake instead of @command{configure} scripts?
+ at end display
+
+Several people have written addressing this question, so
+adaptations of their explanations are included here.
+
+The following answer is based on one written by Richard Pixley:
+
+ at quotation
+Autoconf generated scripts frequently work on machines that it has
+never been set up to handle before. That is, it does a good job of
+inferring a configuration for a new system. Imake cannot do this.
+
+Imake uses a common database of host specific data. For X11, this makes
+sense because the distribution is made as a collection of tools, by one
+central authority who has control over the database.
+
+GNU tools are not released this way. Each GNU tool has a
+maintainer; these maintainers are scattered across the world. Using a
+common database would be a maintenance nightmare. Autoconf may appear
+to be this kind of database, but in fact it is not. Instead of listing
+host dependencies, it lists program requirements.
+
+If you view the GNU suite as a collection of native tools, then the
+problems are similar. But the GNU development tools can be
+configured as cross tools in almost any host+target permutation. All of
+these configurations can be installed concurrently. They can even be
+configured to share host independent files across hosts. Imake doesn't
+address these issues.
+
+Imake templates are a form of standardization. The GNU coding
+standards address the same issues without necessarily imposing the same
+restrictions.
+ at end quotation
+
+
+Here is some further explanation, written by Per Bothner:
+
+ at quotation
+One of the advantages of Imake is that it is easy to generate large
+makefiles using the @samp{#include} and macro mechanisms of @command{cpp}.
+However, @code{cpp} is not programmable: it has limited conditional
+facilities, and no looping. And @code{cpp} cannot inspect its
+environment.
+
+All of these problems are solved by using @code{sh} instead of
+ at code{cpp}. The shell is fully programmable, has macro substitution,
+can execute (or source) other shell scripts, and can inspect its
+environment.
+ at end quotation
+
+
+Paul Eggert elaborates more:
+
+ at quotation
+With Autoconf, installers need not assume that Imake itself is already
+installed and working well. This may not seem like much of an advantage
+to people who are accustomed to Imake. But on many hosts Imake is not
+installed or the default installation is not working well, and requiring
+Imake to install a package hinders the acceptance of that package on
+those hosts. For example, the Imake template and configuration files
+might not be installed properly on a host, or the Imake build procedure
+might wrongly assume that all source files are in one big directory
+tree, or the Imake configuration might assume one compiler whereas the
+package or the installer needs to use another, or there might be a
+version mismatch between the Imake expected by the package and the Imake
+supported by the host. These problems are much rarer with Autoconf,
+where each package comes with its own independent configuration
+processor.
+
+Also, Imake often suffers from unexpected interactions between
+ at command{make} and the installer's C preprocessor. The fundamental problem
+here is that the C preprocessor was designed to preprocess C programs,
+not makefiles. This is much less of a problem with Autoconf,
+which uses the general-purpose preprocessor M4, and where the
+package's author (rather than the installer) does the preprocessing in a
+standard way.
+ at end quotation
+
+
+Finally, Mark Eichin notes:
+
+ at quotation
+Imake isn't all that extensible, either. In order to add new features to
+Imake, you need to provide your own project template, and duplicate most
+of the features of the existing one. This means that for a sophisticated
+project, using the vendor-provided Imake templates fails to provide any
+leverage---since they don't cover anything that your own project needs
+(unless it is an X11 program).
+
+On the other side, though:
+
+The one advantage that Imake has over @command{configure}:
+ at file{Imakefile} files tend to be much shorter (likewise, less redundant)
+than @file{Makefile.in} files. There is a fix to this, however---at least
+for the Kerberos V5 tree, we've modified things to call in common
+ at file{post.in} and @file{pre.in} makefile fragments for the
+entire tree. This means that a lot of common things don't have to be
+duplicated, even though they normally are in @command{configure} setups.
+ at end quotation
+
+
+ at node Defining Directories
+ at section How Do I @code{#define} Installation Directories?
+
+ at display
+My program needs library files, installed in @code{datadir} and
+similar. If I use
+
+ at example
+AC_DEFINE_UNQUOTED([DATADIR], [$datadir],
+ [Define to the read-only architecture-independent
+ data directory.])
+ at end example
+
+ at noindent
+I get
+
+ at example
+#define DATADIR "$@{prefix@}/share"
+ at end example
+ at end display
+
+As already explained, this behavior is on purpose, mandated by the
+GNU Coding Standards, see @ref{Installation Directory
+Variables}. There are several means to achieve a similar goal:
+
+ at itemize @minus
+ at item
+Do not use @code{AC_DEFINE} but use your makefile to pass the
+actual value of @code{datadir} via compilation flags.
+ at xref{Installation Directory Variables}, for the details.
+
+ at item
+This solution can be simplified when compiling a program: you may either
+extend the @code{CPPFLAGS}:
+
+ at example
+CPPFLAGS = -DDATADIR='"$(datadir)"' @@CPPFLAGS@@
+ at end example
+
+ at noindent
+If you are using Automake, you should use @code{AM_CPPFLAGS} instead:
+
+ at example
+AM_CPPFLAGS = -DDATADIR='"$(datadir)"'
+ at end example
+
+ at noindent
+Alternatively, create a dedicated header file:
+
+ at example
+DISTCLEANFILES = myprog-paths.h
+myprog-paths.h: Makefile
+ echo '#define DATADIR "$(datadir)"' >$@@
+ at end example
+
+ at noindent
+The gnulib module @samp{configmake} provides such a header with all the
+standard directory variables defined, @pxref{configmake,,, gnulib, GNU
+Gnulib}.
+
+ at item
+Use @code{AC_DEFINE} but have @command{configure} compute the literal
+value of @code{datadir} and others. Many people have wrapped macros to
+automate this task; for an example, see the macro @code{AC_DEFINE_DIR} from
+the @uref{http://@/www.gnu.org/@/software/@/autoconf-archive/, Autoconf Macro
+Archive}.
+
+This solution does not conform to the GNU Coding Standards.
+
+ at item
+Note that all the previous solutions hard wire the absolute name of
+these directories in the executables, which is not a good property. You
+may try to compute the names relative to @code{prefix}, and try to
+find @code{prefix} at runtime, this way your package is relocatable.
+ at end itemize
+
+
+ at node Autom4te Cache
+ at section What is @file{autom4te.cache}?
+
+ at display
+What is this directory @file{autom4te.cache}? Can I safely remove it?
+ at end display
+
+In the GNU Build System, @file{configure.ac} plays a central
+role and is read by many tools: @command{autoconf} to create
+ at file{configure}, @command{autoheader} to create @file{config.h.in},
+ at command{automake} to create @file{Makefile.in}, @command{autoscan} to
+check the completeness of @file{configure.ac}, @command{autoreconf} to
+check the GNU Build System components that are used. To
+``read @file{configure.ac}'' actually means to compile it with M4,
+which can be a long process for complex @file{configure.ac}.
+
+This is why all these tools, instead of running directly M4, invoke
+ at command{autom4te} (@pxref{autom4te Invocation}) which, while answering to
+a specific demand, stores additional information in
+ at file{autom4te.cache} for future runs. For instance, if you run
+ at command{autoconf}, behind the scenes, @command{autom4te} also
+stores information for the other tools, so that when you invoke
+ at command{autoheader} or @command{automake} etc., reprocessing
+ at file{configure.ac} is not needed. The speed up is frequently 30%,
+and is increasing with the size of @file{configure.ac}.
+
+But it is and remains being simply a cache: you can safely remove it.
+
+ at sp 1
+
+ at display
+Can I permanently get rid of it?
+ at end display
+
+The creation of this cache can be disabled from
+ at file{~/.autom4te.cfg}, see @ref{Customizing autom4te}, for more
+details. You should be aware that disabling the cache slows down the
+Autoconf test suite by 40%. The more GNU Build System
+components are used, the more the cache is useful; for instance
+running @samp{autoreconf -f} on the Core Utilities is twice slower without
+the cache @emph{although @option{--force} implies that the cache is
+not fully exploited}, and eight times slower than without
+ at option{--force}.
+
+
+ at node Present But Cannot Be Compiled
+ at section Header Present But Cannot Be Compiled
+
+The most important guideline to bear in mind when checking for
+features is to mimic as much as possible the intended use.
+Unfortunately, old versions of @code{AC_CHECK_HEADER} and
+ at code{AC_CHECK_HEADERS} failed to follow this idea, and called
+the preprocessor, instead of the compiler, to check for headers. As a
+result, incompatibilities between headers went unnoticed during
+configuration, and maintainers finally had to deal with this issue
+elsewhere.
+
+The transition began with Autoconf 2.56. As of Autoconf 2.64 both
+checks are performed, and @command{configure} complains loudly if the
+compiler and the preprocessor do not agree. However, only the compiler
+result is considered.
+
+Consider the following example:
+
+ at smallexample
+$ @kbd{cat number.h}
+typedef int number;
+$ @kbd{cat pi.h}
+const number pi = 3;
+$ @kbd{cat configure.ac}
+AC_INIT([Example], [1.0], [bug-example@@example.org])
+AC_CHECK_HEADERS([pi.h])
+$ @kbd{autoconf -Wall}
+$ @kbd{./configure}
+checking for gcc... gcc
+checking for C compiler default output file name... a.out
+checking whether the C compiler works... yes
+checking whether we are cross compiling... no
+checking for suffix of executables...
+checking for suffix of object files... o
+checking whether we are using the GNU C compiler... yes
+checking whether gcc accepts -g... yes
+checking for gcc option to accept ISO C89... none needed
+checking how to run the C preprocessor... gcc -E
+checking for grep that handles long lines and -e... grep
+checking for egrep... grep -E
+checking for ANSI C header files... yes
+checking for sys/types.h... yes
+checking for sys/stat.h... yes
+checking for stdlib.h... yes
+checking for string.h... yes
+checking for memory.h... yes
+checking for strings.h... yes
+checking for inttypes.h... yes
+checking for stdint.h... yes
+checking for unistd.h... yes
+checking pi.h usability... no
+checking pi.h presence... yes
+configure: WARNING: pi.h: present but cannot be compiled
+configure: WARNING: pi.h: check for missing prerequisite headers?
+configure: WARNING: pi.h: see the Autoconf documentation
+configure: WARNING: pi.h: section "Present But Cannot Be Compiled"
+configure: WARNING: pi.h: proceeding with the compiler's result
+configure: WARNING: ## -------------------------------------- ##
+configure: WARNING: ## Report this to bug-example@@example.org ##
+configure: WARNING: ## -------------------------------------- ##
+checking for pi.h... yes
+ at end smallexample
+
+ at noindent
+The proper way the handle this case is using the fourth argument
+(@pxref{Generic Headers}):
+
+ at example
+$ @kbd{cat configure.ac}
+AC_INIT([Example], [1.0], [bug-example@@example.org])
+AC_CHECK_HEADERS([number.h pi.h], [], [],
+[[#ifdef HAVE_NUMBER_H
+# include <number.h>
+#endif
+]])
+$ @kbd{autoconf -Wall}
+$ @kbd{./configure}
+checking for gcc... gcc
+checking for C compiler default output... a.out
+checking whether the C compiler works... yes
+checking whether we are cross compiling... no
+checking for suffix of executables...
+checking for suffix of object files... o
+checking whether we are using the GNU C compiler... yes
+checking whether gcc accepts -g... yes
+checking for gcc option to accept ANSI C... none needed
+checking for number.h... yes
+checking for pi.h... yes
+ at end example
+
+See @ref{Particular Headers}, for a list of headers with their
+prerequisites.
+
+ at node Expanded Before Required
+ at section Expanded Before Required
+
+ at cindex expanded before required
+Older versions of Autoconf silently built files with incorrect ordering
+between dependent macros if an outer macro first expanded, then later
+indirectly required, an inner macro. Starting with Autoconf 2.64, this
+situation no longer generates out-of-order code, but results in
+duplicate output and a syntax warning:
+
+ at example
+$ @kbd{cat configure.ac}
+ at result{}AC_DEFUN([TESTA], [[echo in A
+ at result{}if test -n "$SEEN_A" ; then echo duplicate ; fi
+ at result{}SEEN_A=:]])
+ at result{}AC_DEFUN([TESTB], [AC_REQUIRE([TESTA])[echo in B
+ at result{}if test -z "$SEEN_A" ; then echo bug ; fi]])
+ at result{}AC_DEFUN([TESTC], [AC_REQUIRE([TESTB])[echo in C]])
+ at result{}AC_DEFUN([OUTER], [[echo in OUTER]
+ at result{}TESTA
+ at result{}TESTC])
+ at result{}AC_INIT
+ at result{}OUTER
+ at result{}AC_OUTPUT
+$ @kbd{autoconf}
+ at result{}configure.ac:11: warning: AC_REQUIRE:
+ at result{} `TESTA' was expanded before it was required
+ at result{}configure.ac:4: TESTB is expanded from...
+ at result{}configure.ac:6: TESTC is expanded from...
+ at result{}configure.ac:7: OUTER is expanded from...
+ at result{}configure.ac:11: the top level
+ at end example
+
+ at noindent
+To avoid this warning, decide what purpose the macro in question serves.
+If it only needs to be expanded once (for example, if it provides
+initialization text used by later macros), then the simplest fix is to
+change the macro to be declared with @code{AC_DEFUN_ONCE}
+(@pxref{One-Shot Macros}), although this only works in Autoconf 2.64 and
+newer. A more portable fix is to change all
+instances of direct calls to instead go through @code{AC_REQUIRE}
+(@pxref{Prerequisite Macros}). If, instead, the macro is parameterized
+by arguments or by the current definition of other macros in the m4
+environment, then the macro should always be directly expanded instead
+of required.
+
+For another case study, consider this example trimmed down from an
+actual package. Originally, the package contained shell code and
+multiple macro invocations at the top level of @file{configure.ac}:
+
+ at example
+AC_DEFUN([FOO], [AC_COMPILE_IFELSE([@dots{}])])
+foobar=
+AC_PROG_CC
+FOO
+ at end example
+
+ at noindent
+but that was getting complex, so the author wanted to offload some of
+the text into a new macro in another file included via
+ at file{aclocal.m4}. The na@"ive approach merely wraps the text in a new
+macro:
+
+ at example
+AC_DEFUN([FOO], [AC_COMPILE_IFELSE([@dots{}])])
+AC_DEFUN([BAR], [
+foobar=
+AC_PROG_CC
+FOO
+])
+BAR
+ at end example
+
+ at noindent
+With older versions of Autoconf, the setting of @samp{foobar=} occurs
+before the single compiler check, as the author intended. But with
+Autoconf 2.64, this issues the ``expanded before it was required''
+warning for @code{AC_PROG_CC}, and outputs two copies of the compiler
+check, one before @samp{foobar=}, and one after. To understand why this
+is happening, remember that the use of @code{AC_COMPILE_IFELSE} includes
+a call to @code{AC_REQUIRE([AC_PROG_CC])} under the hood. According to
+the documented semantics of @code{AC_REQUIRE}, this means that
+ at code{AC_PROG_CC} @emph{must} occur before the body of the outermost
+ at code{AC_DEFUN}, which in this case is @code{BAR}, thus preceding the
+use of @samp{foobar=}. The older versions of Autoconf were broken with
+regards to the rules of @code{AC_REQUIRE}, which explains why the code
+changed from one over to two copies of @code{AC_PROG_CC} when upgrading
+autoconf. In other words, the author was unknowingly relying on a bug
+exploit to get the desired results, and that exploit broke once the bug
+was fixed.
+
+So, what recourse does the author have, to restore their intended
+semantics of setting @samp{foobar=} prior to a single compiler check,
+regardless of whether Autoconf 2.63 or 2.64 is used? One idea is to
+remember that only @code{AC_DEFUN} is impacted by @code{AC_REQUIRE};
+there is always the possibility of using the lower-level
+ at code{m4_define}:
+
+ at example
+AC_DEFUN([FOO], [AC_COMPILE_IFELSE([@dots{}])])
+m4_define([BAR], [
+foobar=
+AC_PROG_CC
+FOO
+])
+BAR
+ at end example
+
+ at noindent
+This works great if everything is in the same file. However, it does
+not help in the case where the author wants to have @command{aclocal}
+find the definition of @code{BAR} from its own file, since
+ at command{aclocal} requires the use of @code{AC_DEFUN}. In this case, a
+better fix is to recognize that if @code{BAR} also uses
+ at code{AC_REQUIRE}, then there will no longer be direct expansion prior
+to a subsequent require. Then, by creating yet another helper macro,
+the author can once again guarantee a single invocation of
+ at code{AC_PROG_CC}, which will still occur after @code{foobar=}. The
+author can also use @code{AC_BEFORE} to make sure no other macro
+appearing before @code{BAR} has triggered an unwanted expansion of
+ at code{AC_PROG_CC}.
+
+ at example
+AC_DEFUN([FOO], [AC_COMPILE_IFELSE([@dots{}])])
+AC_DEFUN([BEFORE_CC], [
+foobar=
+])
+AC_DEFUN([BAR], [
+AC_BEFORE([$0], [AC_PROG_CC])dnl
+AC_REQUIRE([BEFORE_CC])dnl
+AC_REQUIRE([AC_PROG_CC])dnl
+FOO
+])
+BAR
+ at end example
+
+
+ at node Debugging
+ at section Debugging @command{configure} scripts
+
+While in general, @command{configure} scripts generated by Autoconf
+strive to be fairly portable to various systems, compilers, shells, and
+other tools, it may still be necessary to debug a failing test, broken
+script or makefile, or fix or override an incomplete, faulty, or erroneous
+test, especially during macro development. Failures can occur at all levels,
+in M4 syntax or semantics, shell script issues, or due to bugs in the
+test or the tools invoked by @command{configure}. Together with the
+rather arcane error message that @command{m4} and @command{make} may
+produce when their input contains syntax errors, this can make debugging
+rather painful.
+
+Nevertheless, here is a list of hints and strategies that may help:
+
+ at itemize
+ at item
+When @command{autoconf} fails, common causes for error include:
+
+ at itemize
+ at item
+mismatched or unbalanced parentheses or braces (@pxref{Balancing
+Parentheses}),
+
+ at item under- or overquoted macro arguments (@pxref{Autoconf
+Language}, @pxref{Quoting and Parameters}, @pxref{Quotation and Nested
+Macros}),
+
+ at item spaces between macro name and opening parenthesis (@pxref{Autoconf
+Language}).
+ at end itemize
+
+Typically, it helps to go back to the last working version of the input
+and compare the differences for each of these errors. Another
+possibility is to sprinkle pairs of @code{m4_traceon} and
+ at code{m4_traceoff} judiciously in the code, either without a parameter
+or listing some macro names and watch @command{m4} expand its input
+verbosely (@pxref{Debugging via autom4te}).
+
+ at item
+Sometimes @command{autoconf} succeeds but the generated
+ at command{configure} script has invalid shell syntax. You can detect this
+case by running @samp{bash -n configure} or @samp{sh -n configure}.
+If this command fails, the same tips apply, as if @command{autoconf} had
+failed.
+
+ at item
+Debugging @command{configure} script execution may be done by sprinkling
+pairs of @code{set -x} and @code{set +x} into the shell script before
+and after the region that contains a bug. Running the whole script with
+ at samp{@var{shell} -vx ./configure 2>&1 | tee @var{log-file}} with a decent
+ at var{shell} may work, but produces lots of output. Here, it can help to
+search for markers like @samp{checking for} a particular test in the
+ at var{log-file}.
+
+ at item
+Alternatively, you might use a shell with debugging capabilities like
+ at uref{http://bashdb.sourceforge.net/, bashdb}.
+
+ at item
+When @command{configure} tests produce invalid results for your system,
+it may be necessary to override them:
+
+ at itemize
+ at item
+For programs, tools or libraries variables, preprocessor, compiler, or
+linker flags, it is often sufficient to override them at @command{make}
+run time with some care (@pxref{Macros and Submakes}). Since this
+normally won't cause @command{configure} to be run again with these
+changed settings, it may fail if the changed variable would have caused
+different test results from @command{configure}, so this may work only
+for simple differences.
+
+ at item
+Most tests which produce their result in a substituted variable allow to
+override the test by setting the variable on the @command{configure}
+command line (@pxref{Compilers and Options}, @pxref{Defining Variables},
+ at pxref{Particular Systems}).
+
+ at item
+Many tests store their result in a cache variable (@pxref{Caching
+Results}). This lets you override them either on the
+ at command{configure} command line as above, or through a primed cache or
+site file (@pxref{Cache Files}, @pxref{Site Defaults}). The name of a
+cache variable is documented with a test macro or may be inferred from
+ at ref{Cache Variable Names}; the precise semantics of undocumented
+variables are often internal details, subject to change.
+ at end itemize
+
+ at item
+Alternatively, @command{configure} may produce invalid results because
+of uncaught programming errors, in your package or in an upstream
+library package. For example, when @code{AC_CHECK_LIB} fails to find a
+library with a specified function, always check @file{config.log}. This
+will reveal the exact error that produced the failing result: the
+library linked by @code{AC_CHECK_LIB} probably has a fatal bug.
+ at end itemize
+
+Conversely, as macro author, you can make it easier for users of your
+macro:
+
+ at itemize
+ at item
+by minimizing dependencies between tests and between test results as far
+as possible,
+
+ at item
+by using @command{make} variables to factorize and allow
+override of settings at @command{make} run time,
+
+ at item
+by honoring the GNU Coding Standards and not overriding flags
+reserved for the user except temporarily during @command{configure}
+tests,
+
+ at item
+by not requiring users of your macro to use the cache variables.
+Instead, expose the result of the test via @var{run-if-true} and
+ at var{run-if-false} parameters. If the result is not a boolean,
+then provide it through documented shell variables.
+ at end itemize
+
+
+ at c ===================================================== History of Autoconf.
+
+ at node History
+ at chapter History of Autoconf
+ at cindex History of autoconf
+
+ at emph{This chapter was written by the original author, David MacKenzie.}
+
+You may be wondering, Why was Autoconf originally written? How did it
+get into its present form? (Why does it look like gorilla spit?) If
+you're not wondering, then this chapter contains no information useful
+to you, and you might as well skip it. If you @emph{are} wondering,
+then let there be light at enddots{}
+
+ at menu
+* Genesis:: Prehistory and naming of @command{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
+ at end menu
+
+ at node Genesis
+ at section Genesis
+
+In June 1991 I was maintaining many of the GNU utilities for the
+Free Software Foundation. As they were ported to more platforms and
+more programs were added, the number of @option{-D} options that users
+had to select in the makefile (around 20) became burdensome.
+Especially for me---I had to test each new release on a bunch of
+different systems. So I wrote a little shell script to guess some of
+the correct settings for the fileutils package, and released it as part
+of fileutils 2.0. That @command{configure} script worked well enough that
+the next month I adapted it (by hand) to create similar @command{configure}
+scripts for several other GNU utilities packages. Brian Berliner
+also adapted one of my scripts for his CVS revision control system.
+
+Later that summer, I learned that Richard Stallman and Richard Pixley
+were developing similar scripts to use in the GNU compiler tools;
+so I adapted my @command{configure} scripts to support their evolving
+interface: using the file name @file{Makefile.in} as the templates;
+adding @samp{+srcdir}, the first option (of many); and creating
+ at file{config.status} files.
+
+ at node Exodus
+ at section Exodus
+
+As I got feedback from users, I incorporated many improvements, using
+Emacs to search and replace, cut and paste, similar changes in each of
+the scripts. As I adapted more GNU utilities packages to use
+ at command{configure} scripts, updating them all by hand became impractical.
+Rich Murphey, the maintainer of the GNU graphics utilities, sent me
+mail saying that the @command{configure} scripts were great, and asking if
+I had a tool for generating them that I could send him. No, I thought,
+but I should! So I started to work out how to generate them. And the
+journey from the slavery of hand-written @command{configure} scripts to the
+abundance and ease of Autoconf began.
+
+Cygnus @command{configure}, which was being developed at around that time,
+is table driven; it is meant to deal mainly with a discrete number of
+system types with a small number of mainly unguessable features (such as
+details of the object file format). The automatic configuration system
+that Brian Fox had developed for Bash takes a similar approach. For
+general use, it seems to me a hopeless cause to try to maintain an
+up-to-date database of which features each variant of each operating
+system has. It's easier and more reliable to check for most features on
+the fly---especially on hybrid systems that people have hacked on
+locally or that have patches from vendors installed.
+
+I considered using an architecture similar to that of Cygnus
+ at command{configure}, where there is a single @command{configure} script that
+reads pieces of @file{configure.in} when run. But I didn't want to have
+to distribute all of the feature tests with every package, so I settled
+on having a different @command{configure} made from each
+ at file{configure.in} by a preprocessor. That approach also offered more
+control and flexibility.
+
+I looked briefly into using the Metaconfig package, by Larry Wall,
+Harlan Stenn, and Raphael Manfredi, but I decided not to for several
+reasons. The @command{Configure} scripts it produces are interactive,
+which I find quite inconvenient; I didn't like the ways it checked for
+some features (such as library functions); I didn't know that it was
+still being maintained, and the @command{Configure} scripts I had
+seen didn't work on many modern systems (such as System V R4 and NeXT);
+it wasn't flexible in what it could do in response to a feature's
+presence or absence; I found it confusing to learn; and it was too big
+and complex for my needs (I didn't realize then how much Autoconf would
+eventually have to grow).
+
+I considered using Perl to generate my style of @command{configure}
+scripts, but decided that M4 was better suited to the job of simple
+textual substitutions: it gets in the way less, because output is
+implicit. Plus, everyone already has it. (Initially I didn't rely on
+the GNU extensions to M4.) Also, some of my friends at the
+University of Maryland had recently been putting M4 front ends on
+several programs, including @code{tvtwm}, and I was interested in trying
+out a new language.
+
+ at node Leviticus
+ at section Leviticus
+
+Since my @command{configure} scripts determine the system's capabilities
+automatically, with no interactive user intervention, I decided to call
+the program that generates them Autoconfig. But with a version number
+tacked on, that name would be too long for old Unix file systems,
+so I shortened it to Autoconf.
+
+In the fall of 1991 I called together a group of fellow questers after
+the Holy Grail of portability (er, that is, alpha testers) to give me
+feedback as I encapsulated pieces of my handwritten scripts in M4 macros
+and continued to add features and improve the techniques used in the
+checks. Prominent among the testers were Fran@,{c}ois Pinard, who came up
+with the idea of making an Autoconf shell script to run M4
+and check for unresolved macro calls; Richard Pixley, who suggested
+running the compiler instead of searching the file system to find
+include files and symbols, for more accurate results; Karl Berry, who
+got Autoconf to configure @TeX{} and added the macro index to the
+documentation; and Ian Lance Taylor, who added support for creating a C
+header file as an alternative to putting @option{-D} options in a
+makefile, so he could use Autoconf for his UUCP package.
+The alpha testers cheerfully adjusted their files again and again as the
+names and calling conventions of the Autoconf macros changed from
+release to release. They all contributed many specific checks, great
+ideas, and bug fixes.
+
+ at node Numbers
+ at section Numbers
+
+In July 1992, after months of alpha testing, I released Autoconf 1.0,
+and converted many GNU packages to use it. I was surprised by how
+positive the reaction to it was. More people started using it than I
+could keep track of, including people working on software that wasn't
+part of the GNU Project (such as TCL, FSP, and Kerberos V5).
+Autoconf continued to improve rapidly, as many people using the
+ at command{configure} scripts reported problems they encountered.
+
+Autoconf turned out to be a good torture test for M4 implementations.
+Unix M4 started to dump core because of the length of the
+macros that Autoconf defined, and several bugs showed up in GNU
+M4 as well. Eventually, we realized that we needed to use some
+features that only GNU M4 has. 4.3BSD M4, in
+particular, has an impoverished set of builtin macros; the System V
+version is better, but still doesn't provide everything we need.
+
+More development occurred as people put Autoconf under more stresses
+(and to uses I hadn't anticipated). Karl Berry added checks for X11.
+david zuhn contributed C++ support. Fran@,{c}ois Pinard made it diagnose
+invalid arguments. Jim Blandy bravely coerced it into configuring
+GNU Emacs, laying the groundwork for several later improvements.
+Roland McGrath got it to configure the GNU C Library, wrote the
+ at command{autoheader} script to automate the creation of C header file
+templates, and added a @option{--verbose} option to @command{configure}.
+Noah Friedman added the @option{--autoconf-dir} option and
+ at code{AC_MACRODIR} environment variable. (He also coined the term
+ at dfn{autoconfiscate} to mean ``adapt a software package to use
+Autoconf''.) Roland and Noah improved the quoting protection in
+ at code{AC_DEFINE} and fixed many bugs, especially when I got sick of
+dealing with portability problems from February through June, 1993.
+
+ at node Deuteronomy
+ at section Deuteronomy
+
+A long wish list for major features had accumulated, and the effect of
+several years of patching by various people had left some residual
+cruft. In April 1994, while working for Cygnus Support, I began a major
+revision of Autoconf. I added most of the features of the Cygnus
+ at command{configure} that Autoconf had lacked, largely by adapting the
+relevant parts of Cygnus @command{configure} with the help of david zuhn
+and Ken Raeburn. These features include support for using
+ at file{config.sub}, @file{config.guess}, @option{--host}, and
+ at option{--target}; making links to files; and running @command{configure}
+scripts in subdirectories. Adding these features enabled Ken to convert
+GNU @code{as}, and Rob Savoye to convert DejaGNU, to using
+Autoconf.
+
+I added more features in response to other peoples' requests. Many
+people had asked for @command{configure} scripts to share the results of
+the checks between runs, because (particularly when configuring a large
+source tree, like Cygnus does) they were frustratingly slow. Mike
+Haertel suggested adding site-specific initialization scripts. People
+distributing software that had to unpack on MS-DOS asked for a way to
+override the @file{.in} extension on the file names, which produced file
+names like @file{config.h.in} containing two dots. Jim Avera did an
+extensive examination of the problems with quoting in @code{AC_DEFINE}
+and @code{AC_SUBST}; his insights led to significant improvements.
+Richard Stallman asked that compiler output be sent to @file{config.log}
+instead of @file{/dev/null}, to help people debug the Emacs
+ at command{configure} script.
+
+I made some other changes because of my dissatisfaction with the quality
+of the program. I made the messages showing results of the checks less
+ambiguous, always printing a result. I regularized the names of the
+macros and cleaned up coding style inconsistencies. I added some
+auxiliary utilities that I had developed to help convert source code
+packages to use Autoconf. With the help of Fran@,{c}ois Pinard, I made
+the macros not interrupt each others' messages. (That feature revealed
+some performance bottlenecks in GNU M4, which he hastily
+corrected!) I reorganized the documentation around problems people want
+to solve. And I began a test suite, because experience had shown that
+Autoconf has a pronounced tendency to regress when we change it.
+
+Again, several alpha testers gave invaluable feedback, especially
+Fran@,{c}ois Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn,
+and Mark Eichin.
+
+Finally, version 2.0 was ready. And there was much rejoicing. (And I
+have free time again. I think. Yeah, right.)
+
+
+ at c ========================================================== Appendices
+
+
+ at node GNU Free Documentation License
+ at appendix GNU Free Documentation License
+
+ at include fdl.texi
+
+ at node Indices
+ at appendix Indices
+
+ at menu
+* 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
+ at end menu
+
+ at node Environment Variable Index
+ at appendixsec Environment Variable Index
+
+This is an alphabetical list of the environment variables that might
+influence Autoconf checks.
+
+ at printindex ev
+
+ at node Output Variable Index
+ at appendixsec Output Variable Index
+
+This is an alphabetical list of the variables that Autoconf can
+substitute into files that it creates, typically one or more
+makefiles. @xref{Setting Output Variables}, for more information
+on how this is done.
+
+ at printindex ov
+
+ at node Preprocessor Symbol Index
+ at appendixsec Preprocessor Symbol Index
+
+This is an alphabetical list of the C preprocessor symbols that the
+Autoconf macros define. To work with Autoconf, C source code needs to
+use these names in @code{#if} or @code{#ifdef} directives.
+
+ at printindex cv
+
+ at node Cache Variable Index
+ at appendixsec Cache Variable Index
+
+This is an alphabetical list of documented cache variables used
+by macros defined in Autoconf. Autoconf macros may use additional cache
+variables internally.
+ at ifset shortindexflag
+To make the list easier to use, the variables are listed without their
+preceding @samp{ac_cv_}.
+ at end ifset
+
+ at printindex CA
+
+ at node Autoconf Macro Index
+ at appendixsec Autoconf Macro Index
+
+This is an alphabetical list of the Autoconf macros.
+ at ifset shortindexflag
+To make the list easier to use, the macros are listed without their
+preceding @samp{AC_}.
+ at end ifset
+
+ at printindex AC
+
+ at node M4 Macro Index
+ at appendixsec M4 Macro Index
+
+This is an alphabetical list of the M4, M4sugar, and M4sh macros.
+ at ifset shortindexflag
+To make the list easier to use, the macros are listed without their
+preceding @samp{m4_} or @samp{AS_}. The prefix is @samp{m4_} for
+all-lowercase macro names and @samp{AS_} for all-uppercase macro
+names.
+ at end ifset
+
+ at printindex MS
+
+ at node Autotest Macro Index
+ at appendixsec Autotest Macro Index
+
+This is an alphabetical list of the Autotest macros.
+ at ifset shortindexflag
+To make the list easier to use, the macros are listed without their
+preceding @samp{AT_}.
+ at end ifset
+
+ at printindex AT
+
+ at node Program & Function Index
+ at appendixsec Program and Function Index
+
+This is an alphabetical list of the programs and functions whose
+portability is discussed in this document.
+
+ at printindex pr
+
+ at node Concept Index
+ at appendixsec Concept Index
+
+This is an alphabetical list of the files, tools, and concepts
+introduced in this document.
+
+ at printindex cp
+
+ at bye
+
+ at c LocalWords: texinfo setfilename autoconf texi settitle setchapternewpage
+ at c LocalWords: setcontentsaftertitlepage finalout ARG ovar varname dvar acx
+ at c LocalWords: makeinfo dvi defcodeindex ev ov CPP cv Autotest mv defindex fn
+ at c LocalWords: shortindexflag iftex ifset acindex ACindex ifclear ahindex fu
+ at c LocalWords: asindex MSindex atindex ATindex auindex hdrindex prindex FIXME
+ at c LocalWords: msindex alloca fnindex Aaarg indices FSF's dircategory ifnames
+ at c LocalWords: direntry autoscan autoreconf autoheader autoupdate config FDs
+ at c LocalWords: testsuite titlepage Elliston Demaille vskip filll ifnottex hmm
+ at c LocalWords: insertcopying Autoconf's detailmenu Automake Libtool Posix ois
+ at c LocalWords: Systemology Checkpointing Changequote INTERCAL changequote dfn
+ at c LocalWords: Quadrigraphs builtins Shellology acconfig Bugward LIBOBJ Imake
+ at c LocalWords: LIBOBJS IFELSE cindex flushright Pinard Metaconfig uref Simons
+ at c LocalWords: distclean uninstall noindent versioning Tromey dir
+ at c LocalWords: SAMS samp aclocal acsite underquoted emph itemx prepend SUBST
+ at c LocalWords: evindex automake Gettext autopoint gettext symlink libtoolize
+ at c LocalWords: defmac INIT tarname ovindex cvindex BUGREPORT PREREQ asis PROG
+ at c LocalWords: SRCDIR srcdir globbing afterwards cmds foos fooo foooo init cd
+ at c LocalWords: builddir timestamp src Imakefile chmod defvar CFLAGS CPPFLAGS
+ at c LocalWords: CXXFLAGS DEFS DHAVE defvarx FCFLAGS FFLAGS LDFLAGS bindir GCC
+ at c LocalWords: datadir datarootdir docdir dvidir htmldir libdir ifnothtml kbd
+ at c LocalWords: includedir infodir libexecdir localedir localstatedir mandir
+ at c LocalWords: oldincludedir pdfdir PDF psdir PostScript sbindir sysconfdir
+ at c LocalWords: sharedstatedir DDATADIR sed tmp pkgdatadir VPATH conf unistd
+ at c LocalWords: undef endif builtin FUNCS ifndef STACKSEG getb GETB YMP fubar
+ at c LocalWords: PRE dest SUBDIRS subdirs fi struct STDC stdlib stddef INTTYPES
+ at c LocalWords: inttypes STDINT stdint AWK AIX Solaris NeXT env EGREP FGREP yy
+ at c LocalWords: LEXLIB YYTEXT lfl nonportable Automake's LN RANLIB byacc INETD
+ at c LocalWords: inetd prog PROGS progs ranlib lmp lXt lX nsl gethostbyname UX
+ at c LocalWords: NextStep isinf isnan glibc IRIX sunmath lm lsunmath pre sizeof
+ at c LocalWords: ld inline malloc putenv setenv FreeBSD realloc SunOS MinGW
+ at c LocalWords: snprintf vsnprintf sprintf vsprintf sscanf gcc strerror ifdef
+ at c LocalWords: strnlen sysconf PAGESIZE unsetenv va fallback memcpy dst FUNC
+ at c LocalWords: PowerPC GNUC libPW pragma Olibcalls CHOWN chown CLOSEDIR VFORK
+ at c LocalWords: closedir FNMATCH fnmatch vfork FSEEKO LARGEFILE fseeko SVR sc
+ at c LocalWords: largefile GETGROUPS getgroups GETLOADAVG DGUX UMAX NLIST KMEM
+ at c LocalWords: SETGID getloadavg nlist GETMNTENT irix
+ at c LocalWords: getmntent UnixWare GETPGRP getpgid getpgrp Posix's pid LSTAT
+ at c LocalWords: lstat rpl MEMCMP memcmp OpenStep MBRTOWC mbrtowc MKTIME mktime
+ at c LocalWords: localtime MMAP mmap OBSTACK obstack obstacks ARGTYPES timeval
+ at c LocalWords: SETPGRP setpgrp defmacx Hurd SETVBUF setvbuf STRCOLL strcoll
+ at c LocalWords: STRTOD strtod DECL STRFTIME strftime SCO UTIME utime VPRINTF
+ at c LocalWords: DOPRNT vprintf doprnt sp unfixable LIBSOURCE LIBSOURCES Eggert
+ at c LocalWords: linux netinet ia Tru XFree DIRENT NDIR dirent ndir multitable
+ at c LocalWords: NAMLEN strlen namlen MKDEV SYSMACROS makedev RESOLV resolv DNS
+ at c LocalWords: inet structs NAMESER arpa NETDB netdb UTekV UTS GCC's kB
+ at c LocalWords: STDBOOL BOOL stdbool cplusplus bool Bool stdarg tm
+ at c LocalWords: ctype strchr strrchr rindex bcopy memmove memchr WEXITSTATUS
+ at c LocalWords: WIFEXITED TIOCGWINSZ GWINSZ termios preprocess preprocessable
+ at c LocalWords: DECLS strdup calloc BLKSIZE blksize RDEV rdev TZNAME tzname pw
+ at c LocalWords: passwd gecos pwd MBSTATE mbstate wchar RETSIGTYPE hup UID uid
+ at c LocalWords: gid ptrdiff uintmax EXEEXT OBJEXT Ae conftest AXP str
+ at c LocalWords: ALIGNOF WERROR Werror cpp HP's WorkShop egcs un fied stdc CXX
+ at c LocalWords: varargs BIGENDIAN Endianness SPARC endianness grep'ed CONST FC
+ at c LocalWords: const STRINGIZE stringizing PARAMS unprotoize protos KCC cxx
+ at c LocalWords: xlC aCC CXXCPP FREEFORM xlf FLIBS FCLIBS ish SRCEXT XTRA LFS
+ at c LocalWords: ISC lcposix MINIX Minix conditionalized inlines hw dD confdefs
+ at c LocalWords: fputs stdout PREPROC ar UFS HFS QNX realtime fstype STATVFS se
+ at c LocalWords: statvfs STATFS statfs func machfile hdr lelf raboof DEFUN GTK
+ at c LocalWords: GTKMM Grmph ified ine defn baz EOF qar Ahhh changecom algol io
+ at c LocalWords: changeword quadrigraphs quadrigraph dnl SGI atoi overquoting
+ at c LocalWords: Aas Wcross sep args namespace undefine bpatsubst popdef dquote
+ at c LocalWords: bregexp Overquote overquotation meisch maisch meische maische
+ at c LocalWords: miscian DIRNAME dirname MKDIR CATFILE XMKMF TRAVOLTA celsius
+ at c LocalWords: EMX emxos Emacsen Korn DYNIX subshell posix Ksh ksh Pdksh Zsh
+ at c LocalWords: pdksh zsh Allbery Lipe Kubota UWS zorglub stderr eval esac lfn
+ at c LocalWords: drivespec Posixy DJGPP doschk prettybird LPT pfew Zsh's yu yaa
+ at c LocalWords: yM uM aM firebird IP subdir misparses ok Unpatched abc bc zA
+ at c LocalWords: CDPATH DUALCASE LINENO prepass Subshells lineno NULLCMD cmp wc
+ at c LocalWords: MAILPATH scanset arg NetBSD Almquist printf expr cp
+ at c LocalWords: Oliva awk Aaaaarg cmd regex xfoo GNV OpenVMS VM
+ at c LocalWords: sparc Proulx nbar nfoo maxdepth acdilrtu TWG mc
+ at c LocalWords: mkdir exe uname OpenBSD Fileutils mktemp umask TMPDIR guid os
+ at c LocalWords: fooXXXXXX Unicos utimes hpux hppa unescaped
+ at c LocalWords: pmake DOS's gmake ifoo DESTDIR autoconfiscated pc coff mips gg
+ at c LocalWords: dec ultrix cpu wildcards rpcc rdtsc powerpc readline
+ at c LocalWords: withval vxworks gless localcache usr LOFF loff CYGWIN Cygwin
+ at c LocalWords: cygwin SIGLIST siglist SYSNDIR SYSDIR ptx lseq rusage elif MSC
+ at c LocalWords: lfoo POUNDBANG lsun NIS getpwnam SYSCALLS RSH INTL lintl aix
+ at c LocalWords: intl lx ldir syslog bsd EPI toolchain netbsd objext de KNR nn
+ at c LocalWords: fication LTLIBOBJS Wdiff TESTDIR atconfig atlocal akim XFAIL
+ at c LocalWords: ChangeLog prepended errexit smallexample TESTSUITEFLAGS GPL er
+ at c LocalWords: installcheck autotest indir Pixley Bothner Eichin Kerberos adl
+ at c LocalWords: DISTCLEANFILES preprocessor's fileutils Stallman Murphey Stenn
+ at c LocalWords: Manfredi Autoconfig TCL FSP david zuhn Blandy MACRODIR Raeburn
+ at c LocalWords: autoconfiscate Savoye Haertel Avera Meyering fdl appendixsec
+ at c LocalWords: printindex american LIBOBJDIR LibdirTest ERLCFLAGS OBJCFLAGS
+ at c LocalWords: VER Gnulib online xyes strcpy TYPEOF typeof OBJC objcc objc ln
+ at c LocalWords: GOBJC OTP ERLC erl valloc decr dumpdef errprint incr
+ at c LocalWords: esyscmd len maketemp pushdef substr syscmd sysval translit txt
+ at c LocalWords: sinclude foreach myvar tolower toupper uniq BASENAME STDIN
+ at c LocalWords: Dynix basename aname cname macroexpands xno xcheck
+ at c LocalWords: LIBREADLINE lreadline lncurses libreadline
+
+ at c Local Variables:
+ at c fill-column: 72
+ at c ispell-local-dictionary: "american"
+ at c indent-tabs-mode: nil
+ at c whitespace-check-buffer-indent: nil
+ at c End:
diff --git a/debian/docs/src/autoconf/2.69/fdl.texi b/debian/docs/src/autoconf/2.69/fdl.texi
new file mode 100644
index 0000000..cb71f05
--- /dev/null
+++ b/debian/docs/src/autoconf/2.69/fdl.texi
@@ -0,0 +1,505 @@
+ at c The GNU Free Documentation License.
+ at center Version 1.3, 3 November 2008
+
+ at c This file is intended to be included within another document,
+ at c hence no sectioning command or @node.
+
+ at display
+Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
+ at uref{http://fsf.org/}
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+ at end display
+
+ at enumerate 0
+ at item
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document @dfn{free} in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
+ at item
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The ``Document'', below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as ``you''. You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section
+of the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall
+subject (or to related matters) and contains nothing that could fall
+directly within that overall subject. (Thus, if the Document is in
+part a textbook of mathematics, a Secondary Section may not explain
+any mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A copy that is not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, La at TeX{} input
+format, SGML or XML using a publicly available
+DTD, and standard-conforming simple HTML,
+PostScript or PDF designed for human modification. Examples
+of transparent image formats include PNG, XCF and
+JPG. Opaque formats include proprietary formats that can be
+read and edited only by proprietary word processors, SGML or
+XML for which the DTD and/or processing tools are
+not generally available, and the machine-generated HTML,
+PostScript or PDF produced by some word processors for
+output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+The ``publisher'' means any person or entity that distributes copies
+of the Document to the public.
+
+A section ``Entitled XYZ'' means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as ``Acknowledgements'',
+``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
+of such a section when you modify the Document means that it remains a
+section ``Entitled XYZ'' according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
+ at item
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+ at item
+COPYING IN QUANTITY
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+ at item
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
+ at enumerate A
+ at item
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
+ at item
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has fewer than five),
+unless they release you from this requirement.
+
+ at item
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+ at item
+Preserve all the copyright notices of the Document.
+
+ at item
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+ at item
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
+ at item
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
+ at item
+Include an unaltered copy of this License.
+
+ at item
+Preserve the section Entitled ``History'', Preserve its Title, and add
+to it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section Entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
+ at item
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
+ at item
+For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
+the Title of the section, and preserve in the section all the
+substance and tone of each of the contributor acknowledgements and/or
+dedications given therein.
+
+ at item
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
+ at item
+Delete any section Entitled ``Endorsements''. Such a section
+may not be included in the Modified Version.
+
+ at item
+Do not retitle any existing section to be Entitled ``Endorsements'' or
+to conflict in title with any Invariant Section.
+
+ at item
+Preserve any Warranty Disclaimers.
+ at end enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+ at item
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled ``History''
+in the various original documents, forming one section Entitled
+``History''; likewise combine any sections Entitled ``Acknowledgements'',
+and any sections Entitled ``Dedications''. You must delete all
+sections Entitled ``Endorsements.''
+
+ at item
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+ at item
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an ``aggregate'' if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
+ at item
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled ``Acknowledgements'',
+``Dedications'', or ``History'', the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
+ at item
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document
+except as expressly provided under this License. Any attempt
+otherwise to copy, modify, sublicense, or distribute it is void, and
+will automatically terminate your rights under this License.
+
+However, if you cease all violation of this License, then your license
+from a particular copyright holder is reinstated (a) provisionally,
+unless and until the copyright holder explicitly and finally
+terminates your license, and (b) permanently, if the copyright holder
+fails to notify you of the violation by some reasonable means prior to
+60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License. If your rights have been terminated and not permanently
+reinstated, receipt of a copy of some or all of the same material does
+not give you any rights to use it.
+
+ at item
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
+ at uref{http://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation. If the Document
+specifies that a proxy can decide which future versions of this
+License can be used, that proxy's public statement of acceptance of a
+version permanently authorizes you to choose that version for the
+Document.
+
+ at item
+RELICENSING
+
+``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any
+World Wide Web server that publishes copyrightable works and also
+provides prominent facilities for anybody to edit those works. A
+public wiki that anybody can edit is an example of such a server. A
+``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the
+site means any set of copyrightable works thus published on the MMC
+site.
+
+``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0
+license published by Creative Commons Corporation, a not-for-profit
+corporation with a principal place of business in San Francisco,
+California, as well as future copyleft versions of that license
+published by that same organization.
+
+``Incorporate'' means to publish or republish a Document, in whole or
+in part, as part of another Document.
+
+An MMC is ``eligible for relicensing'' if it is licensed under this
+License, and if all works that were first published under this License
+somewhere other than this MMC, and subsequently incorporated in whole
+or in part into the MMC, (1) had no cover texts or invariant sections,
+and (2) were thus incorporated prior to November 1, 2008.
+
+The operator of an MMC Site may republish an MMC contained in the site
+under CC-BY-SA on the same site at any time before August 1, 2009,
+provided the MMC is eligible for relicensing.
+
+ at end enumerate
+
+ at page
+ at heading ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+ at smallexample
+ at group
+ Copyright (C) @var{year} @var{your name}.
+ 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''.
+ at end group
+ at end smallexample
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the ``with at dots{}Texts.''@: line with this:
+
+ at smallexample
+ at group
+ with the Invariant Sections being @var{list their titles}, with
+ the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
+ being @var{list}.
+ at end group
+ at end smallexample
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+ at c Local Variables:
+ at c ispell-local-pdict: "ispell-dict"
+ at c End:
diff --git a/debian/docs/src/autoconf/2.69/gnu-oids.texi b/debian/docs/src/autoconf/2.69/gnu-oids.texi
new file mode 100644
index 0000000..ecbd59b
--- /dev/null
+++ b/debian/docs/src/autoconf/2.69/gnu-oids.texi
@@ -0,0 +1,55 @@
+ at c This table of OID's is included in the GNU Coding Standards.
+ at c
+ at c Copyright 2008, 2009, 2010 Free Software Foundation, Inc.
+ at c
+ at c Copying and distribution of this file, with or without modification,
+ at c are permitted in any medium without royalty provided the copyright
+ at c notice and this notice are preserved.
+ at c
+ at c When adding new OIDs, please add them also to
+ at c http://www.alvestrand.no/objectid/ (except it gets an internal
+ at c server error, so never mind)
+ at c (Our page is http://www.alvestrand.no/objectid/1.3.6.1.4.1.11591.html.)
+
+1.3.6.1.4.1.11591 GNU
+
+1.3.6.1.4.1.11591.1 GNU Radius
+
+1.3.6.1.4.1.11591.2 GnuPG
+ 1.3.6.1.4.1.11591.2.1 notation
+ 1.3.6.1.4.1.11591.2.1.1 pkaAddress
+
+1.3.6.1.4.1.11591.3 GNU Radar
+
+1.3.6.1.4.1.11591.4 GNU GSS
+
+ at c Added 2008-10-24 on request from Sergey Poznyakoff <gray at gnu.org.ua>
+1.3.6.1.4.1.11591.5 GNU Mailutils
+
+ at c Added 2009-03-03 on request from Simon Josefsson <simon at josefsson.org>
+1.3.6.1.4.1.11591.6 GNU Shishi
+
+ at c Added 2010-05-17 on request from Eric Blossom <eb at comsec.com>
+1.3.6.1.4.1.11591.7 GNU Radio
+
+ at c Added 2010-07-02 on request from Sergey Poznyakoff <gray at gnu.org.ua>
+1.3.6.1.4.1.11591.8 GNU Dico
+
+1.3.6.1.4.1.11591.12 digestAlgorithm
+ 1.3.6.1.4.1.11591.12.2 TIGER/192
+ 1.3.6.1.4.1.11591.13 encryptionAlgorithm
+ 1.3.6.1.4.1.11591.13.2 Serpent
+ 1.3.6.1.4.1.11591.13.2.1 Serpent-128-ECB
+ 1.3.6.1.4.1.11591.13.2.2 Serpent-128-CBC
+ 1.3.6.1.4.1.11591.13.2.3 Serpent-128-OFB
+ 1.3.6.1.4.1.11591.13.2.4 Serpent-128-CFB
+ 1.3.6.1.4.1.11591.13.2.21 Serpent-192-ECB
+ 1.3.6.1.4.1.11591.13.2.22 Serpent-192-CBC
+ 1.3.6.1.4.1.11591.13.2.23 Serpent-192-OFB
+ 1.3.6.1.4.1.11591.13.2.24 Serpent-192-CFB
+ 1.3.6.1.4.1.11591.13.2.41 Serpent-256-ECB
+ 1.3.6.1.4.1.11591.13.2.42 Serpent-256-CBC
+ 1.3.6.1.4.1.11591.13.2.43 Serpent-256-OFB
+ 1.3.6.1.4.1.11591.13.2.44 Serpent-256-CFB
+ 1.3.6.1.4.1.11591.14 CRC algorithms
+ 1.3.6.1.4.1.11591.14.1 CRC 32
diff --git a/debian/docs/src/autoconf/2.69/install.texi b/debian/docs/src/autoconf/2.69/install.texi
new file mode 100644
index 0000000..4c2ffb5
--- /dev/null
+++ b/debian/docs/src/autoconf/2.69/install.texi
@@ -0,0 +1,437 @@
+ at c This file is included by autoconf.texi and is used to produce
+ at c the INSTALL file.
+
+ at ifclear autoconf
+
+ at unnumbered Installation Instructions
+
+Copyright @copyright{} 1994-1996, 1999-2002, 2004-2012 Free Software
+Foundation, Inc.
+
+Copying and distribution of this file, with or without modification, are
+permitted in any medium without royalty provided the copyright notice
+and this notice are preserved. This file is offered as-is, without
+warranty of any kind.
+
+ at end ifclear
+
+ at node Basic Installation
+ at section Basic Installation
+
+Briefly, the shell commands @samp{./configure; make; make install}
+should configure, build, and install this package. The following
+more-detailed instructions are generic; see the @file{README} file for
+instructions specific to this package.
+ at ifclear autoconf
+Some packages provide this @file{INSTALL} file but do not implement all
+of the features documented below. The lack of an optional feature in a
+given package is not necessarily a bug.
+ at end ifclear
+More recommendations for GNU packages can be found in
+ at ref{Makefile Conventions, , Makefile Conventions, standards,
+GNU Coding Standards}.
+
+The @command{configure} shell script attempts to guess correct values
+for various system-dependent variables used during compilation. It uses
+those values to create a @file{Makefile} in each directory of the
+package. It may also create one or more @file{.h} files containing
+system-dependent definitions. Finally, it creates a shell script
+ at file{config.status} that you can run in the future to recreate the
+current configuration, and a file @file{config.log} containing compiler
+output (useful mainly for debugging @command{configure}).
+
+It can also use an optional file (typically called @file{config.cache}
+and enabled with @option{--cache-file=config.cache} or simply
+ at option{-C}) that saves the results of its tests to speed up
+reconfiguring. Caching is disabled by default to prevent problems with
+accidental use of stale cache files.
+
+If you need to do unusual things to compile the package, please try to
+figure out how @command{configure} could check whether to do them, and
+mail diffs or instructions to the address given in the @file{README} so
+they can be considered for the next release. If you are using the
+cache, and at some point @file{config.cache} contains results you don't
+want to keep, you may remove or edit it.
+
+The file @file{configure.ac} (or @file{configure.in}) is used to create
+ at file{configure} by a program called @command{autoconf}. You need
+ at file{configure.ac} if you want to change it or regenerate
+ at file{configure} using a newer version of @command{autoconf}.
+
+The simplest way to compile this package is:
+
+ at enumerate
+ at item
+ at command{cd} to the directory containing the package's source code and type
+ at samp{./configure} to configure the package for your system.
+
+Running @command{configure} might take a while. While running, it prints some
+messages telling which features it is checking for.
+
+ at item
+Type @samp{make} to compile the package.
+
+ at item
+Optionally, type @samp{make check} to run any self-tests that come with
+the package, generally using the just-built uninstalled binaries.
+
+ at item
+Type @samp{make install} to install the programs and any data files and
+documentation. When installing into a prefix owned by root, it is
+recommended that the package be configured and built as a regular user,
+and only the @samp{make install} phase executed with root privileges.
+
+ at item
+Optionally, type @samp{make installcheck} to repeat any self-tests, but
+this time using the binaries in their final installed location. This
+target does not install anything. Running this target as a regular
+user, particularly if the prior @samp{make install} required root
+privileges, verifies that the installation completed correctly.
+
+ at item
+You can remove the program binaries and object files from the source
+code directory by typing @samp{make clean}. To also remove the files
+that @command{configure} created (so you can compile the package for a
+different kind of computer), type @samp{make distclean}. There is also
+a @samp{make maintainer-clean} target, but that is intended mainly for
+the package's developers. If you use it, you may have to get all sorts
+of other programs in order to regenerate files that came with the
+distribution.
+
+ at item
+Often, you can also type @samp{make uninstall} to remove the installed
+files again. In practice, not all packages have tested that
+uninstallation works correctly, even though it is required by the
+GNU Coding Standards.
+
+ at item
+Some packages, particularly those that use Automake, provide @samp{make
+distcheck}, which can by used by developers to test that all other
+targets like @samp{make install} and @samp{make uninstall} work
+correctly. This target is generally not run by end users.
+ at end enumerate
+
+ at node Compilers and Options
+ at section Compilers and Options
+
+Some systems require unusual options for compilation or linking that the
+ at command{configure} script does not know about. Run @samp{./configure
+--help} for details on some of the pertinent environment variables.
+
+You can give @command{configure} initial values for configuration
+parameters by setting variables in the command line or in the environment.
+Here is an example:
+
+ at example
+./configure CC=c99 CFLAGS=-g LIBS=-lposix
+ at end example
+
+ at xref{Defining Variables}, for more details.
+
+
+ at node Multiple Architectures
+ at section Compiling For Multiple Architectures
+
+You can compile the package for more than one kind of computer at the
+same time, by placing the object files for each architecture in their
+own directory. To do this, you can use GNU @command{make}.
+ at command{cd} to the directory where you want the object files and
+executables to go and run the @command{configure} script.
+ at command{configure} automatically checks for the source code in the
+directory that @command{configure} is in and in @file{..}. This is
+known as a @dfn{VPATH} build.
+
+With a non-GNU @command{make},
+it is safer to compile the package for one
+architecture at a time in the source code directory. After you have
+installed the package for one architecture, use @samp{make distclean}
+before reconfiguring for another architecture.
+
+On MacOS X 10.5 and later systems, you can create libraries and
+executables that work on multiple system types---known as @dfn{fat} or
+ at dfn{universal} binaries---by specifying multiple @option{-arch} options
+to the compiler but only a single @option{-arch} option to the
+preprocessor. Like this:
+
+ at example
+./configure CC="gcc -arch i386 -arch x86_64 -arch ppc -arch ppc64" \
+ CXX="g++ -arch i386 -arch x86_64 -arch ppc -arch ppc64" \
+ CPP="gcc -E" CXXCPP="g++ -E"
+ at end example
+
+This is not guaranteed to produce working output in all cases, you may
+have to build one architecture at a time and combine the results
+using the @command{lipo} tool if you have problems.
+
+ at node Installation Names
+ at section Installation Names
+
+By default, @samp{make install} installs the package's commands under
+ at file{/usr/local/bin}, include files under @file{/usr/local/include}, etc.
+You can specify an
+installation prefix other than @file{/usr/local} by giving
+ at command{configure} the option @option{--prefix=@var{prefix}}, where
+ at var{prefix} must be an absolute file name.
+
+You can specify separate installation prefixes for architecture-specific
+files and architecture-independent files. If you pass the option
+ at option{--exec-prefix=@var{prefix}} to @command{configure}, the
+package uses @var{prefix} as the prefix for installing programs and
+libraries. Documentation and other data files still use the
+regular prefix.
+
+In addition, if you use an unusual directory layout you can give options
+like @option{--bindir=@var{dir}} to specify different values for
+particular kinds of files. Run @samp{configure --help} for a list of
+the directories you can set and what kinds of files go in them. In
+general, the default for these options is expressed in terms of
+ at samp{$@{prefix@}}, so that specifying just @option{--prefix} will
+affect all of the other directory specifications that were not
+explicitly provided.
+
+The most portable way to affect installation locations is to pass the
+correct locations to @command{configure}; however, many packages provide
+one or both of the following shortcuts of passing variable assignments
+to the @samp{make install} command line to change installation locations
+without having to reconfigure or recompile.
+
+The first method involves providing an override variable for each
+affected directory. For example, @samp{make install
+prefix=/alternate/directory} will choose an alternate location for all
+directory configuration variables that were expressed in terms of
+ at samp{$@{prefix@}}. Any directories that were specified during
+ at command{configure}, but not in terms of @samp{$@{prefix@}}, must each be
+overridden at install time for the entire
+installation to be relocated. The approach of makefile variable
+overrides for each directory variable is required by the GNU
+Coding Standards, and ideally causes no recompilation. However, some
+platforms have known limitations with the semantics of shared libraries
+that end up requiring recompilation when using this method, particularly
+noticeable in packages that use GNU Libtool.
+
+The second method involves providing the @samp{DESTDIR} variable. For
+example, @samp{make install DESTDIR=/alternate/directory} will prepend
+ at samp{/alternate/directory} before all installation names. The approach
+of @samp{DESTDIR} overrides is not required by the GNU Coding
+Standards, and does not work on platforms that have drive letters. On
+the other hand, it does better at avoiding recompilation issues, and
+works well even when some directory options were not specified in terms
+of @samp{$@{prefix@}} at @command{configure} time.
+
+ at node Optional Features
+ at section Optional Features
+
+If the package supports it, you can cause programs to be installed with
+an extra prefix or suffix on their names by giving @command{configure}
+the option @option{--program-prefix=@var{PREFIX}} or
+ at option{--program-suffix=@var{SUFFIX}}.
+
+Some packages pay attention to @option{--enable- at var{feature}} options
+to @command{configure}, where @var{feature} indicates an optional part
+of the package. They may also pay attention to
+ at option{--with- at var{package}} options, where @var{package} is something
+like @samp{gnu-as} or @samp{x} (for the X Window System). The
+ at file{README} should mention any @option{--enable-} and @option{--with-}
+options that the package recognizes.
+
+For packages that use the X Window System, @command{configure} can
+usually find the X include and library files automatically, but if it
+doesn't, you can use the @command{configure} options
+ at option{--x-includes=@var{dir}} and @option{--x-libraries=@var{dir}} to
+specify their locations.
+
+Some packages offer the ability to configure how verbose the execution
+of @command{make} will be. For these packages, running
+ at samp{./configure --enable-silent-rules} sets the default to minimal
+output, which can be overridden with @code{make V=1}; while running
+ at samp{./configure --disable-silent-rules} sets the default to verbose,
+which can be overridden with @code{make V=0}.
+
+ at node Particular Systems
+ at section Particular systems
+
+On HP-UX, the default C compiler is not ANSI C compatible. If GNU CC is
+not installed, it is recommended to use the following options in order to
+use an ANSI C compiler:
+
+ at example
+./configure CC="cc -Ae -D_XOPEN_SOURCE=500"
+ at end example
+
+ at noindent
+and if that doesn't work, install pre-built binaries of GCC for HP-UX.
+
+HP-UX @command{make} updates targets which have the same time stamps as
+their prerequisites, which makes it generally unusable when shipped
+generated files such as @command{configure} are involved. Use GNU
+ at command{make} instead.
+
+On OSF/1 a.k.a.@: Tru64, some versions of the default C compiler cannot
+parse its @code{<wchar.h>} header file. The option @option{-nodtk} can be
+used as a workaround. If GNU CC is not installed, it is therefore
+recommended to try
+
+ at example
+./configure CC="cc"
+ at end example
+
+ at noindent
+and if that doesn't work, try
+
+ at example
+./configure CC="cc -nodtk"
+ at end example
+
+On Solaris, don't put @code{/usr/ucb} early in your @env{PATH}. This
+directory contains several dysfunctional programs; working variants
+of these programs are available in @code{/usr/bin}. So, if you need
+ at code{/usr/ucb} in your @env{PATH}, put it @emph{after} @code{/usr/bin}.
+
+On Haiku, software installed for all users goes in @file{/boot/common},
+not @file{/usr/local}. It is recommended to use the following options:
+
+ at example
+./configure --prefix=/boot/common
+ at end example
+
+ at node System Type
+ at section Specifying the System Type
+
+There may be some features @command{configure} cannot figure out
+automatically, but needs to determine by the type of machine the package
+will run on. Usually, assuming the package is built to be run on the
+ at emph{same} architectures, @command{configure} can figure that out, but
+if it prints a message saying it cannot guess the machine type, give it
+the @option{--build=@var{type}} option. @var{type} can either be a
+short name for the system type, such as @samp{sun4}, or a canonical name
+which has the form:
+
+ at example
+ at var{cpu}- at var{company}- at var{system}
+ at end example
+
+ at noindent
+where @var{system} can have one of these forms:
+
+ at example
+ at var{os}
+ at var{kernel}- at var{os}
+ at end example
+
+See the file @file{config.sub} for the possible values of each field.
+If @file{config.sub} isn't included in this package, then this package
+doesn't need to know the machine type.
+
+If you are @emph{building} compiler tools for cross-compiling, you
+should use the option @option{--target=@var{type}} to select the type of
+system they will produce code for.
+
+If you want to @emph{use} a cross compiler, that generates code for a
+platform different from the build platform, you should specify the
+ at dfn{host} platform (i.e., that on which the generated programs will
+eventually be run) with @option{--host=@var{type}}.
+
+ at node Sharing Defaults
+ at section Sharing Defaults
+
+If you want to set default values for @command{configure} scripts to
+share, you can create a site shell script called @file{config.site} that
+gives default values for variables like @code{CC}, @code{cache_file},
+and @code{prefix}. @command{configure} looks for
+ at file{@var{prefix}/share/config.site} if it exists, then
+ at file{@var{prefix}/etc/config.site} if it exists. Or, you can set the
+ at code{CONFIG_SITE} environment variable to the location of the site
+script. A warning: not all @command{configure} scripts look for a site
+script.
+
+ at node Defining Variables
+ at section Defining Variables
+
+Variables not defined in a site shell script can be set in the
+environment passed to @command{configure}. However, some packages may
+run configure again during the build, and the customized values of these
+variables may be lost. In order to avoid this problem, you should set
+them in the @command{configure} command line, using @samp{VAR=value}.
+For example:
+
+ at example
+./configure CC=/usr/local2/bin/gcc
+ at end example
+
+ at noindent
+causes the specified @command{gcc} to be used as the C compiler (unless it is
+overridden in the site shell script).
+
+ at noindent
+Unfortunately, this technique does not work for @env{CONFIG_SHELL} due
+to an Autoconf limitation. Until the limitation is lifted, you can use
+this workaround:
+
+ at example
+CONFIG_SHELL=/bin/bash ./configure CONFIG_SHELL=/bin/bash
+ at end example
+
+ at node configure Invocation
+ at section @command{configure} Invocation
+
+ at command{configure} recognizes the following options to control how it
+operates.
+
+ at table @option
+ at item --help
+ at itemx -h
+Print a summary of all of the options to @command{configure}, and exit.
+
+ at item --help=short
+ at itemx --help=recursive
+Print a summary of the options unique to this package's
+ at command{configure}, and exit. The @code{short} variant lists options
+used only in the top level, while the @code{recursive} variant lists
+options also present in any nested packages.
+
+ at item --version
+ at itemx -V
+Print the version of Autoconf used to generate the @command{configure}
+script, and exit.
+
+ at item --cache-file=@var{file}
+ at cindex Cache, enabling
+Enable the cache: use and save the results of the tests in @var{file},
+traditionally @file{config.cache}. @var{file} defaults to
+ at file{/dev/null} to disable caching.
+
+ at item --config-cache
+ at itemx -C
+Alias for @option{--cache-file=config.cache}.
+
+ at item --quiet
+ at itemx --silent
+ at itemx -q
+Do not print messages saying which checks are being made. To suppress
+all normal output, redirect it to @file{/dev/null} (any error messages
+will still be shown).
+
+ at item --srcdir=@var{dir}
+Look for the package's source code in directory @var{dir}. Usually
+ at command{configure} can determine that directory automatically.
+
+ at item --prefix=@var{dir}
+Use @var{dir} as the installation prefix. @ref{Installation Names}
+for more details, including other options available for fine-tuning
+the installation locations.
+
+ at item --no-create
+ at itemx -n
+Run the configure checks, but stop before creating any output files.
+ at end table
+
+ at noindent
+ at command{configure} also accepts some other, not widely useful, options.
+Run @samp{configure --help} for more details.
+
+ at c Local Variables:
+ at c fill-column: 72
+ at c ispell-local-dictionary: "american"
+ at c indent-tabs-mode: nil
+ at c whitespace-check-buffer-indent: nil
+ at c End:
diff --git a/debian/docs/src/autoconf/2.69/make-stds.texi b/debian/docs/src/autoconf/2.69/make-stds.texi
new file mode 100644
index 0000000..cdcbb68
--- /dev/null
+++ b/debian/docs/src/autoconf/2.69/make-stds.texi
@@ -0,0 +1,1159 @@
+ at comment This file is included by both standards.texi and make.texinfo.
+ at comment It was broken out of standards.texi on 1/6/93 by roland.
+
+ at node Makefile Conventions
+ at chapter Makefile Conventions
+ at cindex makefile, conventions for
+ at cindex conventions for makefiles
+ at cindex standards for makefiles
+
+ at c Copyright 1992, 1993, 1994, 1995, 1996, 1997, 1998, 2000, 2001,
+ at c 2004, 2005, 2006, 2007, 2008, 2010 Free Software Foundation, Inc.
+ at c
+ at c Permission is granted to copy, distribute and/or modify this document
+ at c under the terms of the GNU Free Documentation License, Version 1.3
+ at c or any later version published by the Free Software Foundation;
+ at c with no Invariant Sections, with no
+ at c Front-Cover Texts, and with no Back-Cover Texts.
+ at c A copy of the license is included in the section entitled ``GNU
+ at c Free Documentation License''.
+
+This
+ at ifinfo
+node
+ at end ifinfo
+ at iftex
+ at ifset CODESTD
+section
+ at end ifset
+ at ifclear CODESTD
+chapter
+ at end ifclear
+ at end iftex
+describes conventions for writing the Makefiles for GNU programs.
+Using Automake will help you write a Makefile that follows these
+conventions. For more information on portable Makefiles, see
+ at sc{posix} and @ref{Portable Make, Portable Make Programming,, autoconf,
+Autoconf}.
+
+
+ at menu
+* Makefile Basics:: General conventions for Makefiles.
+* Utilities in Makefiles:: Utilities to be used in Makefiles.
+* Command Variables:: Variables for specifying commands.
+* DESTDIR:: Supporting staged installs.
+* Directory Variables:: Variables for installation directories.
+* Standard Targets:: Standard targets for users.
+* Install Command Categories:: Three categories of commands in the `install'
+ rule: normal, pre-install and post-install.
+ at end menu
+
+ at node Makefile Basics
+ at section General Conventions for Makefiles
+
+Every Makefile should contain this line:
+
+ at example
+SHELL = /bin/sh
+ at end example
+
+ at noindent
+to avoid trouble on systems where the @code{SHELL} variable might be
+inherited from the environment. (This is never a problem with GNU
+ at code{make}.)
+
+Different @code{make} programs have incompatible suffix lists and
+implicit rules, and this sometimes creates confusion or misbehavior. So
+it is a good idea to set the suffix list explicitly using only the
+suffixes you need in the particular Makefile, like this:
+
+ at example
+.SUFFIXES:
+.SUFFIXES: .c .o
+ at end example
+
+ at noindent
+The first line clears out the suffix list, the second introduces all
+suffixes which may be subject to implicit rules in this Makefile.
+
+Don't assume that @file{.} is in the path for command execution. When
+you need to run programs that are a part of your package during the
+make, please make sure that it uses @file{./} if the program is built as
+part of the make or @file{$(srcdir)/} if the file is an unchanging part
+of the source code. Without one of these prefixes, the current search
+path is used.
+
+The distinction between @file{./} (the @dfn{build directory}) and
+ at file{$(srcdir)/} (the @dfn{source directory}) is important because
+users can build in a separate directory using the @samp{--srcdir} option
+to @file{configure}. A rule of the form:
+
+ at smallexample
+foo.1 : foo.man sedscript
+ sed -f sedscript foo.man > foo.1
+ at end smallexample
+
+ at noindent
+will fail when the build directory is not the source directory, because
+ at file{foo.man} and @file{sedscript} are in the source directory.
+
+When using GNU @code{make}, relying on @samp{VPATH} to find the source
+file will work in the case where there is a single dependency file,
+since the @code{make} automatic variable @samp{$<} will represent the
+source file wherever it is. (Many versions of @code{make} set @samp{$<}
+only in implicit rules.) A Makefile target like
+
+ at smallexample
+foo.o : bar.c
+ $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
+ at end smallexample
+
+ at noindent
+should instead be written as
+
+ at smallexample
+foo.o : bar.c
+ $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@@
+ at end smallexample
+
+ at noindent
+in order to allow @samp{VPATH} to work correctly. When the target has
+multiple dependencies, using an explicit @samp{$(srcdir)} is the easiest
+way to make the rule work well. For example, the target above for
+ at file{foo.1} is best written as:
+
+ at smallexample
+foo.1 : foo.man sedscript
+ sed -f $(srcdir)/sedscript $(srcdir)/foo.man > $@@
+ at end smallexample
+
+GNU distributions usually contain some files which are not source
+files---for example, Info files, and the output from Autoconf, Automake,
+Bison or Flex. Since these files normally appear in the source
+directory, they should always appear in the source directory, not in the
+build directory. So Makefile rules to update them should put the
+updated files in the source directory.
+
+However, if a file does not appear in the distribution, then the
+Makefile should not put it in the source directory, because building a
+program in ordinary circumstances should not modify the source directory
+in any way.
+
+Try to make the build and installation targets, at least (and all their
+subtargets) work correctly with a parallel @code{make}.
+
+ at node Utilities in Makefiles
+ at section Utilities in Makefiles
+
+Write the Makefile commands (and any shell scripts, such as
+ at code{configure}) to run under @code{sh} (both the traditional Bourne
+shell and the @sc{posix} shell), not @code{csh}. Don't use any
+special features of @code{ksh} or @code{bash}, or @sc{posix} features
+not widely supported in traditional Bourne @code{sh}.
+
+The @code{configure} script and the Makefile rules for building and
+installation should not use any utilities directly except these:
+
+ at c dd find
+ at c gunzip gzip md5sum
+ at c mkfifo mknod tee uname
+
+ at example
+awk cat cmp cp diff echo egrep expr false grep install-info ln ls
+mkdir mv printf pwd rm rmdir sed sleep sort tar test touch tr true
+ at end example
+
+Compression programs such as @code{gzip} can be used in the
+ at code{dist} rule.
+
+Generally, stick to the widely-supported (usually
+ at sc{posix}-specified) options and features of these programs. For
+example, don't use @samp{mkdir -p}, convenient as it may be, because a
+few systems don't support it at all and with others, it is not safe
+for parallel execution. For a list of known incompatibilities, see
+ at ref{Portable Shell, Portable Shell Programming,, autoconf, Autoconf}.
+
+
+It is a good idea to avoid creating symbolic links in makefiles, since a
+few file systems don't support them.
+
+The Makefile rules for building and installation can also use compilers
+and related programs, but should do so via @code{make} variables so that the
+user can substitute alternatives. Here are some of the programs we
+mean:
+
+ at example
+ar bison cc flex install ld ldconfig lex
+make makeinfo ranlib texi2dvi yacc
+ at end example
+
+Use the following @code{make} variables to run those programs:
+
+ at example
+$(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
+$(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
+ at end example
+
+When you use @code{ranlib} or @code{ldconfig}, you should make sure
+nothing bad happens if the system does not have the program in question.
+Arrange to ignore an error from that command, and print a message before
+the command to tell the user that failure of this command does not mean
+a problem. (The Autoconf @samp{AC_PROG_RANLIB} macro can help with
+this.)
+
+If you use symbolic links, you should implement a fallback for systems
+that don't have symbolic links.
+
+Additional utilities that can be used via Make variables are:
+
+ at example
+chgrp chmod chown mknod
+ at end example
+
+It is ok to use other utilities in Makefile portions (or scripts)
+intended only for particular systems where you know those utilities
+exist.
+
+ at node Command Variables
+ at section Variables for Specifying Commands
+
+Makefiles should provide variables for overriding certain commands, options,
+and so on.
+
+In particular, you should run most utility programs via variables.
+Thus, if you use Bison, have a variable named @code{BISON} whose default
+value is set with @samp{BISON = bison}, and refer to it with
+ at code{$(BISON)} whenever you need to use Bison.
+
+File management utilities such as @code{ln}, @code{rm}, @code{mv}, and
+so on, need not be referred to through variables in this way, since users
+don't need to replace them with other programs.
+
+Each program-name variable should come with an options variable that is
+used to supply options to the program. Append @samp{FLAGS} to the
+program-name variable name to get the options variable name---for
+example, @code{BISONFLAGS}. (The names @code{CFLAGS} for the C
+compiler, @code{YFLAGS} for yacc, and @code{LFLAGS} for lex, are
+exceptions to this rule, but we keep them because they are standard.)
+Use @code{CPPFLAGS} in any compilation command that runs the
+preprocessor, and use @code{LDFLAGS} in any compilation command that
+does linking as well as in any direct use of @code{ld}.
+
+If there are C compiler options that @emph{must} be used for proper
+compilation of certain files, do not include them in @code{CFLAGS}.
+Users expect to be able to specify @code{CFLAGS} freely themselves.
+Instead, arrange to pass the necessary options to the C compiler
+independently of @code{CFLAGS}, by writing them explicitly in the
+compilation commands or by defining an implicit rule, like this:
+
+ at smallexample
+CFLAGS = -g
+ALL_CFLAGS = -I. $(CFLAGS)
+.c.o:
+ $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
+ at end smallexample
+
+Do include the @samp{-g} option in @code{CFLAGS}, because that is not
+ at emph{required} for proper compilation. You can consider it a default
+that is only recommended. If the package is set up so that it is
+compiled with GCC by default, then you might as well include @samp{-O}
+in the default value of @code{CFLAGS} as well.
+
+Put @code{CFLAGS} last in the compilation command, after other variables
+containing compiler options, so the user can use @code{CFLAGS} to
+override the others.
+
+ at code{CFLAGS} should be used in every invocation of the C compiler,
+both those which do compilation and those which do linking.
+
+Every Makefile should define the variable @code{INSTALL}, which is the
+basic command for installing a file into the system.
+
+Every Makefile should also define the variables @code{INSTALL_PROGRAM}
+and @code{INSTALL_DATA}. (The default for @code{INSTALL_PROGRAM} should
+be @code{$(INSTALL)}; the default for @code{INSTALL_DATA} should be
+ at code{$@{INSTALL@} -m 644}.) Then it should use those variables as the
+commands for actual installation, for executables and non-executables
+respectively. Minimal use of these variables is as follows:
+
+ at example
+$(INSTALL_PROGRAM) foo $(bindir)/foo
+$(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
+ at end example
+
+However, it is preferable to support a @code{DESTDIR} prefix on the
+target files, as explained in the next section.
+
+It is acceptable, but not required, to install multiple files in one
+command, with the final argument being a directory, as in:
+
+ at example
+$(INSTALL_PROGRAM) foo bar baz $(bindir)
+ at end example
+
+
+ at node DESTDIR
+ at section @code{DESTDIR}: Support for Staged Installs
+
+ at vindex DESTDIR
+ at cindex staged installs
+ at cindex installations, staged
+
+ at code{DESTDIR} is a variable prepended to each installed target file,
+like this:
+
+ at example
+$(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
+$(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
+ at end example
+
+The @code{DESTDIR} variable is specified by the user on the @code{make}
+command line as an absolute file name. For example:
+
+ at example
+make DESTDIR=/tmp/stage install
+ at end example
+
+ at noindent
+ at code{DESTDIR} should be supported only in the @code{install*} and
+ at code{uninstall*} targets, as those are the only targets where it is
+useful.
+
+If your installation step would normally install
+ at file{/usr/local/bin/foo} and @file{/usr/@/local/@/lib/@/libfoo.a}, then an
+installation invoked as in the example above would install
+ at file{/tmp/stage/usr/local/bin/foo} and
+ at file{/tmp/stage/usr/local/lib/libfoo.a} instead.
+
+Prepending the variable @code{DESTDIR} to each target in this way
+provides for @dfn{staged installs}, where the installed files are not
+placed directly into their expected location but are instead copied
+into a temporary location (@code{DESTDIR}). However, installed files
+maintain their relative directory structure and any embedded file names
+will not be modified.
+
+You should not set the value of @code{DESTDIR} in your @file{Makefile}
+at all; then the files are installed into their expected locations by
+default. Also, specifying @code{DESTDIR} should not change the
+operation of the software in any way, so its value should not be
+included in any file contents.
+
+ at code{DESTDIR} support is commonly used in package creation. It is
+also helpful to users who want to understand what a given package will
+install where, and to allow users who don't normally have permissions
+to install into protected areas to build and install before gaining
+those permissions. Finally, it can be useful with tools such as
+ at code{stow}, where code is installed in one place but made to appear
+to be installed somewhere else using symbolic links or special mount
+operations. So, we strongly recommend GNU packages support
+ at code{DESTDIR}, though it is not an absolute requirement.
+
+
+ at node Directory Variables
+ at section Variables for Installation Directories
+
+Installation directories should always be named by variables, so it is
+easy to install in a nonstandard place. The standard names for these
+variables and the values they should have in GNU packages are
+described below. They are based on a standard file system layout;
+variants of it are used in GNU/Linux and other modern operating
+systems.
+
+Installers are expected to override these values when calling
+ at command{make} (e.g., @kbd{make prefix=/usr install} or
+ at command{configure} (e.g., @kbd{configure --prefix=/usr}). GNU
+packages should not try to guess which value should be appropriate for
+these variables on the system they are being installed onto: use the
+default settings specified here so that all GNU packages behave
+identically, allowing the installer to achieve any desired layout.
+
+ at cindex directories, creating installation
+ at cindex installation directories, creating
+All installation directories, and their parent directories, should be
+created (if necessary) before they are installed into.
+
+These first two variables set the root for the installation. All the
+other installation directories should be subdirectories of one of
+these two, and nothing should be directly installed into these two
+directories.
+
+ at table @code
+ at item prefix
+ at vindex prefix
+A prefix used in constructing the default values of the variables listed
+below. The default value of @code{prefix} should be @file{/usr/local}.
+When building the complete GNU system, the prefix will be empty and
+ at file{/usr} will be a symbolic link to @file{/}.
+(If you are using Autoconf, write it as @samp{@@prefix@@}.)
+
+Running @samp{make install} with a different value of @code{prefix} from
+the one used to build the program should @emph{not} recompile the
+program.
+
+ at item exec_prefix
+ at vindex exec_prefix
+A prefix used in constructing the default values of some of the
+variables listed below. The default value of @code{exec_prefix} should
+be @code{$(prefix)}.
+(If you are using Autoconf, write it as @samp{@@exec_prefix@@}.)
+
+Generally, @code{$(exec_prefix)} is used for directories that contain
+machine-specific files (such as executables and subroutine libraries),
+while @code{$(prefix)} is used directly for other directories.
+
+Running @samp{make install} with a different value of @code{exec_prefix}
+from the one used to build the program should @emph{not} recompile the
+program.
+ at end table
+
+Executable programs are installed in one of the following directories.
+
+ at table @code
+ at item bindir
+ at vindex bindir
+The directory for installing executable programs that users can run.
+This should normally be @file{/usr/local/bin}, but write it as
+ at file{$(exec_prefix)/bin}.
+(If you are using Autoconf, write it as @samp{@@bindir@@}.)
+
+ at item sbindir
+ at vindex sbindir
+The directory for installing executable programs that can be run from
+the shell, but are only generally useful to system administrators. This
+should normally be @file{/usr/local/sbin}, but write it as
+ at file{$(exec_prefix)/sbin}.
+(If you are using Autoconf, write it as @samp{@@sbindir@@}.)
+
+ at item libexecdir
+ at vindex libexecdir
+ at comment This paragraph adjusted to avoid overfull hbox --roland 5jul94
+The directory for installing executable programs to be run by other
+programs rather than by users. This directory should normally be
+ at file{/usr/local/libexec}, but write it as @file{$(exec_prefix)/libexec}.
+(If you are using Autoconf, write it as @samp{@@libexecdir@@}.)
+
+The definition of @samp{libexecdir} is the same for all packages, so
+you should install your data in a subdirectory thereof. Most packages
+install their data under @file{$(libexecdir)/@var{package-name}/},
+possibly within additional subdirectories thereof, such as
+ at file{$(libexecdir)/@var{package-name}/@var{machine}/@var{version}}.
+ at end table
+
+Data files used by the program during its execution are divided into
+categories in two ways.
+
+ at itemize @bullet
+ at item
+Some files are normally modified by programs; others are never normally
+modified (though users may edit some of these).
+
+ at item
+Some files are architecture-independent and can be shared by all
+machines at a site; some are architecture-dependent and can be shared
+only by machines of the same kind and operating system; others may never
+be shared between two machines.
+ at end itemize
+
+This makes for six different possibilities. However, we want to
+discourage the use of architecture-dependent files, aside from object
+files and libraries. It is much cleaner to make other data files
+architecture-independent, and it is generally not hard.
+
+Here are the variables Makefiles should use to specify directories
+to put these various kinds of files in:
+
+ at table @samp
+ at item datarootdir
+The root of the directory tree for read-only architecture-independent
+data files. This should normally be @file{/usr/local/share}, but
+write it as @file{$(prefix)/share}. (If you are using Autoconf, write
+it as @samp{@@datarootdir@@}.) @samp{datadir}'s default value is
+based on this variable; so are @samp{infodir}, @samp{mandir}, and
+others.
+
+ at item datadir
+The directory for installing idiosyncratic read-only
+architecture-independent data files for this program. This is usually
+the same place as @samp{datarootdir}, but we use the two separate
+variables so that you can move these program-specific files without
+altering the location for Info files, man pages, etc.
+
+ at c raggedright (not until next Texinfo release)
+This should normally be @file{/usr/local/share}, but write it as
+ at file{$(datarootdir)}. (If you are using Autoconf, write it as
+ at samp{@@datadir@@}.)
+ at c end raggedright
+
+The definition of @samp{datadir} is the same for all packages, so you
+should install your data in a subdirectory thereof. Most packages
+install their data under @file{$(datadir)/@var{package-name}/}.
+
+ at item sysconfdir
+The directory for installing read-only data files that pertain to a
+single machine--that is to say, files for configuring a host. Mailer
+and network configuration files, @file{/etc/passwd}, and so forth belong
+here. All the files in this directory should be ordinary ASCII text
+files. This directory should normally be @file{/usr/local/etc}, but
+write it as @file{$(prefix)/etc}.
+(If you are using Autoconf, write it as @samp{@@sysconfdir@@}.)
+
+Do not install executables here in this directory (they probably belong
+in @file{$(libexecdir)} or @file{$(sbindir)}). Also do not install
+files that are modified in the normal course of their use (programs
+whose purpose is to change the configuration of the system excluded).
+Those probably belong in @file{$(localstatedir)}.
+
+ at item sharedstatedir
+The directory for installing architecture-independent data files which
+the programs modify while they run. This should normally be
+ at file{/usr/local/com}, but write it as @file{$(prefix)/com}.
+(If you are using Autoconf, write it as @samp{@@sharedstatedir@@}.)
+
+ at item localstatedir
+The directory for installing data files which the programs modify while
+they run, and that pertain to one specific machine. Users should never
+need to modify files in this directory to configure the package's
+operation; put such configuration information in separate files that go
+in @file{$(datadir)} or @file{$(sysconfdir)}. @file{$(localstatedir)}
+should normally be @file{/usr/local/var}, but write it as
+ at file{$(prefix)/var}.
+(If you are using Autoconf, write it as @samp{@@localstatedir@@}.)
+ at end table
+
+These variables specify the directory for installing certain specific
+types of files, if your program has them. Every GNU package should
+have Info files, so every program needs @samp{infodir}, but not all
+need @samp{libdir} or @samp{lispdir}.
+
+ at table @samp
+ at item includedir
+The directory for installing header files to be included by user
+programs with the C @samp{#include} preprocessor directive. This
+should normally be @file{/usr/local/include}, but write it as
+ at file{$(prefix)/include}.
+(If you are using Autoconf, write it as @samp{@@includedir@@}.)
+
+Most compilers other than GCC do not look for header files in directory
+ at file{/usr/local/include}. So installing the header files this way is
+only useful with GCC. Sometimes this is not a problem because some
+libraries are only really intended to work with GCC. But some libraries
+are intended to work with other compilers. They should install their
+header files in two places, one specified by @code{includedir} and one
+specified by @code{oldincludedir}.
+
+ at item oldincludedir
+The directory for installing @samp{#include} header files for use with
+compilers other than GCC. This should normally be @file{/usr/include}.
+(If you are using Autoconf, you can write it as @samp{@@oldincludedir@@}.)
+
+The Makefile commands should check whether the value of
+ at code{oldincludedir} is empty. If it is, they should not try to use
+it; they should cancel the second installation of the header files.
+
+A package should not replace an existing header in this directory unless
+the header came from the same package. Thus, if your Foo package
+provides a header file @file{foo.h}, then it should install the header
+file in the @code{oldincludedir} directory if either (1) there is no
+ at file{foo.h} there or (2) the @file{foo.h} that exists came from the Foo
+package.
+
+To tell whether @file{foo.h} came from the Foo package, put a magic
+string in the file---part of a comment---and @code{grep} for that string.
+
+ at item docdir
+The directory for installing documentation files (other than Info) for
+this package. By default, it should be
+ at file{/usr/local/share/doc/@var{yourpkg}}, but it should be written as
+ at file{$(datarootdir)/doc/@var{yourpkg}}. (If you are using Autoconf,
+write it as @samp{@@docdir@@}.) The @var{yourpkg} subdirectory, which
+may include a version number, prevents collisions among files with
+common names, such as @file{README}.
+
+ at item infodir
+The directory for installing the Info files for this package. By
+default, it should be @file{/usr/local/share/info}, but it should be
+written as @file{$(datarootdir)/info}. (If you are using Autoconf,
+write it as @samp{@@infodir@@}.) @code{infodir} is separate from
+ at code{docdir} for compatibility with existing practice.
+
+ at item htmldir
+ at itemx dvidir
+ at itemx pdfdir
+ at itemx psdir
+Directories for installing documentation files in the particular
+format. They should all be set to @code{$(docdir)} by default. (If
+you are using Autoconf, write them as @samp{@@htmldir@@},
+ at samp{@@dvidir@@}, etc.) Packages which supply several translations
+of their documentation should install them in
+ at samp{$(htmldir)/}@var{ll}, @samp{$(pdfdir)/}@var{ll}, etc. where
+ at var{ll} is a locale abbreviation such as @samp{en} or @samp{pt_BR}.
+
+ at item libdir
+The directory for object files and libraries of object code. Do not
+install executables here, they probably ought to go in @file{$(libexecdir)}
+instead. The value of @code{libdir} should normally be
+ at file{/usr/local/lib}, but write it as @file{$(exec_prefix)/lib}.
+(If you are using Autoconf, write it as @samp{@@libdir@@}.)
+
+ at item lispdir
+The directory for installing any Emacs Lisp files in this package. By
+default, it should be @file{/usr/local/share/emacs/site-lisp}, but it
+should be written as @file{$(datarootdir)/emacs/site-lisp}.
+
+If you are using Autoconf, write the default as @samp{@@lispdir@@}.
+In order to make @samp{@@lispdir@@} work, you need the following lines
+in your @file{configure.in} file:
+
+ at example
+lispdir='$@{datarootdir@}/emacs/site-lisp'
+AC_SUBST(lispdir)
+ at end example
+
+ at item localedir
+The directory for installing locale-specific message catalogs for this
+package. By default, it should be @file{/usr/local/share/locale}, but
+it should be written as @file{$(datarootdir)/locale}. (If you are
+using Autoconf, write it as @samp{@@localedir@@}.) This directory
+usually has a subdirectory per locale.
+ at end table
+
+Unix-style man pages are installed in one of the following:
+
+ at table @samp
+ at item mandir
+The top-level directory for installing the man pages (if any) for this
+package. It will normally be @file{/usr/local/share/man}, but you
+should write it as @file{$(datarootdir)/man}. (If you are using
+Autoconf, write it as @samp{@@mandir@@}.)
+
+ at item man1dir
+The directory for installing section 1 man pages. Write it as
+ at file{$(mandir)/man1}.
+ at item man2dir
+The directory for installing section 2 man pages. Write it as
+ at file{$(mandir)/man2}
+ at item @dots{}
+
+ at strong{Don't make the primary documentation for any GNU software be a
+man page. Write a manual in Texinfo instead. Man pages are just for
+the sake of people running GNU software on Unix, which is a secondary
+application only.}
+
+ at item manext
+The file name extension for the installed man page. This should contain
+a period followed by the appropriate digit; it should normally be @samp{.1}.
+
+ at item man1ext
+The file name extension for installed section 1 man pages.
+ at item man2ext
+The file name extension for installed section 2 man pages.
+ at item @dots{}
+Use these names instead of @samp{manext} if the package needs to install man
+pages in more than one section of the manual.
+ at end table
+
+And finally, you should set the following variable:
+
+ at table @samp
+ at item srcdir
+The directory for the sources being compiled. The value of this
+variable is normally inserted by the @code{configure} shell script.
+(If you are using Autoconf, use @samp{srcdir = @@srcdir@@}.)
+ at end table
+
+For example:
+
+ at smallexample
+ at c I have changed some of the comments here slightly to fix an overfull
+ at c hbox, so the make manual can format correctly. --roland
+# Common prefix for installation directories.
+# NOTE: This directory must exist when you start the install.
+prefix = /usr/local
+datarootdir = $(prefix)/share
+datadir = $(datarootdir)
+exec_prefix = $(prefix)
+# Where to put the executable for the command `gcc'.
+bindir = $(exec_prefix)/bin
+# Where to put the directories used by the compiler.
+libexecdir = $(exec_prefix)/libexec
+# Where to put the Info files.
+infodir = $(datarootdir)/info
+ at end smallexample
+
+If your program installs a large number of files into one of the
+standard user-specified directories, it might be useful to group them
+into a subdirectory particular to that program. If you do this, you
+should write the @code{install} rule to create these subdirectories.
+
+Do not expect the user to include the subdirectory name in the value of
+any of the variables listed above. The idea of having a uniform set of
+variable names for installation directories is to enable the user to
+specify the exact same values for several different GNU packages. In
+order for this to be useful, all the packages must be designed so that
+they will work sensibly when the user does so.
+
+At times, not all of these variables may be implemented in the current
+release of Autoconf and/or Automake; but as of Autoconf at tie{}2.60, we
+believe all of them are. When any are missing, the descriptions here
+serve as specifications for what Autoconf will implement. As a
+programmer, you can either use a development version of Autoconf or
+avoid using these variables until a stable release is made which
+supports them.
+
+
+ at node Standard Targets
+ at section Standard Targets for Users
+
+All GNU programs should have the following targets in their Makefiles:
+
+ at table @samp
+ at item all
+Compile the entire program. This should be the default target. This
+target need not rebuild any documentation files; Info files should
+normally be included in the distribution, and DVI (and other
+documentation format) files should be made only when explicitly asked
+for.
+
+By default, the Make rules should compile and link with @samp{-g}, so
+that executable programs have debugging symbols. Otherwise, you are
+essentially helpless in the face of a crash, and it is often far from
+easy to reproduce with a fresh build.
+
+ at item install
+Compile the program and copy the executables, libraries, and so on to
+the file names where they should reside for actual use. If there is a
+simple test to verify that a program is properly installed, this target
+should run that test.
+
+Do not strip executables when installing them. This helps eventual
+debugging that may be needed later, and nowadays disk space is cheap
+and dynamic loaders typically ensure debug sections are not loaded during
+normal execution. Users that need stripped binaries may invoke the
+ at code{install-strip} target to do that.
+
+If possible, write the @code{install} target rule so that it does not
+modify anything in the directory where the program was built, provided
+ at samp{make all} has just been done. This is convenient for building the
+program under one user name and installing it under another.
+
+The commands should create all the directories in which files are to be
+installed, if they don't already exist. This includes the directories
+specified as the values of the variables @code{prefix} and
+ at code{exec_prefix}, as well as all subdirectories that are needed.
+One way to do this is by means of an @code{installdirs} target
+as described below.
+
+Use @samp{-} before any command for installing a man page, so that
+ at code{make} will ignore any errors. This is in case there are systems
+that don't have the Unix man page documentation system installed.
+
+The way to install Info files is to copy them into @file{$(infodir)}
+with @code{$(INSTALL_DATA)} (@pxref{Command Variables}), and then run
+the @code{install-info} program if it is present. @code{install-info}
+is a program that edits the Info @file{dir} file to add or update the
+menu entry for the given Info file; it is part of the Texinfo package.
+
+Here is a sample rule to install an Info file that also tries to
+handle some additional situations, such as @code{install-info} not
+being present.
+
+ at comment This example has been carefully formatted for the Make manual.
+ at comment Please do not reformat it without talking to bug-make at gnu.org.
+ at smallexample
+do-install-info: foo.info installdirs
+ $(NORMAL_INSTALL)
+# Prefer an info file in . to one in srcdir.
+ if test -f foo.info; then d=.; \
+ else d="$(srcdir)"; fi; \
+ $(INSTALL_DATA) $$d/foo.info \
+ "$(DESTDIR)$(infodir)/foo.info"
+# Run install-info only if it exists.
+# Use `if' instead of just prepending `-' to the
+# line so we notice real errors from install-info.
+# Use `$(SHELL) -c' because some shells do not
+# fail gracefully when there is an unknown command.
+ $(POST_INSTALL)
+ if $(SHELL) -c 'install-info --version' \
+ >/dev/null 2>&1; then \
+ install-info --dir-file="$(DESTDIR)$(infodir)/dir" \
+ "$(DESTDIR)$(infodir)/foo.info"; \
+ else true; fi
+ at end smallexample
+
+When writing the @code{install} target, you must classify all the
+commands into three categories: normal ones, @dfn{pre-installation}
+commands and @dfn{post-installation} commands. @xref{Install Command
+Categories}.
+
+ at item install-html
+ at itemx install-dvi
+ at itemx install-pdf
+ at itemx install-ps
+These targets install documentation in formats other than Info;
+they're intended to be called explicitly by the person installing the
+package, if that format is desired. GNU prefers Info files, so these
+must be installed by the @code{install} target.
+
+When you have many documentation files to install, we recommend that
+you avoid collisions and clutter by arranging for these targets to
+install in subdirectories of the appropriate installation directory,
+such as @code{htmldir}. As one example, if your package has multiple
+manuals, and you wish to install HTML documentation with many files
+(such as the ``split'' mode output by @code{makeinfo --html}), you'll
+certainly want to use subdirectories, or two nodes with the same name
+in different manuals will overwrite each other.
+
+Please make these @code{install- at var{format}} targets invoke the
+commands for the @var{format} target, for example, by making
+ at var{format} a dependency.
+
+ at item uninstall
+Delete all the installed files---the copies that the @samp{install}
+and @samp{install-*} targets create.
+
+This rule should not modify the directories where compilation is done,
+only the directories where files are installed.
+
+The uninstallation commands are divided into three categories, just like
+the installation commands. @xref{Install Command Categories}.
+
+ at item install-strip
+Like @code{install}, but strip the executable files while installing
+them. In simple cases, this target can use the @code{install} target in
+a simple way:
+
+ at smallexample
+install-strip:
+ $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
+ install
+ at end smallexample
+
+But if the package installs scripts as well as real executables, the
+ at code{install-strip} target can't just refer to the @code{install}
+target; it has to strip the executables but not the scripts.
+
+ at code{install-strip} should not strip the executables in the build
+directory which are being copied for installation. It should only strip
+the copies that are installed.
+
+Normally we do not recommend stripping an executable unless you are sure
+the program has no bugs. However, it can be reasonable to install a
+stripped executable for actual execution while saving the unstripped
+executable elsewhere in case there is a bug.
+
+ at item clean
+Delete all files in the current directory that are normally created by
+building the program. Also delete files in other directories if they
+are created by this makefile. However, don't delete the files that
+record the configuration. Also preserve files that could be made by
+building, but normally aren't because the distribution comes with
+them. There is no need to delete parent directories that were created
+with @samp{mkdir -p}, since they could have existed anyway.
+
+Delete @file{.dvi} files here if they are not part of the distribution.
+
+ at item distclean
+Delete all files in the current directory (or created by this
+makefile) that are created by configuring or building the program. If
+you have unpacked the source and built the program without creating
+any other files, @samp{make distclean} should leave only the files
+that were in the distribution. However, there is no need to delete
+parent directories that were created with @samp{mkdir -p}, since they
+could have existed anyway.
+
+ at item mostlyclean
+Like @samp{clean}, but may refrain from deleting a few files that people
+normally don't want to recompile. For example, the @samp{mostlyclean}
+target for GCC does not delete @file{libgcc.a}, because recompiling it
+is rarely necessary and takes a lot of time.
+
+ at item maintainer-clean
+Delete almost everything that can be reconstructed with this Makefile.
+This typically includes everything deleted by @code{distclean}, plus
+more: C source files produced by Bison, tags tables, Info files, and
+so on.
+
+The reason we say ``almost everything'' is that running the command
+ at samp{make maintainer-clean} should not delete @file{configure} even
+if @file{configure} can be remade using a rule in the Makefile. More
+generally, @samp{make maintainer-clean} should not delete anything
+that needs to exist in order to run @file{configure} and then begin to
+build the program. Also, there is no need to delete parent
+directories that were created with @samp{mkdir -p}, since they could
+have existed anyway. These are the only exceptions;
+ at code{maintainer-clean} should delete everything else that can be
+rebuilt.
+
+The @samp{maintainer-clean} target is intended to be used by a maintainer of
+the package, not by ordinary users. You may need special tools to
+reconstruct some of the files that @samp{make maintainer-clean} deletes.
+Since these files are normally included in the distribution, we don't
+take care to make them easy to reconstruct. If you find you need to
+unpack the full distribution again, don't blame us.
+
+To help make users aware of this, the commands for the special
+ at code{maintainer-clean} target should start with these two:
+
+ at smallexample
+@@echo 'This command is intended for maintainers to use; it'
+@@echo 'deletes files that may need special tools to rebuild.'
+ at end smallexample
+
+ at item TAGS
+Update a tags table for this program.
+ at c ADR: how?
+
+ at item info
+Generate any Info files needed. The best way to write the rules is as
+follows:
+
+ at smallexample
+info: foo.info
+
+foo.info: foo.texi chap1.texi chap2.texi
+ $(MAKEINFO) $(srcdir)/foo.texi
+ at end smallexample
+
+ at noindent
+You must define the variable @code{MAKEINFO} in the Makefile. It should
+run the @code{makeinfo} program, which is part of the Texinfo
+distribution.
+
+Normally a GNU distribution comes with Info files, and that means the
+Info files are present in the source directory. Therefore, the Make
+rule for an info file should update it in the source directory. When
+users build the package, ordinarily Make will not update the Info files
+because they will already be up to date.
+
+ at item dvi
+ at itemx html
+ at itemx pdf
+ at itemx ps
+Generate documentation files in the given format. These targets
+should always exist, but any or all can be a no-op if the given output
+format cannot be generated. These targets should not be dependencies
+of the @code{all} target; the user must manually invoke them.
+
+Here's an example rule for generating DVI files from Texinfo:
+
+ at smallexample
+dvi: foo.dvi
+
+foo.dvi: foo.texi chap1.texi chap2.texi
+ $(TEXI2DVI) $(srcdir)/foo.texi
+ at end smallexample
+
+ at noindent
+You must define the variable @code{TEXI2DVI} in the Makefile. It
+should run the program @code{texi2dvi}, which is part of the Texinfo
+distribution. (@code{texi2dvi} uses @TeX{} to do the real work of
+formatting. @TeX{} is not distributed with Texinfo.) Alternatively,
+write only the dependencies, and allow GNU @code{make} to provide the
+command.
+
+Here's another example, this one for generating HTML from Texinfo:
+
+ at smallexample
+html: foo.html
+
+foo.html: foo.texi chap1.texi chap2.texi
+ $(TEXI2HTML) $(srcdir)/foo.texi
+ at end smallexample
+
+ at noindent
+Again, you would define the variable @code{TEXI2HTML} in the Makefile;
+for example, it might run @code{makeinfo --no-split --html}
+(@command{makeinfo} is part of the Texinfo distribution).
+
+ at item dist
+Create a distribution tar file for this program. The tar file should be
+set up so that the file names in the tar file start with a subdirectory
+name which is the name of the package it is a distribution for. This
+name can include the version number.
+
+For example, the distribution tar file of GCC version 1.40 unpacks into
+a subdirectory named @file{gcc-1.40}.
+
+The easiest way to do this is to create a subdirectory appropriately
+named, use @code{ln} or @code{cp} to install the proper files in it, and
+then @code{tar} that subdirectory.
+
+Compress the tar file with @code{gzip}. For example, the actual
+distribution file for GCC version 1.40 is called @file{gcc-1.40.tar.gz}.
+It is ok to support other free compression formats as well.
+
+The @code{dist} target should explicitly depend on all non-source files
+that are in the distribution, to make sure they are up to date in the
+distribution.
+ at ifset CODESTD
+ at xref{Releases, , Making Releases}.
+ at end ifset
+ at ifclear CODESTD
+ at xref{Releases, , Making Releases, standards, GNU Coding Standards}.
+ at end ifclear
+
+ at item check
+Perform self-tests (if any). The user must build the program before
+running the tests, but need not install the program; you should write
+the self-tests so that they work when the program is built but not
+installed.
+ at end table
+
+The following targets are suggested as conventional names, for programs
+in which they are useful.
+
+ at table @code
+ at item installcheck
+Perform installation tests (if any). The user must build and install
+the program before running the tests. You should not assume that
+ at file{$(bindir)} is in the search path.
+
+ at item installdirs
+It's useful to add a target named @samp{installdirs} to create the
+directories where files are installed, and their parent directories.
+There is a script called @file{mkinstalldirs} which is convenient for
+this; you can find it in the Gnulib package.
+You can use a rule like this:
+
+ at comment This has been carefully formatted to look decent in the Make manual.
+ at comment Please be sure not to make it extend any further to the right.--roland
+ at smallexample
+# Make sure all installation directories (e.g. $(bindir))
+# actually exist by making them if necessary.
+installdirs: mkinstalldirs
+ $(srcdir)/mkinstalldirs $(bindir) $(datadir) \
+ $(libdir) $(infodir) \
+ $(mandir)
+ at end smallexample
+
+ at noindent
+or, if you wish to support @env{DESTDIR} (strongly encouraged),
+
+ at smallexample
+# Make sure all installation directories (e.g. $(bindir))
+# actually exist by making them if necessary.
+installdirs: mkinstalldirs
+ $(srcdir)/mkinstalldirs \
+ $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \
+ $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \
+ $(DESTDIR)$(mandir)
+ at end smallexample
+
+This rule should not modify the directories where compilation is done.
+It should do nothing but create installation directories.
+ at end table
+
+ at node Install Command Categories
+ at section Install Command Categories
+
+ at cindex pre-installation commands
+ at cindex post-installation commands
+When writing the @code{install} target, you must classify all the
+commands into three categories: normal ones, @dfn{pre-installation}
+commands and @dfn{post-installation} commands.
+
+Normal commands move files into their proper places, and set their
+modes. They may not alter any files except the ones that come entirely
+from the package they belong to.
+
+Pre-installation and post-installation commands may alter other files;
+in particular, they can edit global configuration files or data bases.
+
+Pre-installation commands are typically executed before the normal
+commands, and post-installation commands are typically run after the
+normal commands.
+
+The most common use for a post-installation command is to run
+ at code{install-info}. This cannot be done with a normal command, since
+it alters a file (the Info directory) which does not come entirely and
+solely from the package being installed. It is a post-installation
+command because it needs to be done after the normal command which
+installs the package's Info files.
+
+Most programs don't need any pre-installation commands, but we have the
+feature just in case it is needed.
+
+To classify the commands in the @code{install} rule into these three
+categories, insert @dfn{category lines} among them. A category line
+specifies the category for the commands that follow.
+
+A category line consists of a tab and a reference to a special Make
+variable, plus an optional comment at the end. There are three
+variables you can use, one for each category; the variable name
+specifies the category. Category lines are no-ops in ordinary execution
+because these three Make variables are normally undefined (and you
+ at emph{should not} define them in the makefile).
+
+Here are the three possible category lines, each with a comment that
+explains what it means:
+
+ at smallexample
+ $(PRE_INSTALL) # @r{Pre-install commands follow.}
+ $(POST_INSTALL) # @r{Post-install commands follow.}
+ $(NORMAL_INSTALL) # @r{Normal commands follow.}
+ at end smallexample
+
+If you don't use a category line at the beginning of the @code{install}
+rule, all the commands are classified as normal until the first category
+line. If you don't use any category lines, all the commands are
+classified as normal.
+
+These are the category lines for @code{uninstall}:
+
+ at smallexample
+ $(PRE_UNINSTALL) # @r{Pre-uninstall commands follow.}
+ $(POST_UNINSTALL) # @r{Post-uninstall commands follow.}
+ $(NORMAL_UNINSTALL) # @r{Normal commands follow.}
+ at end smallexample
+
+Typically, a pre-uninstall command would be used for deleting entries
+from the Info directory.
+
+If the @code{install} or @code{uninstall} target has any dependencies
+which act as subroutines of installation, then you should start
+ at emph{each} dependency's commands with a category line, and start the
+main target's commands with a category line also. This way, you can
+ensure that each command is placed in the right category regardless of
+which of the dependencies actually run.
+
+Pre-installation and post-installation commands should not run any
+programs except for these:
+
+ at example
+[ basename bash cat chgrp chmod chown cmp cp dd diff echo
+egrep expand expr false fgrep find getopt grep gunzip gzip
+hostname install install-info kill ldconfig ln ls md5sum
+mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
+test touch true uname xargs yes
+ at end example
+
+ at cindex binary packages
+The reason for distinguishing the commands in this way is for the sake
+of making binary packages. Typically a binary package contains all the
+executables and other files that need to be installed, and has its own
+method of installing them---so it does not need to run the normal
+installation commands. But installing the binary package does need to
+execute the pre-installation and post-installation commands.
+
+Programs to build binary packages work by extracting the
+pre-installation and post-installation commands. Here is one way of
+extracting the pre-installation commands (the @option{-s} option to
+ at command{make} is needed to silence messages about entering
+subdirectories):
+
+ at smallexample
+make -s -n install -o all \
+ PRE_INSTALL=pre-install \
+ POST_INSTALL=post-install \
+ NORMAL_INSTALL=normal-install \
+ | gawk -f pre-install.awk
+ at end smallexample
+
+ at noindent
+where the file @file{pre-install.awk} could contain this:
+
+ at smallexample
+$0 ~ /^(normal-install|post-install)[ \t]*$/ @{on = 0@}
+on @{print $0@}
+$0 ~ /^pre-install[ \t]*$/ @{on = 1@}
+ at end smallexample
diff --git a/debian/docs/src/autoconf/2.69/standards.texi b/debian/docs/src/autoconf/2.69/standards.texi
new file mode 100644
index 0000000..69a400e
--- /dev/null
+++ b/debian/docs/src/autoconf/2.69/standards.texi
@@ -0,0 +1,4256 @@
+\input texinfo @c -*-texinfo-*-
+ at c %**start of header
+ at setfilename standards.info
+ at settitle GNU Coding Standards
+ at c This date is automagically updated when you save this file:
+ at set lastupdate April 7, 2012
+ at c %**end of header
+
+ at dircategory GNU organization
+ at direntry
+* Standards: (standards). GNU coding standards.
+ at end direntry
+
+ at c @setchapternewpage odd
+ at setchapternewpage off
+
+ at c Put everything in one index (arbitrarily chosen to be the concept index).
+ at syncodeindex fn cp
+ at syncodeindex ky cp
+ at syncodeindex pg cp
+ at syncodeindex vr cp
+
+ at c This is used by a cross ref in make-stds.texi
+ at set CODESTD 1
+
+ at copying
+The GNU coding standards, last updated @value{lastupdate}.
+
+Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
+2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010,
+2011, 2012 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 no Front-Cover Texts, and with no Back-Cover
+Texts. A copy of the license is included in the section entitled
+``GNU Free Documentation License''.
+ at end copying
+
+ at titlepage
+ at title GNU Coding Standards
+ at author Richard Stallman, et al.
+ at author last updated @value{lastupdate}
+ at page
+ at vskip 0pt plus 1filll
+ at insertcopying
+ at end titlepage
+
+ at contents
+
+ at ifnottex
+ at node Top
+ at top GNU Coding Standards
+
+ at insertcopying
+ at end ifnottex
+
+ at menu
+* Preface:: About the GNU Coding Standards.
+* Legal Issues:: Keeping free software free.
+* Design Advice:: General program design.
+* Program Behavior:: Program behavior for all programs
+* Writing C:: Making the best use of C.
+* Documentation:: Documenting programs.
+* Managing Releases:: The release process.
+* References:: Mentioning non-free software or documentation.
+* GNU Free Documentation License:: Copying and sharing this manual.
+* Index::
+
+ at end menu
+
+ at node Preface
+ at chapter About the GNU Coding Standards
+
+The GNU Coding Standards were written by Richard Stallman and other GNU
+Project volunteers. Their purpose is to make the GNU system clean,
+consistent, and easy to install. This document can also be read as a
+guide to writing portable, robust and reliable programs. It focuses on
+programs written in C, but many of the rules and principles are useful
+even if you write in another programming language. The rules often
+state reasons for writing in a certain way.
+
+ at cindex where to obtain @code{standards.texi}
+ at cindex downloading this manual
+If you did not obtain this file directly from the GNU project and
+recently, please check for a newer version. You can get the GNU
+Coding Standards from the GNU web server in many
+different formats, including the Texinfo source, PDF, HTML, DVI, plain
+text, and more, at: @uref{http://www.gnu.org/prep/standards/}.
+
+If you are maintaining an official GNU package, in addition to this
+document, please read and follow the GNU maintainer information
+(@pxref{Top, , Contents, maintain, Information for Maintainers of GNU
+Software}).
+
+ at cindex @code{gnustandards-commit@@gnu.org} mailing list
+If you want to receive diffs for every change to these GNU documents,
+join the mailing list @code{gnustandards-commit@@gnu.org}, via the web
+interface at
+ at url{http://lists.gnu.org/mailman/listinfo/gnustandards-commit}.
+Archives are also available there.
+
+ at cindex @code{bug-standards@@gnu.org} email address
+ at cindex Savannah repository for gnustandards
+ at cindex gnustandards project repository
+Please send corrections or suggestions for this document to
+ at email{bug-standards@@gnu.org}. If you make a suggestion, please
+include a suggested new wording for it, to help us consider the
+suggestion efficiently. We prefer a context diff to the Texinfo
+source, but if that's difficult for you, you can make a context diff
+for some other version of this document, or propose it in any way that
+makes it clear. The source repository for this document can be found
+at @url{http://savannah.gnu.org/projects/gnustandards}.
+
+These standards cover the minimum of what is important when writing a
+GNU package. Likely, the need for additional standards will come up.
+Sometimes, you might suggest that such standards be added to this
+document. If you think your standards would be generally useful, please
+do suggest them.
+
+You should also set standards for your package on many questions not
+addressed or not firmly specified here. The most important point is to
+be self-consistent---try to stick to the conventions you pick, and try
+to document them as much as possible. That way, your program will be
+more maintainable by others.
+
+The GNU Hello program serves as an example of how to follow the GNU
+coding standards for a trivial program.
+ at uref{http://www.gnu.org/software/hello/hello.html}.
+
+This release of the GNU Coding Standards was last updated
+ at value{lastupdate}.
+
+
+ at node Legal Issues
+ at chapter Keeping Free Software Free
+ at cindex legal aspects
+
+This chapter discusses how you can make sure that GNU software
+avoids legal difficulties, and other related issues.
+
+ at menu
+* Reading Non-Free Code:: Referring to proprietary programs.
+* Contributions:: Accepting contributions.
+* Trademarks:: How we deal with trademark issues.
+ at end menu
+
+ at node Reading Non-Free Code
+ at section Referring to Proprietary Programs
+ at cindex proprietary programs
+ at cindex avoiding proprietary code
+
+Don't in any circumstances refer to Unix source code for or during
+your work on GNU! (Or to any other proprietary programs.)
+
+If you have a vague recollection of the internals of a Unix program,
+this does not absolutely mean you can't write an imitation of it, but
+do try to organize the imitation internally along different lines,
+because this is likely to make the details of the Unix version
+irrelevant and dissimilar to your results.
+
+For example, Unix utilities were generally optimized to minimize
+memory use; if you go for speed instead, your program will be very
+different. You could keep the entire input file in memory and scan it
+there instead of using stdio. Use a smarter algorithm discovered more
+recently than the Unix program. Eliminate use of temporary files. Do
+it in one pass instead of two (we did this in the assembler).
+
+Or, on the contrary, emphasize simplicity instead of speed. For some
+applications, the speed of today's computers makes simpler algorithms
+adequate.
+
+Or go for generality. For example, Unix programs often have static
+tables or fixed-size strings, which make for arbitrary limits; use
+dynamic allocation instead. Make sure your program handles NULs and
+other funny characters in the input files. Add a programming language
+for extensibility and write part of the program in that language.
+
+Or turn some parts of the program into independently usable libraries.
+Or use a simple garbage collector instead of tracking precisely when
+to free memory, or use a new GNU facility such as obstacks.
+
+
+ at node Contributions
+ at section Accepting Contributions
+ at cindex legal papers
+ at cindex accepting contributions
+
+If the program you are working on is copyrighted by the Free Software
+Foundation, then when someone else sends you a piece of code to add to
+the program, we need legal papers to use it---just as we asked you to
+sign papers initially. @emph{Each} person who makes a nontrivial
+contribution to a program must sign some sort of legal papers in order
+for us to have clear title to the program; the main author alone is not
+enough.
+
+So, before adding in any contributions from other people, please tell
+us, so we can arrange to get the papers. Then wait until we tell you
+that we have received the signed papers, before you actually use the
+contribution.
+
+This applies both before you release the program and afterward. If
+you receive diffs to fix a bug, and they make significant changes, we
+need legal papers for that change.
+
+This also applies to comments and documentation files. For copyright
+law, comments and code are just text. Copyright applies to all kinds of
+text, so we need legal papers for all kinds.
+
+We know it is frustrating to ask for legal papers; it's frustrating for
+us as well. But if you don't wait, you are going out on a limb---for
+example, what if the contributor's employer won't sign a disclaimer?
+You might have to take that code out again!
+
+You don't need papers for changes of a few lines here or there, since
+they are not significant for copyright purposes. Also, you don't need
+papers if all you get from the suggestion is some ideas, not actual code
+which you use. For example, if someone sent you one implementation, but
+you write a different implementation of the same idea, you don't need to
+get papers.
+
+The very worst thing is if you forget to tell us about the other
+contributor. We could be very embarrassed in court some day as a
+result.
+
+We have more detailed advice for maintainers of GNU packages. If you
+have reached the stage of maintaining a GNU program (whether released
+or not), please take a look: @pxref{Legal Matters,,, maintain,
+Information for GNU Maintainers}.
+
+
+ at node Trademarks
+ at section Trademarks
+ at cindex trademarks
+
+Please do not include any trademark acknowledgements in GNU software
+packages or documentation.
+
+Trademark acknowledgements are the statements that such-and-such is a
+trademark of so-and-so. The GNU Project has no objection to the basic
+idea of trademarks, but these acknowledgements feel like kowtowing,
+and there is no legal requirement for them, so we don't use them.
+
+What is legally required, as regards other people's trademarks, is to
+avoid using them in ways which a reader might reasonably understand as
+naming or labeling our own programs or activities. For example, since
+``Objective C'' is (or at least was) a trademark, we made sure to say
+that we provide a ``compiler for the Objective C language'' rather
+than an ``Objective C compiler''. The latter would have been meant as
+a shorter way of saying the former, but it does not explicitly state
+the relationship, so it could be misinterpreted as using ``Objective
+C'' as a label for the compiler rather than for the language.
+
+Please don't use ``win'' as an abbreviation for Microsoft Windows in
+GNU software or documentation. In hacker terminology, calling
+something a ``win'' is a form of praise. If you wish to praise
+Microsoft Windows when speaking on your own, by all means do so, but
+not in GNU software. Usually we write the name ``Windows'' in full,
+but when brevity is very important (as in file names and sometimes
+symbol names), we abbreviate it to ``w''. For instance, the files and
+functions in Emacs that deal with Windows start with @samp{w32}.
+
+ at node Design Advice
+ at chapter General Program Design
+ at cindex program design
+
+This chapter discusses some of the issues you should take into
+account when designing your program.
+
+ at c Standard or ANSI C
+ at c
+ at c In 1989 the American National Standards Institute (ANSI) standardized
+ at c C as standard X3.159-1989. In December of that year the
+ at c International Standards Organization ISO adopted the ANSI C standard
+ at c making minor changes. In 1990 ANSI then re-adopted ISO standard
+ at c C. This version of C is known as either ANSI C or Standard C.
+
+ at c A major revision of the C Standard appeared in 1999.
+
+ at menu
+* Source Language:: Which languages to use.
+* Compatibility:: Compatibility with other implementations.
+* Using Extensions:: Using non-standard features.
+* Standard C:: Using standard C features.
+* Conditional Compilation:: Compiling code only if a conditional is true.
+ at end menu
+
+ at node Source Language
+ at section Which Languages to Use
+ at cindex programming languages
+
+When you want to use a language that gets compiled and runs at high
+speed, the best language to use is C. Using another language is like
+using a non-standard feature: it will cause trouble for users. Even if
+GCC supports the other language, users may find it inconvenient to have
+to install the compiler for that other language in order to build your
+program. For example, if you write your program in C++, people will
+have to install the GNU C++ compiler in order to compile your program.
+
+C has one other advantage over C++ and other compiled languages: more
+people know C, so more people will find it easy to read and modify the
+program if it is written in C.
+
+So in general it is much better to use C, rather than the
+comparable alternatives.
+
+But there are two exceptions to that conclusion:
+
+ at itemize @bullet
+ at item
+It is no problem to use another language to write a tool specifically
+intended for use with that language. That is because the only people
+who want to build the tool will be those who have installed the other
+language anyway.
+
+ at item
+If an application is of interest only to a narrow part of the community,
+then the question of which language it is written in has less effect on
+other people, so you may as well please yourself.
+ at end itemize
+
+Many programs are designed to be extensible: they include an interpreter
+for a language that is higher level than C. Often much of the program
+is written in that language, too. The Emacs editor pioneered this
+technique.
+
+ at cindex Guile
+ at cindex GNOME and Guile
+The standard extensibility interpreter for GNU software is Guile
+(@uref{http://www.gnu.org/@/software/@/guile/}), which implements the
+language Scheme (an especially clean and simple dialect of Lisp).
+Guile also includes bindings for GTK+/GNOME, making it practical to
+write modern GUI functionality within Guile. We don't reject programs
+written in other ``scripting languages'' such as Perl and Python, but
+using Guile is very important for the overall consistency of the GNU
+system.
+
+
+ at node Compatibility
+ at section Compatibility with Other Implementations
+ at cindex compatibility with C and @sc{posix} standards
+ at cindex @sc{posix} compatibility
+
+With occasional exceptions, utility programs and libraries for GNU
+should be upward compatible with those in Berkeley Unix, and upward
+compatible with Standard C if Standard C specifies their
+behavior, and upward compatible with @sc{posix} if @sc{posix} specifies
+their behavior.
+
+When these standards conflict, it is useful to offer compatibility
+modes for each of them.
+
+ at cindex options for compatibility
+Standard C and @sc{posix} prohibit many kinds of extensions. Feel
+free to make the extensions anyway, and include a @samp{--ansi},
+ at samp{--posix}, or @samp{--compatible} option to turn them off.
+However, if the extension has a significant chance of breaking any real
+programs or scripts, then it is not really upward compatible. So you
+should try to redesign its interface to make it upward compatible.
+
+ at cindex @code{POSIXLY_CORRECT}, environment variable
+Many GNU programs suppress extensions that conflict with @sc{posix} if the
+environment variable @code{POSIXLY_CORRECT} is defined (even if it is
+defined with a null value). Please make your program recognize this
+variable if appropriate.
+
+When a feature is used only by users (not by programs or command
+files), and it is done poorly in Unix, feel free to replace it
+completely with something totally different and better. (For example,
+ at code{vi} is replaced with Emacs.) But it is nice to offer a compatible
+feature as well. (There is a free @code{vi} clone, so we offer it.)
+
+Additional useful features are welcome regardless of whether
+there is any precedent for them.
+
+ at node Using Extensions
+ at section Using Non-standard Features
+ at cindex non-standard extensions
+
+Many GNU facilities that already exist support a number of convenient
+extensions over the comparable Unix facilities. Whether to use these
+extensions in implementing your program is a difficult question.
+
+On the one hand, using the extensions can make a cleaner program.
+On the other hand, people will not be able to build the program
+unless the other GNU tools are available. This might cause the
+program to work on fewer kinds of machines.
+
+With some extensions, it might be easy to provide both alternatives.
+For example, you can define functions with a ``keyword'' @code{INLINE}
+and define that as a macro to expand into either @code{inline} or
+nothing, depending on the compiler.
+
+In general, perhaps it is best not to use the extensions if you can
+straightforwardly do without them, but to use the extensions if they
+are a big improvement.
+
+An exception to this rule are the large, established programs (such as
+Emacs) which run on a great variety of systems. Using GNU extensions in
+such programs would make many users unhappy, so we don't do that.
+
+Another exception is for programs that are used as part of compilation:
+anything that must be compiled with other compilers in order to
+bootstrap the GNU compilation facilities. If these require the GNU
+compiler, then no one can compile them without having them installed
+already. That would be extremely troublesome in certain cases.
+
+ at node Standard C
+ at section Standard C and Pre-Standard C
+ at cindex @sc{ansi} C standard
+
+1989 Standard C is widespread enough now that it is ok to use its
+features in new programs. There is one exception: do not ever use the
+``trigraph'' feature of Standard C.
+
+1999 Standard C is not widespread yet, so please do not require its
+features in programs. It is ok to use its features if they are present.
+
+However, it is easy to support pre-standard compilers in most programs,
+so if you know how to do that, feel free. If a program you are
+maintaining has such support, you should try to keep it working.
+
+ at cindex function prototypes
+To support pre-standard C, instead of writing function definitions in
+standard prototype form,
+
+ at example
+int
+foo (int x, int y)
+ at dots{}
+ at end example
+
+ at noindent
+write the definition in pre-standard style like this,
+
+ at example
+int
+foo (x, y)
+ int x, y;
+ at dots{}
+ at end example
+
+ at noindent
+and use a separate declaration to specify the argument prototype:
+
+ at example
+int foo (int, int);
+ at end example
+
+You need such a declaration anyway, in a header file, to get the benefit
+of prototypes in all the files where the function is called. And once
+you have the declaration, you normally lose nothing by writing the
+function definition in the pre-standard style.
+
+This technique does not work for integer types narrower than @code{int}.
+If you think of an argument as being of a type narrower than @code{int},
+declare it as @code{int} instead.
+
+There are a few special cases where this technique is hard to use. For
+example, if a function argument needs to hold the system type
+ at code{dev_t}, you run into trouble, because @code{dev_t} is shorter than
+ at code{int} on some machines; but you cannot use @code{int} instead,
+because @code{dev_t} is wider than @code{int} on some machines. There
+is no type you can safely use on all machines in a non-standard
+definition. The only way to support non-standard C and pass such an
+argument is to check the width of @code{dev_t} using Autoconf and choose
+the argument type accordingly. This may not be worth the trouble.
+
+In order to support pre-standard compilers that do not recognize
+prototypes, you may want to use a preprocessor macro like this:
+
+ at example
+/* Declare the prototype for a general external function. */
+#if defined (__STDC__) || defined (WINDOWSNT)
+#define P_(proto) proto
+#else
+#define P_(proto) ()
+#endif
+ at end example
+
+ at node Conditional Compilation
+ at section Conditional Compilation
+
+When supporting configuration options already known when building your
+program we prefer using @code{if (... )} over conditional compilation,
+as in the former case the compiler is able to perform more extensive
+checking of all possible code paths.
+
+For example, please write
+
+ at smallexample
+ if (HAS_FOO)
+ ...
+ else
+ ...
+ at end smallexample
+
+ at noindent
+instead of:
+
+ at smallexample
+ #ifdef HAS_FOO
+ ...
+ #else
+ ...
+ #endif
+ at end smallexample
+
+A modern compiler such as GCC will generate exactly the same code in
+both cases, and we have been using similar techniques with good success
+in several projects. Of course, the former method assumes that
+ at code{HAS_FOO} is defined as either 0 or 1.
+
+While this is not a silver bullet solving all portability problems,
+and is not always appropriate, following this policy would have saved
+GCC developers many hours, or even days, per year.
+
+In the case of function-like macros like @code{REVERSIBLE_CC_MODE} in
+GCC which cannot be simply used in @code{if (...)} statements, there is
+an easy workaround. Simply introduce another macro
+ at code{HAS_REVERSIBLE_CC_MODE} as in the following example:
+
+ at smallexample
+ #ifdef REVERSIBLE_CC_MODE
+ #define HAS_REVERSIBLE_CC_MODE 1
+ #else
+ #define HAS_REVERSIBLE_CC_MODE 0
+ #endif
+ at end smallexample
+
+ at node Program Behavior
+ at chapter Program Behavior for All Programs
+
+This chapter describes conventions for writing robust
+software. It also describes general standards for error messages, the
+command line interface, and how libraries should behave.
+
+ at menu
+* Non-GNU Standards:: We consider standards such as POSIX;
+ we don't "obey" them.
+* Semantics:: Writing robust programs.
+* Libraries:: Library behavior.
+* Errors:: Formatting error messages.
+* User Interfaces:: Standards about interfaces generally.
+* Graphical Interfaces:: Standards for graphical interfaces.
+* Command-Line Interfaces:: Standards for command line interfaces.
+* Dynamic Plug-In Interfaces:: Standards for dynamic plug-in interfaces.
+* Option Table:: Table of long options.
+* OID Allocations:: Table of OID slots for GNU.
+* Memory Usage:: When and how to care about memory needs.
+* File Usage:: Which files to use, and where.
+ at end menu
+
+ at node Non-GNU Standards
+ at section Non-GNU Standards
+
+The GNU Project regards standards published by other organizations as
+suggestions, not orders. We consider those standards, but we do not
+``obey'' them. In developing a GNU program, you should implement
+an outside standard's specifications when that makes the GNU system
+better overall in an objective sense. When it doesn't, you shouldn't.
+
+In most cases, following published standards is convenient for
+users---it means that their programs or scripts will work more
+portably. For instance, GCC implements nearly all the features of
+Standard C as specified by that standard. C program developers would
+be unhappy if it did not. And GNU utilities mostly follow
+specifications of POSIX.2; shell script writers and users would be
+unhappy if our programs were incompatible.
+
+But we do not follow either of these specifications rigidly, and there
+are specific points on which we decided not to follow them, so as to
+make the GNU system better for users.
+
+For instance, Standard C says that nearly all extensions to C are
+prohibited. How silly! GCC implements many extensions, some of which
+were later adopted as part of the standard. If you want these
+constructs to give an error message as ``required'' by the standard,
+you must specify @samp{--pedantic}, which was implemented only so that
+we can say ``GCC is a 100% implementation of the standard'', not
+because there is any reason to actually use it.
+
+POSIX.2 specifies that @samp{df} and @samp{du} must output sizes by
+default in units of 512 bytes. What users want is units of 1k, so
+that is what we do by default. If you want the ridiculous behavior
+``required'' by POSIX, you must set the environment variable
+ at samp{POSIXLY_CORRECT} (which was originally going to be named
+ at samp{POSIX_ME_HARDER}).
+
+GNU utilities also depart from the letter of the POSIX.2 specification
+when they support long-named command-line options, and intermixing
+options with ordinary arguments. This minor incompatibility with
+POSIX is never a problem in practice, and it is very useful.
+
+In particular, don't reject a new feature, or remove an old one,
+merely because a standard says it is ``forbidden'' or ``deprecated''.
+
+
+ at node Semantics
+ at section Writing Robust Programs
+
+ at cindex arbitrary limits on data
+Avoid arbitrary limits on the length or number of @emph{any} data
+structure, including file names, lines, files, and symbols, by allocating
+all data structures dynamically. In most Unix utilities, ``long lines
+are silently truncated''. This is not acceptable in a GNU utility.
+
+ at cindex @code{NUL} characters
+ at findex libiconv
+Utilities reading files should not drop NUL characters, or any other
+nonprinting characters @emph{including those with codes above 0177}.
+The only sensible exceptions would be utilities specifically intended
+for interface to certain types of terminals or printers that can't
+handle those characters. Whenever possible, try to make programs work
+properly with sequences of bytes that represent multibyte characters;
+UTF-8 is the most important.
+
+ at cindex error messages
+Check every system call for an error return, unless you know you wish
+to ignore errors. Include the system error text (from @code{perror},
+ at code{strerror}, or equivalent) in @emph{every} error message
+resulting from a failing system call, as well as the name of the file
+if any and the name of the utility. Just ``cannot open foo.c'' or
+``stat failed'' is not sufficient.
+
+ at cindex @code{malloc} return value
+ at cindex memory allocation failure
+Check every call to @code{malloc} or @code{realloc} to see if it
+returned zero. Check @code{realloc} even if you are making the block
+smaller; in a system that rounds block sizes to a power of 2,
+ at code{realloc} may get a different block if you ask for less space.
+
+In Unix, @code{realloc} can destroy the storage block if it returns
+zero. GNU @code{realloc} does not have this bug: if it fails, the
+original block is unchanged. Feel free to assume the bug is fixed. If
+you wish to run your program on Unix, and wish to avoid lossage in this
+case, you can use the GNU @code{malloc}.
+
+You must expect @code{free} to alter the contents of the block that was
+freed. Anything you want to fetch from the block, you must fetch before
+calling @code{free}.
+
+If @code{malloc} fails in a noninteractive program, make that a fatal
+error. In an interactive program (one that reads commands from the
+user), it is better to abort the command and return to the command
+reader loop. This allows the user to kill other processes to free up
+virtual memory, and then try the command again.
+
+ at cindex command-line arguments, decoding
+Use @code{getopt_long} to decode arguments, unless the argument syntax
+makes this unreasonable.
+
+When static storage is to be written in during program execution, use
+explicit C code to initialize it. Reserve C initialized declarations
+for data that will not be changed.
+ at c ADR: why?
+
+Try to avoid low-level interfaces to obscure Unix data structures (such
+as file directories, utmp, or the layout of kernel memory), since these
+are less likely to work compatibly. If you need to find all the files
+in a directory, use @code{readdir} or some other high-level interface.
+These are supported compatibly by GNU.
+
+ at cindex signal handling
+The preferred signal handling facilities are the BSD variant of
+ at code{signal}, and the @sc{posix} @code{sigaction} function; the
+alternative USG @code{signal} interface is an inferior design.
+
+Nowadays, using the @sc{posix} signal functions may be the easiest way
+to make a program portable. If you use @code{signal}, then on GNU/Linux
+systems running GNU libc version 1, you should include
+ at file{bsd/signal.h} instead of @file{signal.h}, so as to get BSD
+behavior. It is up to you whether to support systems where
+ at code{signal} has only the USG behavior, or give up on them.
+
+ at cindex impossible conditions
+In error checks that detect ``impossible'' conditions, just abort.
+There is usually no point in printing any message. These checks
+indicate the existence of bugs. Whoever wants to fix the bugs will have
+to read the source code and run a debugger. So explain the problem with
+comments in the source. The relevant data will be in variables, which
+are easy to examine with the debugger, so there is no point moving them
+elsewhere.
+
+Do not use a count of errors as the exit status for a program.
+ at emph{That does not work}, because exit status values are limited to 8
+bits (0 through 255). A single run of the program might have 256
+errors; if you try to return 256 as the exit status, the parent process
+will see 0 as the status, and it will appear that the program succeeded.
+
+ at cindex temporary files
+ at cindex @code{TMPDIR} environment variable
+If you make temporary files, check the @code{TMPDIR} environment
+variable; if that variable is defined, use the specified directory
+instead of @file{/tmp}.
+
+In addition, be aware that there is a possible security problem when
+creating temporary files in world-writable directories. In C, you can
+avoid this problem by creating temporary files in this manner:
+
+ at example
+fd = open (filename, O_WRONLY | O_CREAT | O_EXCL, 0600);
+ at end example
+
+ at noindent
+or by using the @code{mkstemps} function from Gnulib
+(@pxref{mkstemps,,, gnulib, Gnulib}).
+
+In bash, use @code{set -C} (long name @code{noclobber}) to avoid this
+problem. In addition, the @code{mktemp} utility is a more general
+solution for creating temporary files from shell scripts
+(@pxref{mktemp invocation,,, coreutils, GNU Coreutils}).
+
+
+ at node Libraries
+ at section Library Behavior
+ at cindex libraries
+
+Try to make library functions reentrant. If they need to do dynamic
+storage allocation, at least try to avoid any nonreentrancy aside from
+that of @code{malloc} itself.
+
+Here are certain name conventions for libraries, to avoid name
+conflicts.
+
+Choose a name prefix for the library, more than two characters long.
+All external function and variable names should start with this
+prefix. In addition, there should only be one of these in any given
+library member. This usually means putting each one in a separate
+source file.
+
+An exception can be made when two external symbols are always used
+together, so that no reasonable program could use one without the
+other; then they can both go in the same file.
+
+External symbols that are not documented entry points for the user
+should have names beginning with @samp{_}. The @samp{_} should be
+followed by the chosen name prefix for the library, to prevent
+collisions with other libraries. These can go in the same files with
+user entry points if you like.
+
+Static functions and variables can be used as you like and need not
+fit any naming convention.
+
+ at node Errors
+ at section Formatting Error Messages
+ at cindex formatting error messages
+ at cindex error messages, formatting
+
+Error messages from compilers should look like this:
+
+ at example
+ at var{sourcefile}:@var{lineno}: @var{message}
+ at end example
+
+ at noindent
+If you want to mention the column number, use one of these formats:
+
+ at example
+ at var{sourcefile}:@var{lineno}:@var{column}: @var{message}
+ at var{sourcefile}:@var{lineno}. at var{column}: @var{message}
+
+ at end example
+
+ at noindent
+Line numbers should start from 1 at the beginning of the file, and
+column numbers should start from 1 at the beginning of the line.
+(Both of these conventions are chosen for compatibility.) Calculate
+column numbers assuming that space and all ASCII printing characters
+have equal width, and assuming tab stops every 8 columns. For
+non-ASCII characters, Unicode character widths should be used when in
+a UTF-8 locale; GNU libc and GNU gnulib provide suitable
+ at code{wcwidth} functions.
+
+The error message can also give both the starting and ending positions
+of the erroneous text. There are several formats so that you can
+avoid redundant information such as a duplicate line number.
+Here are the possible formats:
+
+ at example
+ at var{sourcefile}:@var{line1}. at var{column1}- at var{line2}. at var{column2}: @var{message}
+ at var{sourcefile}:@var{line1}. at var{column1}- at var{column2}: @var{message}
+ at var{sourcefile}:@var{line1}- at var{line2}: @var{message}
+ at end example
+
+ at noindent
+When an error is spread over several files, you can use this format:
+
+ at example
+ at var{file1}:@var{line1}. at var{column1}- at var{file2}:@var{line2}. at var{column2}: @var{message}
+ at end example
+
+Error messages from other noninteractive programs should look like this:
+
+ at example
+ at var{program}:@var{sourcefile}:@var{lineno}: @var{message}
+ at end example
+
+ at noindent
+when there is an appropriate source file, or like this:
+
+ at example
+ at var{program}: @var{message}
+ at end example
+
+ at noindent
+when there is no relevant source file.
+
+If you want to mention the column number, use this format:
+
+ at example
+ at var{program}:@var{sourcefile}:@var{lineno}:@var{column}: @var{message}
+ at end example
+
+In an interactive program (one that is reading commands from a
+terminal), it is better not to include the program name in an error
+message. The place to indicate which program is running is in the
+prompt or with the screen layout. (When the same program runs with
+input from a source other than a terminal, it is not interactive and
+would do best to print error messages using the noninteractive style.)
+
+The string @var{message} should not begin with a capital letter when
+it follows a program name and/or file name, because that isn't the
+beginning of a sentence. (The sentence conceptually starts at the
+beginning of the line.) Also, it should not end with a period.
+
+Error messages from interactive programs, and other messages such as
+usage messages, should start with a capital letter. But they should not
+end with a period.
+
+ at node User Interfaces
+ at section Standards for Interfaces Generally
+
+ at cindex program name and its behavior
+ at cindex behavior, dependent on program's name
+Please don't make the behavior of a utility depend on the name used
+to invoke it. It is useful sometimes to make a link to a utility
+with a different name, and that should not change what it does.
+
+Instead, use a run time option or a compilation switch or both
+to select among the alternate behaviors.
+
+ at cindex output device and program's behavior
+Likewise, please don't make the behavior of the program depend on the
+type of output device it is used with. Device independence is an
+important principle of the system's design; do not compromise it merely
+to save someone from typing an option now and then. (Variation in error
+message syntax when using a terminal is ok, because that is a side issue
+that people do not depend on.)
+
+If you think one behavior is most useful when the output is to a
+terminal, and another is most useful when the output is a file or a
+pipe, then it is usually best to make the default behavior the one that
+is useful with output to a terminal, and have an option for the other
+behavior.
+
+Compatibility requires certain programs to depend on the type of output
+device. It would be disastrous if @code{ls} or @code{sh} did not do so
+in the way all users expect. In some of these cases, we supplement the
+program with a preferred alternate version that does not depend on the
+output device type. For example, we provide a @code{dir} program much
+like @code{ls} except that its default output format is always
+multi-column format.
+
+
+ at node Graphical Interfaces
+ at section Standards for Graphical Interfaces
+ at cindex graphical user interface
+ at cindex interface styles
+ at cindex user interface styles
+
+ at cindex GTK+
+When you write a program that provides a graphical user interface,
+please make it work with the X Window System and the GTK+ toolkit
+unless the functionality specifically requires some alternative (for
+example, ``displaying jpeg images while in console mode'').
+
+In addition, please provide a command-line interface to control the
+functionality. (In many cases, the graphical user interface can be a
+separate program which invokes the command-line program.) This is
+so that the same jobs can be done from scripts.
+
+ at cindex CORBA
+ at cindex GNOME
+ at cindex D-bus
+ at cindex keyboard interface
+ at cindex library interface
+Please also consider providing a D-bus interface for use from other
+running programs, such as within GNOME. (GNOME used to use CORBA
+for this, but that is being phased out.) In addition, consider
+providing a library interface (for use from C), and perhaps a
+keyboard-driven console interface (for use by users from console
+mode). Once you are doing the work to provide the functionality and
+the graphical interface, these won't be much extra work.
+
+
+ at node Command-Line Interfaces
+ at section Standards for Command Line Interfaces
+ at cindex command-line interface
+
+ at findex getopt
+It is a good idea to follow the @sc{posix} guidelines for the
+command-line options of a program. The easiest way to do this is to use
+ at code{getopt} to parse them. Note that the GNU version of @code{getopt}
+will normally permit options anywhere among the arguments unless the
+special argument @samp{--} is used. This is not what @sc{posix}
+specifies; it is a GNU extension.
+
+ at cindex long-named options
+Please define long-named options that are equivalent to the
+single-letter Unix-style options. We hope to make GNU more user
+friendly this way. This is easy to do with the GNU function
+ at code{getopt_long}.
+
+One of the advantages of long-named options is that they can be
+consistent from program to program. For example, users should be able
+to expect the ``verbose'' option of any GNU program which has one, to be
+spelled precisely @samp{--verbose}. To achieve this uniformity, look at
+the table of common long-option names when you choose the option names
+for your program (@pxref{Option Table}).
+
+It is usually a good idea for file names given as ordinary arguments to
+be input files only; any output files would be specified using options
+(preferably @samp{-o} or @samp{--output}). Even if you allow an output
+file name as an ordinary argument for compatibility, try to provide an
+option as another way to specify it. This will lead to more consistency
+among GNU utilities, and fewer idiosyncrasies for users to remember.
+
+ at cindex standard command-line options
+ at cindex options, standard command-line
+ at cindex CGI programs, standard options for
+ at cindex PATH_INFO, specifying standard options as
+All programs should support two standard options: @samp{--version}
+and @samp{--help}. CGI programs should accept these as command-line
+options, and also if given as the @env{PATH_INFO}; for instance,
+visiting @url{http://example.org/p.cgi/--help} in a browser should
+output the same information as invoking @samp{p.cgi --help} from the
+command line.
+
+ at menu
+* --version:: The standard output for --version.
+* --help:: The standard output for --help.
+ at end menu
+
+ at node --version
+ at subsection @option{--version}
+
+ at cindex @samp{--version} output
+
+The standard @code{--version} option should direct the program to
+print information about its name, version, origin and legal status,
+all on standard output, and then exit successfully. Other options and
+arguments should be ignored once this is seen, and the program should
+not perform its normal function.
+
+ at cindex canonical name of a program
+ at cindex program's canonical name
+The first line is meant to be easy for a program to parse; the version
+number proper starts after the last space. In addition, it contains
+the canonical name for this program, in this format:
+
+ at example
+GNU Emacs 19.30
+ at end example
+
+ at noindent
+The program's name should be a constant string; @emph{don't} compute it
+from @code{argv[0]}. The idea is to state the standard or canonical
+name for the program, not its file name. There are other ways to find
+out the precise file name where a command is found in @code{PATH}.
+
+If the program is a subsidiary part of a larger package, mention the
+package name in parentheses, like this:
+
+ at example
+emacsserver (GNU Emacs) 19.30
+ at end example
+
+ at noindent
+If the package has a version number which is different from this
+program's version number, you can mention the package version number
+just before the close-parenthesis.
+
+If you @emph{need} to mention the version numbers of libraries which
+are distributed separately from the package which contains this program,
+you can do so by printing an additional line of version info for each
+library you want to mention. Use the same format for these lines as for
+the first line.
+
+Please do not mention all of the libraries that the program uses ``just
+for completeness''---that would produce a lot of unhelpful clutter.
+Please mention library version numbers only if you find in practice that
+they are very important to you in debugging.
+
+The following line, after the version number line or lines, should be a
+copyright notice. If more than one copyright notice is called for, put
+each on a separate line.
+
+Next should follow a line stating the license, preferably using one of
+abbreviations below, and a brief statement that the program is free
+software, and that users are free to copy and change it. Also mention
+that there is no warranty, to the extent permitted by law. See
+recommended wording below.
+
+It is ok to finish the output with a list of the major authors of the
+program, as a way of giving credit.
+
+Here's an example of output that follows these rules:
+
+ at smallexample
+GNU hello 2.3
+Copyright (C) 2007 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+ at end smallexample
+
+You should adapt this to your program, of course, filling in the proper
+year, copyright holder, name of program, and the references to
+distribution terms, and changing the rest of the wording as necessary.
+
+This copyright notice only needs to mention the most recent year in
+which changes were made---there's no need to list the years for previous
+versions' changes. You don't have to mention the name of the program in
+these notices, if that is inconvenient, since it appeared in the first
+line. (The rules are different for copyright notices in source files;
+ at pxref{Copyright Notices,,,maintain,Information for GNU Maintainers}.)
+
+Translations of the above lines must preserve the validity of the
+copyright notices (@pxref{Internationalization}). If the translation's
+character set supports it, the @samp{(C)} should be replaced with the
+copyright symbol, as follows:
+
+ at ifinfo
+(the official copyright symbol, which is the letter C in a circle);
+ at end ifinfo
+ at ifnotinfo
+ at copyright{}
+ at end ifnotinfo
+
+Write the word ``Copyright'' exactly like that, in English. Do not
+translate it into another language. International treaties recognize
+the English word ``Copyright''; translations into other languages do not
+have legal significance.
+
+Finally, here is the table of our suggested license abbreviations.
+Any abbreviation can be followed by @samp{v at var{version}[+]}, meaning
+that particular version, or later versions with the @samp{+}, as shown
+above.
+
+In the case of exceptions for extra permissions with the GPL, we use
+ at samp{/} for a separator; the version number can follow the license
+abbreviation as usual, as in the examples below.
+
+ at table @asis
+ at item GPL
+GNU General Public License, @url{http://www.gnu.org/@/licenses/@/gpl.html}.
+
+ at item LGPL
+GNU Lesser General Public License, @url{http://www.gnu.org/@/licenses/@/lgpl.html}.
+
+ at item GPL/Ada
+GNU GPL with the exception for Ada.
+
+ at item Apache
+The Apache Software Foundation license,
+ at url{http://www.apache.org/@/licenses}.
+
+ at item Artistic
+The Artistic license used for Perl, @url{http://www.perlfoundation.org/@/legal}.
+
+ at item Expat
+The Expat license, @url{http://www.jclark.com/@/xml/@/copying.txt}.
+
+ at item MPL
+The Mozilla Public License, @url{http://www.mozilla.org/@/MPL/}.
+
+ at item OBSD
+The original (4-clause) BSD license, incompatible with the GNU GPL
+ at url{http://www.xfree86.org/@/3.3.6/@/COPYRIGHT2.html#6}.
+
+ at item PHP
+The license used for PHP, @url{http://www.php.net/@/license/}.
+
+ at item public domain
+The non-license that is being in the public domain,
+ at url{http://www.gnu.org/@/licenses/@/license-list.html#PublicDomain}.
+
+ at item Python
+The license for Python, @url{http://www.python.org/@/2.0.1/@/license.html}.
+
+ at item RBSD
+The revised (3-clause) BSD, compatible with the GNU GPL,@*
+ at url{http://www.xfree86.org/@/3.3.6/@/COPYRIGHT2.html#5}.
+
+ at item X11
+The simple non-copyleft license used for most versions of the X Window
+System, @url{http://www.xfree86.org/@/3.3.6/@/COPYRIGHT2.html#3}.
+
+ at item Zlib
+The license for Zlib, @url{http://www.gzip.org/@/zlib/@/zlib_license.html}.
+
+ at end table
+
+More information about these licenses and many more are on the GNU
+licensing web pages,
+ at url{http://www.gnu.org/@/licenses/@/license-list.html}.
+
+
+ at node --help
+ at subsection @option{--help}
+
+ at cindex @samp{--help} output
+
+The standard @code{--help} option should output brief documentation
+for how to invoke the program, on standard output, then exit
+successfully. Other options and arguments should be ignored once this
+is seen, and the program should not perform its normal function.
+
+ at cindex address for bug reports
+ at cindex bug reports
+Near the end of the @samp{--help} option's output, please place lines
+giving the email address for bug reports, the package's home page
+(normally @indicateurl{http://www.gnu.org/software/@var{pkg}}, and the
+general page for help using GNU programs. The format should be like this:
+
+ at example
+Report bugs to: @var{mailing-address}
+ at var{pkg} home page: <http://www.gnu.org/software/@var{pkg}/>
+General help using GNU software: <http://www.gnu.org/gethelp/>
+ at end example
+
+It is ok to mention other appropriate mailing lists and web pages.
+
+
+ at node Dynamic Plug-In Interfaces
+ at section Standards for Dynamic Plug-in Interfaces
+ at cindex plug-ins
+ at cindex dynamic plug-ins
+
+Another aspect of keeping free programs free is encouraging
+development of free plug-ins, and discouraging development of
+proprietary plug-ins. Many GNU programs will not have anything like
+plug-ins at all, but those that do should follow these
+practices.
+
+First, the general plug-in architecture design should closely tie the
+plug-in to the original code, such that the plug-in and the base
+program are parts of one extended program. For GCC, for example,
+plug-ins receive and modify GCC's internal data structures, and so
+clearly form an extended program with the base GCC.
+
+ at vindex plugin_is_GPL_compatible
+Second, you should require plug-in developers to affirm that their
+plug-ins are released under an appropriate license. This should be
+enforced with a simple programmatic check. For GCC, again for
+example, a plug-in must define the global symbol
+ at code{plugin_is_GPL_compatible}, thus asserting that the plug-in is
+released under a GPL-compatible license (@pxref{Plugins,, Plugins,
+gccint, GCC Internals}).
+
+By adding this check to your program you are not creating a new legal
+requirement. The GPL itself requires plug-ins to be free software,
+licensed compatibly. As long as you have followed the first rule above
+to keep plug-ins closely tied to your original program, the GPL and AGPL
+already require those plug-ins to be released under a compatible
+license. The symbol definition in the plug-in---or whatever equivalent
+works best in your program---makes it harder for anyone who might
+distribute proprietary plug-ins to legally defend themselves. If a case
+about this got to court, we can point to that symbol as evidence that
+the plug-in developer understood that the license had this requirement.
+
+
+ at node Option Table
+ at section Table of Long Options
+ at cindex long option names
+ at cindex table of long options
+
+Here is a table of long options used by GNU programs. It is surely
+incomplete, but we aim to list all the options that a new program might
+want to be compatible with. If you use names not already in the table,
+please send @email{bug-standards@@gnu.org} a list of them, with their
+meanings, so we can update the table.
+
+ at c Please leave newlines between items in this table; it's much easier
+ at c to update when it isn't completely squashed together and unreadable.
+ at c When there is more than one short option for a long option name, put
+ at c a semicolon between the lists of the programs that use them, not a
+ at c period. --friedman
+
+ at table @samp
+ at item after-date
+ at samp{-N} in @code{tar}.
+
+ at item all
+ at samp{-a} in @code{du}, @code{ls}, @code{nm}, @code{stty}, @code{uname},
+and @code{unexpand}.
+
+ at item all-text
+ at samp{-a} in @code{diff}.
+
+ at item almost-all
+ at samp{-A} in @code{ls}.
+
+ at item append
+ at samp{-a} in @code{etags}, @code{tee}, @code{time};
+ at samp{-r} in @code{tar}.
+
+ at item archive
+ at samp{-a} in @code{cp}.
+
+ at item archive-name
+ at samp{-n} in @code{shar}.
+
+ at item arglength
+ at samp{-l} in @code{m4}.
+
+ at item ascii
+ at samp{-a} in @code{diff}.
+
+ at item assign
+ at samp{-v} in @code{gawk}.
+
+ at item assume-new
+ at samp{-W} in @code{make}.
+
+ at item assume-old
+ at samp{-o} in @code{make}.
+
+ at item auto-check
+ at samp{-a} in @code{recode}.
+
+ at item auto-pager
+ at samp{-a} in @code{wdiff}.
+
+ at item auto-reference
+ at samp{-A} in @code{ptx}.
+
+ at item avoid-wraps
+ at samp{-n} in @code{wdiff}.
+
+ at item background
+For server programs, run in the background.
+
+ at item backward-search
+ at samp{-B} in @code{ctags}.
+
+ at item basename
+ at samp{-f} in @code{shar}.
+
+ at item batch
+Used in GDB.
+
+ at item baud
+Used in GDB.
+
+ at item before
+ at samp{-b} in @code{tac}.
+
+ at item binary
+ at samp{-b} in @code{cpio} and @code{diff}.
+
+ at item bits-per-code
+ at samp{-b} in @code{shar}.
+
+ at item block-size
+Used in @code{cpio} and @code{tar}.
+
+ at item blocks
+ at samp{-b} in @code{head} and @code{tail}.
+
+ at item break-file
+ at samp{-b} in @code{ptx}.
+
+ at item brief
+Used in various programs to make output shorter.
+
+ at item bytes
+ at samp{-c} in @code{head}, @code{split}, and @code{tail}.
+
+ at item c at t{++}
+ at samp{-C} in @code{etags}.
+
+ at item catenate
+ at samp{-A} in @code{tar}.
+
+ at item cd
+Used in various programs to specify the directory to use.
+
+ at item changes
+ at samp{-c} in @code{chgrp} and @code{chown}.
+
+ at item classify
+ at samp{-F} in @code{ls}.
+
+ at item colons
+ at samp{-c} in @code{recode}.
+
+ at item command
+ at samp{-c} in @code{su};
+ at samp{-x} in GDB.
+
+ at item compare
+ at samp{-d} in @code{tar}.
+
+ at item compat
+Used in @code{gawk}.
+
+ at item compress
+ at samp{-Z} in @code{tar} and @code{shar}.
+
+ at item concatenate
+ at samp{-A} in @code{tar}.
+
+ at item confirmation
+ at samp{-w} in @code{tar}.
+
+ at item context
+Used in @code{diff}.
+
+ at item copyleft
+ at samp{-W copyleft} in @code{gawk}.
+
+ at item copyright
+ at samp{-C} in @code{ptx}, @code{recode}, and @code{wdiff};
+ at samp{-W copyright} in @code{gawk}.
+
+ at item core
+Used in GDB.
+
+ at item count
+ at samp{-q} in @code{who}.
+
+ at item count-links
+ at samp{-l} in @code{du}.
+
+ at item create
+Used in @code{tar} and @code{cpio}.
+
+ at item cut-mark
+ at samp{-c} in @code{shar}.
+
+ at item cxref
+ at samp{-x} in @code{ctags}.
+
+ at item date
+ at samp{-d} in @code{touch}.
+
+ at item debug
+ at samp{-d} in @code{make} and @code{m4};
+ at samp{-t} in Bison.
+
+ at item define
+ at samp{-D} in @code{m4}.
+
+ at item defines
+ at samp{-d} in Bison and @code{ctags}.
+
+ at item delete
+ at samp{-D} in @code{tar}.
+
+ at item dereference
+ at samp{-L} in @code{chgrp}, @code{chown}, @code{cpio}, @code{du},
+ at code{ls}, and @code{tar}.
+
+ at item dereference-args
+ at samp{-D} in @code{du}.
+
+ at item device
+Specify an I/O device (special file name).
+
+ at item diacritics
+ at samp{-d} in @code{recode}.
+
+ at item dictionary-order
+ at samp{-d} in @code{look}.
+
+ at item diff
+ at samp{-d} in @code{tar}.
+
+ at item digits
+ at samp{-n} in @code{csplit}.
+
+ at item directory
+Specify the directory to use, in various programs. In @code{ls}, it
+means to show directories themselves rather than their contents. In
+ at code{rm} and @code{ln}, it means to not treat links to directories
+specially.
+
+ at item discard-all
+ at samp{-x} in @code{strip}.
+
+ at item discard-locals
+ at samp{-X} in @code{strip}.
+
+ at item dry-run
+ at samp{-n} in @code{make}.
+
+ at item ed
+ at samp{-e} in @code{diff}.
+
+ at item elide-empty-files
+ at samp{-z} in @code{csplit}.
+
+ at item end-delete
+ at samp{-x} in @code{wdiff}.
+
+ at item end-insert
+ at samp{-z} in @code{wdiff}.
+
+ at item entire-new-file
+ at samp{-N} in @code{diff}.
+
+ at item environment-overrides
+ at samp{-e} in @code{make}.
+
+ at item eof
+ at samp{-e} in @code{xargs}.
+
+ at item epoch
+Used in GDB.
+
+ at item error-limit
+Used in @code{makeinfo}.
+
+ at item error-output
+ at samp{-o} in @code{m4}.
+
+ at item escape
+ at samp{-b} in @code{ls}.
+
+ at item exclude-from
+ at samp{-X} in @code{tar}.
+
+ at item exec
+Used in GDB.
+
+ at item exit
+ at samp{-x} in @code{xargs}.
+
+ at item exit-0
+ at samp{-e} in @code{unshar}.
+
+ at item expand-tabs
+ at samp{-t} in @code{diff}.
+
+ at item expression
+ at samp{-e} in @code{sed}.
+
+ at item extern-only
+ at samp{-g} in @code{nm}.
+
+ at item extract
+ at samp{-i} in @code{cpio};
+ at samp{-x} in @code{tar}.
+
+ at item faces
+ at samp{-f} in @code{finger}.
+
+ at item fast
+ at samp{-f} in @code{su}.
+
+ at item fatal-warnings
+ at samp{-E} in @code{m4}.
+
+ at item file
+ at samp{-f} in @code{gawk}, @code{info}, @code{make}, @code{mt},
+ at code{sed}, and @code{tar}.
+
+ at item field-separator
+ at samp{-F} in @code{gawk}.
+
+ at item file-prefix
+ at samp{-b} in Bison.
+
+ at item file-type
+ at samp{-F} in @code{ls}.
+
+ at item files-from
+ at samp{-T} in @code{tar}.
+
+ at item fill-column
+Used in @code{makeinfo}.
+
+ at item flag-truncation
+ at samp{-F} in @code{ptx}.
+
+ at item fixed-output-files
+ at samp{-y} in Bison.
+
+ at item follow
+ at samp{-f} in @code{tail}.
+
+ at item footnote-style
+Used in @code{makeinfo}.
+
+ at item force
+ at samp{-f} in @code{cp}, @code{ln}, @code{mv}, and @code{rm}.
+
+ at item force-prefix
+ at samp{-F} in @code{shar}.
+
+ at item foreground
+For server programs, run in the foreground;
+in other words, don't do anything special to run the server
+in the background.
+
+ at item format
+Used in @code{ls}, @code{time}, and @code{ptx}.
+
+ at item freeze-state
+ at samp{-F} in @code{m4}.
+
+ at item fullname
+Used in GDB.
+
+ at item gap-size
+ at samp{-g} in @code{ptx}.
+
+ at item get
+ at samp{-x} in @code{tar}.
+
+ at item graphic
+ at samp{-i} in @code{ul}.
+
+ at item graphics
+ at samp{-g} in @code{recode}.
+
+ at item group
+ at samp{-g} in @code{install}.
+
+ at item gzip
+ at samp{-z} in @code{tar} and @code{shar}.
+
+ at item hashsize
+ at samp{-H} in @code{m4}.
+
+ at item header
+ at samp{-h} in @code{objdump} and @code{recode}
+
+ at item heading
+ at samp{-H} in @code{who}.
+
+ at item help
+Used to ask for brief usage information.
+
+ at item here-delimiter
+ at samp{-d} in @code{shar}.
+
+ at item hide-control-chars
+ at samp{-q} in @code{ls}.
+
+ at item html
+In @code{makeinfo}, output HTML.
+
+ at item idle
+ at samp{-u} in @code{who}.
+
+ at item ifdef
+ at samp{-D} in @code{diff}.
+
+ at item ignore
+ at samp{-I} in @code{ls};
+ at samp{-x} in @code{recode}.
+
+ at item ignore-all-space
+ at samp{-w} in @code{diff}.
+
+ at item ignore-backups
+ at samp{-B} in @code{ls}.
+
+ at item ignore-blank-lines
+ at samp{-B} in @code{diff}.
+
+ at item ignore-case
+ at samp{-f} in @code{look} and @code{ptx};
+ at samp{-i} in @code{diff} and @code{wdiff}.
+
+ at item ignore-errors
+ at samp{-i} in @code{make}.
+
+ at item ignore-file
+ at samp{-i} in @code{ptx}.
+
+ at item ignore-indentation
+ at samp{-I} in @code{etags}.
+
+ at item ignore-init-file
+ at samp{-f} in Oleo.
+
+ at item ignore-interrupts
+ at samp{-i} in @code{tee}.
+
+ at item ignore-matching-lines
+ at samp{-I} in @code{diff}.
+
+ at item ignore-space-change
+ at samp{-b} in @code{diff}.
+
+ at item ignore-zeros
+ at samp{-i} in @code{tar}.
+
+ at item include
+ at samp{-i} in @code{etags};
+ at samp{-I} in @code{m4}.
+
+ at item include-dir
+ at samp{-I} in @code{make}.
+
+ at item incremental
+ at samp{-G} in @code{tar}.
+
+ at item info
+ at samp{-i}, @samp{-l}, and @samp{-m} in Finger.
+
+ at item init-file
+In some programs, specify the name of the file to read as the user's
+init file.
+
+ at item initial
+ at samp{-i} in @code{expand}.
+
+ at item initial-tab
+ at samp{-T} in @code{diff}.
+
+ at item inode
+ at samp{-i} in @code{ls}.
+
+ at item interactive
+ at samp{-i} in @code{cp}, @code{ln}, @code{mv}, @code{rm};
+ at samp{-e} in @code{m4};
+ at samp{-p} in @code{xargs};
+ at samp{-w} in @code{tar}.
+
+ at item intermix-type
+ at samp{-p} in @code{shar}.
+
+ at item iso-8601
+Used in @code{date}
+
+ at item jobs
+ at samp{-j} in @code{make}.
+
+ at item just-print
+ at samp{-n} in @code{make}.
+
+ at item keep-going
+ at samp{-k} in @code{make}.
+
+ at item keep-files
+ at samp{-k} in @code{csplit}.
+
+ at item kilobytes
+ at samp{-k} in @code{du} and @code{ls}.
+
+ at item language
+ at samp{-l} in @code{etags}.
+
+ at item less-mode
+ at samp{-l} in @code{wdiff}.
+
+ at item level-for-gzip
+ at samp{-g} in @code{shar}.
+
+ at item line-bytes
+ at samp{-C} in @code{split}.
+
+ at item lines
+Used in @code{split}, @code{head}, and @code{tail}.
+
+ at item link
+ at samp{-l} in @code{cpio}.
+
+ at item lint
+ at itemx lint-old
+Used in @code{gawk}.
+
+ at item list
+ at samp{-t} in @code{cpio};
+ at samp{-l} in @code{recode}.
+
+ at item list
+ at samp{-t} in @code{tar}.
+
+ at item literal
+ at samp{-N} in @code{ls}.
+
+ at item load-average
+ at samp{-l} in @code{make}.
+
+ at item login
+Used in @code{su}.
+
+ at item machine
+Used in @code{uname}.
+
+ at item macro-name
+ at samp{-M} in @code{ptx}.
+
+ at item mail
+ at samp{-m} in @code{hello} and @code{uname}.
+
+ at item make-directories
+ at samp{-d} in @code{cpio}.
+
+ at item makefile
+ at samp{-f} in @code{make}.
+
+ at item mapped
+Used in GDB.
+
+ at item max-args
+ at samp{-n} in @code{xargs}.
+
+ at item max-chars
+ at samp{-n} in @code{xargs}.
+
+ at item max-lines
+ at samp{-l} in @code{xargs}.
+
+ at item max-load
+ at samp{-l} in @code{make}.
+
+ at item max-procs
+ at samp{-P} in @code{xargs}.
+
+ at item mesg
+ at samp{-T} in @code{who}.
+
+ at item message
+ at samp{-T} in @code{who}.
+
+ at item minimal
+ at samp{-d} in @code{diff}.
+
+ at item mixed-uuencode
+ at samp{-M} in @code{shar}.
+
+ at item mode
+ at samp{-m} in @code{install}, @code{mkdir}, and @code{mkfifo}.
+
+ at item modification-time
+ at samp{-m} in @code{tar}.
+
+ at item multi-volume
+ at samp{-M} in @code{tar}.
+
+ at item name-prefix
+ at samp{-a} in Bison.
+
+ at item nesting-limit
+ at samp{-L} in @code{m4}.
+
+ at item net-headers
+ at samp{-a} in @code{shar}.
+
+ at item new-file
+ at samp{-W} in @code{make}.
+
+ at item no-builtin-rules
+ at samp{-r} in @code{make}.
+
+ at item no-character-count
+ at samp{-w} in @code{shar}.
+
+ at item no-check-existing
+ at samp{-x} in @code{shar}.
+
+ at item no-common
+ at samp{-3} in @code{wdiff}.
+
+ at item no-create
+ at samp{-c} in @code{touch}.
+
+ at item no-defines
+ at samp{-D} in @code{etags}.
+
+ at item no-deleted
+ at samp{-1} in @code{wdiff}.
+
+ at item no-dereference
+ at samp{-d} in @code{cp}.
+
+ at item no-inserted
+ at samp{-2} in @code{wdiff}.
+
+ at item no-keep-going
+ at samp{-S} in @code{make}.
+
+ at item no-lines
+ at samp{-l} in Bison.
+
+ at item no-piping
+ at samp{-P} in @code{shar}.
+
+ at item no-prof
+ at samp{-e} in @code{gprof}.
+
+ at item no-regex
+ at samp{-R} in @code{etags}.
+
+ at item no-sort
+ at samp{-p} in @code{nm}.
+
+ at item no-splash
+Don't print a startup splash screen.
+
+ at item no-split
+Used in @code{makeinfo}.
+
+ at item no-static
+ at samp{-a} in @code{gprof}.
+
+ at item no-time
+ at samp{-E} in @code{gprof}.
+
+ at item no-timestamp
+ at samp{-m} in @code{shar}.
+
+ at item no-validate
+Used in @code{makeinfo}.
+
+ at item no-wait
+Used in @code{emacsclient}.
+
+ at item no-warn
+Used in various programs to inhibit warnings.
+
+ at item node
+ at samp{-n} in @code{info}.
+
+ at item nodename
+ at samp{-n} in @code{uname}.
+
+ at item nonmatching
+ at samp{-f} in @code{cpio}.
+
+ at item nstuff
+ at samp{-n} in @code{objdump}.
+
+ at item null
+ at samp{-0} in @code{xargs}.
+
+ at item number
+ at samp{-n} in @code{cat}.
+
+ at item number-nonblank
+ at samp{-b} in @code{cat}.
+
+ at item numeric-sort
+ at samp{-n} in @code{nm}.
+
+ at item numeric-uid-gid
+ at samp{-n} in @code{cpio} and @code{ls}.
+
+ at item nx
+Used in GDB.
+
+ at item old-archive
+ at samp{-o} in @code{tar}.
+
+ at item old-file
+ at samp{-o} in @code{make}.
+
+ at item one-file-system
+ at samp{-l} in @code{tar}, @code{cp}, and @code{du}.
+
+ at item only-file
+ at samp{-o} in @code{ptx}.
+
+ at item only-prof
+ at samp{-f} in @code{gprof}.
+
+ at item only-time
+ at samp{-F} in @code{gprof}.
+
+ at item options
+ at samp{-o} in @code{getopt}, @code{fdlist}, @code{fdmount},
+ at code{fdmountd}, and @code{fdumount}.
+
+ at item output
+In various programs, specify the output file name.
+
+ at item output-prefix
+ at samp{-o} in @code{shar}.
+
+ at item override
+ at samp{-o} in @code{rm}.
+
+ at item overwrite
+ at samp{-c} in @code{unshar}.
+
+ at item owner
+ at samp{-o} in @code{install}.
+
+ at item paginate
+ at samp{-l} in @code{diff}.
+
+ at item paragraph-indent
+Used in @code{makeinfo}.
+
+ at item parents
+ at samp{-p} in @code{mkdir} and @code{rmdir}.
+
+ at item pass-all
+ at samp{-p} in @code{ul}.
+
+ at item pass-through
+ at samp{-p} in @code{cpio}.
+
+ at item port
+ at samp{-P} in @code{finger}.
+
+ at item portability
+ at samp{-c} in @code{cpio} and @code{tar}.
+
+ at item posix
+Used in @code{gawk}.
+
+ at item prefix-builtins
+ at samp{-P} in @code{m4}.
+
+ at item prefix
+ at samp{-f} in @code{csplit}.
+
+ at item preserve
+Used in @code{tar} and @code{cp}.
+
+ at item preserve-environment
+ at samp{-p} in @code{su}.
+
+ at item preserve-modification-time
+ at samp{-m} in @code{cpio}.
+
+ at item preserve-order
+ at samp{-s} in @code{tar}.
+
+ at item preserve-permissions
+ at samp{-p} in @code{tar}.
+
+ at item print
+ at samp{-l} in @code{diff}.
+
+ at item print-chars
+ at samp{-L} in @code{cmp}.
+
+ at item print-data-base
+ at samp{-p} in @code{make}.
+
+ at item print-directory
+ at samp{-w} in @code{make}.
+
+ at item print-file-name
+ at samp{-o} in @code{nm}.
+
+ at item print-symdefs
+ at samp{-s} in @code{nm}.
+
+ at item printer
+ at samp{-p} in @code{wdiff}.
+
+ at item prompt
+ at samp{-p} in @code{ed}.
+
+ at item proxy
+Specify an HTTP proxy.
+
+ at item query-user
+ at samp{-X} in @code{shar}.
+
+ at item question
+ at samp{-q} in @code{make}.
+
+ at item quiet
+Used in many programs to inhibit the usual output. Every
+program accepting @samp{--quiet} should accept @samp{--silent} as a
+synonym.
+
+ at item quiet-unshar
+ at samp{-Q} in @code{shar}
+
+ at item quote-name
+ at samp{-Q} in @code{ls}.
+
+ at item rcs
+ at samp{-n} in @code{diff}.
+
+ at item re-interval
+Used in @code{gawk}.
+
+ at item read-full-blocks
+ at samp{-B} in @code{tar}.
+
+ at item readnow
+Used in GDB.
+
+ at item recon
+ at samp{-n} in @code{make}.
+
+ at item record-number
+ at samp{-R} in @code{tar}.
+
+ at item recursive
+Used in @code{chgrp}, @code{chown}, @code{cp}, @code{ls}, @code{diff},
+and @code{rm}.
+
+ at item reference
+ at samp{-r} in @code{touch}.
+
+ at item references
+ at samp{-r} in @code{ptx}.
+
+ at item regex
+ at samp{-r} in @code{tac} and @code{etags}.
+
+ at item release
+ at samp{-r} in @code{uname}.
+
+ at item reload-state
+ at samp{-R} in @code{m4}.
+
+ at item relocation
+ at samp{-r} in @code{objdump}.
+
+ at item rename
+ at samp{-r} in @code{cpio}.
+
+ at item replace
+ at samp{-i} in @code{xargs}.
+
+ at item report-identical-files
+ at samp{-s} in @code{diff}.
+
+ at item reset-access-time
+ at samp{-a} in @code{cpio}.
+
+ at item reverse
+ at samp{-r} in @code{ls} and @code{nm}.
+
+ at item reversed-ed
+ at samp{-f} in @code{diff}.
+
+ at item right-side-defs
+ at samp{-R} in @code{ptx}.
+
+ at item same-order
+ at samp{-s} in @code{tar}.
+
+ at item same-permissions
+ at samp{-p} in @code{tar}.
+
+ at item save
+ at samp{-g} in @code{stty}.
+
+ at item se
+Used in GDB.
+
+ at item sentence-regexp
+ at samp{-S} in @code{ptx}.
+
+ at item separate-dirs
+ at samp{-S} in @code{du}.
+
+ at item separator
+ at samp{-s} in @code{tac}.
+
+ at item sequence
+Used by @code{recode} to chose files or pipes for sequencing passes.
+
+ at item shell
+ at samp{-s} in @code{su}.
+
+ at item show-all
+ at samp{-A} in @code{cat}.
+
+ at item show-c-function
+ at samp{-p} in @code{diff}.
+
+ at item show-ends
+ at samp{-E} in @code{cat}.
+
+ at item show-function-line
+ at samp{-F} in @code{diff}.
+
+ at item show-tabs
+ at samp{-T} in @code{cat}.
+
+ at item silent
+Used in many programs to inhibit the usual output.
+Every program accepting
+ at samp{--silent} should accept @samp{--quiet} as a synonym.
+
+ at item size
+ at samp{-s} in @code{ls}.
+
+ at item socket
+Specify a file descriptor for a network server to use for its socket,
+instead of opening and binding a new socket. This provides a way to
+run, in a non-privileged process, a server that normally needs a
+reserved port number.
+
+ at item sort
+Used in @code{ls}.
+
+ at item source
+ at samp{-W source} in @code{gawk}.
+
+ at item sparse
+ at samp{-S} in @code{tar}.
+
+ at item speed-large-files
+ at samp{-H} in @code{diff}.
+
+ at item split-at
+ at samp{-E} in @code{unshar}.
+
+ at item split-size-limit
+ at samp{-L} in @code{shar}.
+
+ at item squeeze-blank
+ at samp{-s} in @code{cat}.
+
+ at item start-delete
+ at samp{-w} in @code{wdiff}.
+
+ at item start-insert
+ at samp{-y} in @code{wdiff}.
+
+ at item starting-file
+Used in @code{tar} and @code{diff} to specify which file within
+a directory to start processing with.
+
+ at item statistics
+ at samp{-s} in @code{wdiff}.
+
+ at item stdin-file-list
+ at samp{-S} in @code{shar}.
+
+ at item stop
+ at samp{-S} in @code{make}.
+
+ at item strict
+ at samp{-s} in @code{recode}.
+
+ at item strip
+ at samp{-s} in @code{install}.
+
+ at item strip-all
+ at samp{-s} in @code{strip}.
+
+ at item strip-debug
+ at samp{-S} in @code{strip}.
+
+ at item submitter
+ at samp{-s} in @code{shar}.
+
+ at item suffix
+ at samp{-S} in @code{cp}, @code{ln}, @code{mv}.
+
+ at item suffix-format
+ at samp{-b} in @code{csplit}.
+
+ at item sum
+ at samp{-s} in @code{gprof}.
+
+ at item summarize
+ at samp{-s} in @code{du}.
+
+ at item symbolic
+ at samp{-s} in @code{ln}.
+
+ at item symbols
+Used in GDB and @code{objdump}.
+
+ at item synclines
+ at samp{-s} in @code{m4}.
+
+ at item sysname
+ at samp{-s} in @code{uname}.
+
+ at item tabs
+ at samp{-t} in @code{expand} and @code{unexpand}.
+
+ at item tabsize
+ at samp{-T} in @code{ls}.
+
+ at item terminal
+ at samp{-T} in @code{tput} and @code{ul}.
+ at samp{-t} in @code{wdiff}.
+
+ at item text
+ at samp{-a} in @code{diff}.
+
+ at item text-files
+ at samp{-T} in @code{shar}.
+
+ at item time
+Used in @code{ls} and @code{touch}.
+
+ at item timeout
+Specify how long to wait before giving up on some operation.
+
+ at item to-stdout
+ at samp{-O} in @code{tar}.
+
+ at item total
+ at samp{-c} in @code{du}.
+
+ at item touch
+ at samp{-t} in @code{make}, @code{ranlib}, and @code{recode}.
+
+ at item trace
+ at samp{-t} in @code{m4}.
+
+ at item traditional
+ at samp{-t} in @code{hello};
+ at samp{-W traditional} in @code{gawk};
+ at samp{-G} in @code{ed}, @code{m4}, and @code{ptx}.
+
+ at item tty
+Used in GDB.
+
+ at item typedefs
+ at samp{-t} in @code{ctags}.
+
+ at item typedefs-and-c++
+ at samp{-T} in @code{ctags}.
+
+ at item typeset-mode
+ at samp{-t} in @code{ptx}.
+
+ at item uncompress
+ at samp{-z} in @code{tar}.
+
+ at item unconditional
+ at samp{-u} in @code{cpio}.
+
+ at item undefine
+ at samp{-U} in @code{m4}.
+
+ at item undefined-only
+ at samp{-u} in @code{nm}.
+
+ at item update
+ at samp{-u} in @code{cp}, @code{ctags}, @code{mv}, @code{tar}.
+
+ at item usage
+Used in @code{gawk}; same as @samp{--help}.
+
+ at item uuencode
+ at samp{-B} in @code{shar}.
+
+ at item vanilla-operation
+ at samp{-V} in @code{shar}.
+
+ at item verbose
+Print more information about progress. Many programs support this.
+
+ at item verify
+ at samp{-W} in @code{tar}.
+
+ at item version
+Print the version number.
+
+ at item version-control
+ at samp{-V} in @code{cp}, @code{ln}, @code{mv}.
+
+ at item vgrind
+ at samp{-v} in @code{ctags}.
+
+ at item volume
+ at samp{-V} in @code{tar}.
+
+ at item what-if
+ at samp{-W} in @code{make}.
+
+ at item whole-size-limit
+ at samp{-l} in @code{shar}.
+
+ at item width
+ at samp{-w} in @code{ls} and @code{ptx}.
+
+ at item word-regexp
+ at samp{-W} in @code{ptx}.
+
+ at item writable
+ at samp{-T} in @code{who}.
+
+ at item zeros
+ at samp{-z} in @code{gprof}.
+ at end table
+
+ at node OID Allocations
+ at section OID Allocations
+ at cindex OID allocations for GNU
+ at cindex SNMP
+ at cindex LDAP
+ at cindex X.509
+
+The OID (object identifier) 1.3.6.1.4.1.11591 has been assigned to the
+GNU Project (thanks to Werner Koch). These are used for SNMP, LDAP,
+X.509 certificates, and so on. The web site
+ at url{http://www.alvestrand.no/objectid} has a (voluntary) listing of
+many OID assignments.
+
+If you need a new slot for your GNU package, write
+ at email{maintainers@@gnu.org}. Here is a list of arcs currently
+assigned:
+
+ at example
+ at include gnu-oids.texi
+ at end example
+
+
+ at node Memory Usage
+ at section Memory Usage
+ at cindex memory usage
+
+If a program typically uses just a few meg of memory, don't bother making any
+effort to reduce memory usage. For example, if it is impractical for
+other reasons to operate on files more than a few meg long, it is
+reasonable to read entire input files into memory to operate on them.
+
+However, for programs such as @code{cat} or @code{tail}, that can
+usefully operate on very large files, it is important to avoid using a
+technique that would artificially limit the size of files it can handle.
+If a program works by lines and could be applied to arbitrary
+user-supplied input files, it should keep only a line in memory, because
+this is not very hard and users will want to be able to operate on input
+files that are bigger than will fit in memory all at once.
+
+If your program creates complicated data structures, just make them in
+memory and give a fatal error if @code{malloc} returns zero.
+
+ at pindex valgrind
+ at cindex memory leak
+Memory analysis tools such as @command{valgrind} can be useful, but
+don't complicate a program merely to avoid their false alarms. For
+example, if memory is used until just before a process exits, don't
+free it simply to silence such a tool.
+
+
+ at node File Usage
+ at section File Usage
+ at cindex file usage
+
+Programs should be prepared to operate when @file{/usr} and @file{/etc}
+are read-only file systems. Thus, if the program manages log files,
+lock files, backup files, score files, or any other files which are
+modified for internal purposes, these files should not be stored in
+ at file{/usr} or @file{/etc}.
+
+There are two exceptions. @file{/etc} is used to store system
+configuration information; it is reasonable for a program to modify
+files in @file{/etc} when its job is to update the system configuration.
+Also, if the user explicitly asks to modify one file in a directory, it
+is reasonable for the program to store other files in the same
+directory.
+
+ at node Writing C
+ at chapter Making The Best Use of C
+
+This chapter provides advice on how best to use the C language
+when writing GNU software.
+
+ at menu
+* Formatting:: Formatting your source code.
+* Comments:: Commenting your work.
+* Syntactic Conventions:: Clean use of C constructs.
+* Names:: Naming variables, functions, and files.
+* System Portability:: Portability among different operating systems.
+* CPU Portability:: Supporting the range of CPU types.
+* System Functions:: Portability and ``standard'' library functions.
+* Internationalization:: Techniques for internationalization.
+* Character Set:: Use ASCII by default.
+* Quote Characters:: Use "..." or '...' in the C locale.
+* Mmap:: How you can safely use @code{mmap}.
+ at end menu
+
+ at node Formatting
+ at section Formatting Your Source Code
+ at cindex formatting source code
+
+ at cindex open brace
+ at cindex braces, in C source
+ at cindex function definitions, formatting
+It is important to put the open-brace that starts the body of a C
+function in column one, so that they will start a defun. Several
+tools look for open-braces in column one to find the beginnings of C
+functions. These tools will not work on code not formatted that way.
+
+Avoid putting open-brace, open-parenthesis or open-bracket in column
+one when they are inside a function, so that they won't start a defun.
+The open-brace that starts a @code{struct} body can go in column one
+if you find it useful to treat that definition as a defun.
+
+It is also important for function definitions to start the name of the
+function in column one. This helps people to search for function
+definitions, and may also help certain tools recognize them. Thus,
+using Standard C syntax, the format is this:
+
+ at example
+static char *
+concat (char *s1, char *s2)
+@{
+ @dots{}
+@}
+ at end example
+
+ at noindent
+or, if you want to use traditional C syntax, format the definition like
+this:
+
+ at example
+static char *
+concat (s1, s2) /* Name starts in column one here */
+ char *s1, *s2;
+@{ /* Open brace in column one here */
+ @dots{}
+@}
+ at end example
+
+In Standard C, if the arguments don't fit nicely on one line,
+split it like this:
+
+ at example
+int
+lots_of_args (int an_integer, long a_long, short a_short,
+ double a_double, float a_float)
+ at dots{}
+ at end example
+
+ at cindex @code{struct} types, formatting
+ at cindex @code{enum} types, formatting
+For @code{struct} and @code{enum} types, likewise put the braces in
+column one, unless the whole contents fits on one line:
+
+ at example
+struct foo
+@{
+ int a, b;
+@}
+ at exdent @r{or}
+struct foo @{ int a, b; @}
+ at end example
+
+The rest of this section gives our recommendations for other aspects of
+C formatting style, which is also the default style of the @code{indent}
+program in version 1.2 and newer. It corresponds to the options
+
+ at smallexample
+-nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2
+-ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob
+ at end smallexample
+
+We don't think of these recommendations as requirements, because it
+causes no problems for users if two different programs have different
+formatting styles.
+
+But whatever style you use, please use it consistently, since a mixture
+of styles within one program tends to look ugly. If you are
+contributing changes to an existing program, please follow the style of
+that program.
+
+For the body of the function, our recommended style looks like this:
+
+ at example
+if (x < foo (y, z))
+ haha = bar[4] + 5;
+else
+ @{
+ while (z)
+ @{
+ haha += foo (z, z);
+ z--;
+ @}
+ return ++x + bar ();
+ @}
+ at end example
+
+ at cindex spaces before open-paren
+We find it easier to read a program when it has spaces before the
+open-parentheses and after the commas. Especially after the commas.
+
+When you split an expression into multiple lines, split it
+before an operator, not after one. Here is the right way:
+
+ at cindex expressions, splitting
+ at example
+if (foo_this_is_long && bar > win (x, y, z)
+ && remaining_condition)
+ at end example
+
+Try to avoid having two operators of different precedence at the same
+level of indentation. For example, don't write this:
+
+ at example
+mode = (inmode[j] == VOIDmode
+ || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
+ ? outmode[j] : inmode[j]);
+ at end example
+
+Instead, use extra parentheses so that the indentation shows the nesting:
+
+ at example
+mode = ((inmode[j] == VOIDmode
+ || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
+ ? outmode[j] : inmode[j]);
+ at end example
+
+Insert extra parentheses so that Emacs will indent the code properly.
+For example, the following indentation looks nice if you do it by hand,
+
+ at example
+v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
+ + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
+ at end example
+
+ at noindent
+but Emacs would alter it. Adding a set of parentheses produces
+something that looks equally nice, and which Emacs will preserve:
+
+ at example
+v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
+ + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
+ at end example
+
+Format do-while statements like this:
+
+ at example
+do
+ @{
+ a = foo (a);
+ @}
+while (a > 0);
+ at end example
+
+ at cindex formfeed
+ at cindex control-L
+Please use formfeed characters (control-L) to divide the program into
+pages at logical places (but not within a function). It does not matter
+just how long the pages are, since they do not have to fit on a printed
+page. The formfeeds should appear alone on lines by themselves.
+
+ at node Comments
+ at section Commenting Your Work
+ at cindex commenting
+
+Every program should start with a comment saying briefly what it is for.
+Example: @samp{fmt - filter for simple filling of text}. This comment
+should be at the top of the source file containing the @samp{main}
+function of the program.
+
+Also, please write a brief comment at the start of each source file,
+with the file name and a line or two about the overall purpose of the
+file.
+
+Please write the comments in a GNU program in English, because English
+is the one language that nearly all programmers in all countries can
+read. If you do not write English well, please write comments in
+English as well as you can, then ask other people to help rewrite them.
+If you can't write comments in English, please find someone to work with
+you and translate your comments into English.
+
+Please put a comment on each function saying what the function does,
+what sorts of arguments it gets, and what the possible values of
+arguments mean and are used for. It is not necessary to duplicate in
+words the meaning of the C argument declarations, if a C type is being
+used in its customary fashion. If there is anything nonstandard about
+its use (such as an argument of type @code{char *} which is really the
+address of the second character of a string, not the first), or any
+possible values that would not work the way one would expect (such as,
+that strings containing newlines are not guaranteed to work), be sure
+to say so.
+
+Also explain the significance of the return value, if there is one.
+
+Please put two spaces after the end of a sentence in your comments, so
+that the Emacs sentence commands will work. Also, please write
+complete sentences and capitalize the first word. If a lower-case
+identifier comes at the beginning of a sentence, don't capitalize it!
+Changing the spelling makes it a different identifier. If you don't
+like starting a sentence with a lower case letter, write the sentence
+differently (e.g., ``The identifier lower-case is @dots{}'').
+
+The comment on a function is much clearer if you use the argument
+names to speak about the argument values. The variable name itself
+should be lower case, but write it in upper case when you are speaking
+about the value rather than the variable itself. Thus, ``the inode
+number NODE_NUM'' rather than ``an inode''.
+
+There is usually no purpose in restating the name of the function in
+the comment before it, because readers can see that for themselves.
+There might be an exception when the comment is so long that the function
+itself would be off the bottom of the screen.
+
+There should be a comment on each static variable as well, like this:
+
+ at example
+/* Nonzero means truncate lines in the display;
+ zero means continue them. */
+int truncate_lines;
+ at end example
+
+ at cindex conditionals, comments for
+ at cindex @code{#endif}, commenting
+Every @samp{#endif} should have a comment, except in the case of short
+conditionals (just a few lines) that are not nested. The comment should
+state the condition of the conditional that is ending, @emph{including
+its sense}. @samp{#else} should have a comment describing the condition
+ at emph{and sense} of the code that follows. For example:
+
+ at example
+ at group
+#ifdef foo
+ @dots{}
+#else /* not foo */
+ @dots{}
+#endif /* not foo */
+ at end group
+ at group
+#ifdef foo
+ @dots{}
+#endif /* foo */
+ at end group
+ at end example
+
+ at noindent
+but, by contrast, write the comments this way for a @samp{#ifndef}:
+
+ at example
+ at group
+#ifndef foo
+ @dots{}
+#else /* foo */
+ @dots{}
+#endif /* foo */
+ at end group
+ at group
+#ifndef foo
+ @dots{}
+#endif /* not foo */
+ at end group
+ at end example
+
+ at node Syntactic Conventions
+ at section Clean Use of C Constructs
+ at cindex syntactic conventions
+
+ at cindex implicit @code{int}
+ at cindex function argument, declaring
+Please explicitly declare the types of all objects. For example, you
+should explicitly declare all arguments to functions, and you should
+declare functions to return @code{int} rather than omitting the
+ at code{int}.
+
+ at cindex compiler warnings
+ at cindex @samp{-Wall} compiler option
+Some programmers like to use the GCC @samp{-Wall} option, and change the
+code whenever it issues a warning. If you want to do this, then do.
+Other programmers prefer not to use @samp{-Wall}, because it gives
+warnings for valid and legitimate code which they do not want to change.
+If you want to do this, then do. The compiler should be your servant,
+not your master.
+
+ at pindex clang
+ at pindex lint
+Don't make the program ugly just to placate static analysis tools such
+as @command{lint}, @command{clang}, and GCC with extra warnings
+options such as @option{-Wconversion} and @option{-Wundef}. These
+tools can help find bugs and unclear code, but they can also generate
+so many false alarms that it hurts readability to silence them with
+unnecessary casts, wrappers, and other complications. For example,
+please don't insert casts to @code{void} or calls to do-nothing
+functions merely to pacify a lint checker.
+
+Declarations of external functions and functions to appear later in the
+source file should all go in one place near the beginning of the file
+(somewhere before the first function definition in the file), or else
+should go in a header file. Don't put @code{extern} declarations inside
+functions.
+
+ at cindex temporary variables
+It used to be common practice to use the same local variables (with
+names like @code{tem}) over and over for different values within one
+function. Instead of doing this, it is better to declare a separate local
+variable for each distinct purpose, and give it a name which is
+meaningful. This not only makes programs easier to understand, it also
+facilitates optimization by good compilers. You can also move the
+declaration of each local variable into the smallest scope that includes
+all its uses. This makes the program even cleaner.
+
+Don't use local variables or parameters that shadow global identifiers.
+GCC's @samp{-Wshadow} option can detect this problem.
+
+ at cindex multiple variables in a line
+Don't declare multiple variables in one declaration that spans lines.
+Start a new declaration on each line, instead. For example, instead
+of this:
+
+ at example
+ at group
+int foo,
+ bar;
+ at end group
+ at end example
+
+ at noindent
+write either this:
+
+ at example
+int foo, bar;
+ at end example
+
+ at noindent
+or this:
+
+ at example
+int foo;
+int bar;
+ at end example
+
+ at noindent
+(If they are global variables, each should have a comment preceding it
+anyway.)
+
+When you have an @code{if}- at code{else} statement nested in another
+ at code{if} statement, always put braces around the @code{if}- at code{else}.
+Thus, never write like this:
+
+ at example
+if (foo)
+ if (bar)
+ win ();
+ else
+ lose ();
+ at end example
+
+ at noindent
+always like this:
+
+ at example
+if (foo)
+ @{
+ if (bar)
+ win ();
+ else
+ lose ();
+ @}
+ at end example
+
+If you have an @code{if} statement nested inside of an @code{else}
+statement, either write @code{else if} on one line, like this,
+
+ at example
+if (foo)
+ @dots{}
+else if (bar)
+ @dots{}
+ at end example
+
+ at noindent
+with its @code{then}-part indented like the preceding @code{then}-part,
+or write the nested @code{if} within braces like this:
+
+ at example
+if (foo)
+ @dots{}
+else
+ @{
+ if (bar)
+ @dots{}
+ @}
+ at end example
+
+Don't declare both a structure tag and variables or typedefs in the
+same declaration. Instead, declare the structure tag separately
+and then use it to declare the variables or typedefs.
+
+Try to avoid assignments inside @code{if}-conditions (assignments
+inside @code{while}-conditions are ok). For example, don't write
+this:
+
+ at example
+if ((foo = (char *) malloc (sizeof *foo)) == 0)
+ fatal ("virtual memory exhausted");
+ at end example
+
+ at noindent
+instead, write this:
+
+ at example
+foo = (char *) malloc (sizeof *foo);
+if (foo == 0)
+ fatal ("virtual memory exhausted");
+ at end example
+
+This example uses zero without a cast as a null pointer constant.
+This is perfectly fine, except that a cast is needed when calling a
+varargs function or when using @code{sizeof}.
+
+ at node Names
+ at section Naming Variables, Functions, and Files
+
+ at cindex names of variables, functions, and files
+The names of global variables and functions in a program serve as
+comments of a sort. So don't choose terse names---instead, look for
+names that give useful information about the meaning of the variable or
+function. In a GNU program, names should be English, like other
+comments.
+
+Local variable names can be shorter, because they are used only within
+one context, where (presumably) comments explain their purpose.
+
+Try to limit your use of abbreviations in symbol names. It is ok to
+make a few abbreviations, explain what they mean, and then use them
+frequently, but don't use lots of obscure abbreviations.
+
+Please use underscores to separate words in a name, so that the Emacs
+word commands can be useful within them. Stick to lower case; reserve
+upper case for macros and @code{enum} constants, and for name-prefixes
+that follow a uniform convention.
+
+For example, you should use names like @code{ignore_space_change_flag};
+don't use names like @code{iCantReadThis}.
+
+Variables that indicate whether command-line options have been
+specified should be named after the meaning of the option, not after
+the option-letter. A comment should state both the exact meaning of
+the option and its letter. For example,
+
+ at example
+ at group
+/* Ignore changes in horizontal whitespace (-b). */
+int ignore_space_change_flag;
+ at end group
+ at end example
+
+When you want to define names with constant integer values, use
+ at code{enum} rather than @samp{#define}. GDB knows about enumeration
+constants.
+
+ at cindex file-name limitations
+ at pindex doschk
+You might want to make sure that none of the file names would conflict
+if the files were loaded onto an MS-DOS file system which shortens the
+names. You can use the program @code{doschk} to test for this.
+
+Some GNU programs were designed to limit themselves to file names of 14
+characters or less, to avoid file name conflicts if they are read into
+older System V systems. Please preserve this feature in the existing
+GNU programs that have it, but there is no need to do this in new GNU
+programs. @code{doschk} also reports file names longer than 14
+characters.
+
+
+ at node System Portability
+ at section Portability between System Types
+ at cindex portability, between system types
+
+In the Unix world, ``portability'' refers to porting to different Unix
+versions. For a GNU program, this kind of portability is desirable, but
+not paramount.
+
+The primary purpose of GNU software is to run on top of the GNU kernel,
+compiled with the GNU C compiler, on various types of @sc{cpu}. So the
+kinds of portability that are absolutely necessary are quite limited.
+But it is important to support Linux-based GNU systems, since they
+are the form of GNU that is popular.
+
+Beyond that, it is good to support the other free operating systems
+(*BSD), and it is nice to support other Unix-like systems if you want
+to. Supporting a variety of Unix-like systems is desirable, although
+not paramount. It is usually not too hard, so you may as well do it.
+But you don't have to consider it an obligation, if it does turn out to
+be hard.
+
+ at pindex autoconf
+The easiest way to achieve portability to most Unix-like systems is to
+use Autoconf. It's unlikely that your program needs to know more
+information about the host platform than Autoconf can provide, simply
+because most of the programs that need such knowledge have already been
+written.
+
+Avoid using the format of semi-internal data bases (e.g., directories)
+when there is a higher-level alternative (@code{readdir}).
+
+ at cindex non- at sc{posix} systems, and portability
+As for systems that are not like Unix, such as MSDOS, Windows, VMS, MVS,
+and older Macintosh systems, supporting them is often a lot of work.
+When that is the case, it is better to spend your time adding features
+that will be useful on GNU and GNU/Linux, rather than on supporting
+other incompatible systems.
+
+If you do support Windows, please do not abbreviate it as ``win''. In
+hacker terminology, calling something a ``win'' is a form of praise.
+You're free to praise Microsoft Windows on your own if you want, but
+please don't do this in GNU packages. Instead of abbreviating
+``Windows'' to ``win'', you can write it in full or abbreviate it to
+``woe'' or ``w''. In GNU Emacs, for instance, we use @samp{w32} in
+file names of Windows-specific files, but the macro for Windows
+conditionals is called @code{WINDOWSNT}.
+
+It is a good idea to define the ``feature test macro''
+ at code{_GNU_SOURCE} when compiling your C files. When you compile on GNU
+or GNU/Linux, this will enable the declarations of GNU library extension
+functions, and that will usually give you a compiler error message if
+you define the same function names in some other way in your program.
+(You don't have to actually @emph{use} these functions, if you prefer
+to make the program more portable to other systems.)
+
+But whether or not you use these GNU extensions, you should avoid
+using their names for any other meanings. Doing so would make it hard
+to move your code into other GNU programs.
+
+ at node CPU Portability
+ at section Portability between @sc{cpu}s
+
+ at cindex data types, and portability
+ at cindex portability, and data types
+Even GNU systems will differ because of differences among @sc{cpu}
+types---for example, difference in byte ordering and alignment
+requirements. It is absolutely essential to handle these differences.
+However, don't make any effort to cater to the possibility that an
+ at code{int} will be less than 32 bits. We don't support 16-bit machines
+in GNU.
+
+Similarly, don't make any effort to cater to the possibility that
+ at code{long} will be smaller than predefined types like @code{size_t}.
+For example, the following code is ok:
+
+ at example
+printf ("size = %lu\n", (unsigned long) sizeof array);
+printf ("diff = %ld\n", (long) (pointer2 - pointer1));
+ at end example
+
+1989 Standard C requires this to work, and we know of only one
+counterexample: 64-bit programs on Microsoft Windows. We will leave
+it to those who want to port GNU programs to that environment to
+figure out how to do it.
+
+Predefined file-size types like @code{off_t} are an exception: they are
+longer than @code{long} on many platforms, so code like the above won't
+work with them. One way to print an @code{off_t} value portably is to
+print its digits yourself, one by one.
+
+Don't assume that the address of an @code{int} object is also the
+address of its least-significant byte. This is false on big-endian
+machines. Thus, don't make the following mistake:
+
+ at example
+int c;
+ at dots{}
+while ((c = getchar ()) != EOF)
+ write (file_descriptor, &c, 1);
+ at end example
+
+ at noindent Instead, use @code{unsigned char} as follows. (The @code{unsigned}
+is for portability to unusual systems where @code{char} is signed and
+where there is integer overflow checking.)
+
+ at example
+int c;
+while ((c = getchar ()) != EOF)
+ @{
+ unsigned char u = c;
+ write (file_descriptor, &u, 1);
+ @}
+ at end example
+
+ at cindex casting pointers to integers
+Avoid casting pointers to integers if you can. Such casts greatly
+reduce portability, and in most programs they are easy to avoid. In the
+cases where casting pointers to integers is essential---such as, a Lisp
+interpreter which stores type information as well as an address in one
+word---you'll have to make explicit provisions to handle different word
+sizes. You will also need to make provision for systems in which the
+normal range of addresses you can get from @code{malloc} starts far away
+from zero.
+
+
+ at node System Functions
+ at section Calling System Functions
+
+ at cindex C library functions, and portability
+ at cindex POSIX functions, and portability
+ at cindex library functions, and portability
+ at cindex portability, and library functions
+
+Historically, C implementations differed substantially, and many
+systems lacked a full implementation of ANSI/ISO C89. Nowadays,
+however, very few systems lack a C89 compiler and GNU C supports
+almost all of C99. Similarly, most systems implement POSIX.1-1993
+libraries and tools, and many have POSIX.1-2001.
+
+Hence, there is little reason to support old C or non-POSIX systems,
+and you may want to take advantage of C99 and POSIX-1.2001 to write
+clearer, more portable, or faster code. You should use standard
+interfaces where possible; but if GNU extensions make your program
+more maintainable, powerful, or otherwise better, don't hesitate to
+use them. In any case, don't make your own declaration of system
+functions; that's a recipe for conflict.
+
+Despite the standards, nearly every library function has some sort of
+portability issue on some system or another. Here are some examples:
+
+ at table @code
+ at item open
+Names with trailing @code{/}'s are mishandled on many platforms.
+
+ at item printf
+ at code{long double} may be unimplemented; floating values Infinity and
+NaN are often mishandled; output for large precisions may be
+incorrect.
+
+ at item readlink
+May return @code{int} instead of @code{ssize_t}.
+
+ at item scanf
+On Windows, @code{errno} is not set on failure.
+ at end table
+
+ at cindex Gnulib
+ at uref{http://www.gnu.org/software/gnulib/, Gnulib} is a big help in
+this regard. Gnulib provides implementations of standard interfaces
+on many of the systems that lack them, including portable
+implementations of enhanced GNU interfaces, thereby making their use
+portable, and of POSIX-1.2008 interfaces, some of which are missing
+even on up-to-date GNU systems.
+
+ at findex xmalloc, in Gnulib
+ at findex error messages, in Gnulib
+ at findex data structures, in Gnulib
+Gnulib also provides many useful non-standard interfaces; for example,
+C implementations of standard data structures (hash tables, binary
+trees), error-checking type-safe wrappers for memory allocation
+functions (@code{xmalloc}, @code{xrealloc}), and output of error
+messages.
+
+Gnulib integrates with GNU Autoconf and Automake to remove much of the
+burden of writing portable code from the programmer: Gnulib makes your
+configure script automatically determine what features are missing and
+use the Gnulib code to supply the missing pieces.
+
+The Gnulib and Autoconf manuals have extensive sections on
+portability: @ref{Top,, Introduction, gnulib, Gnulib} and
+ at pxref{Portable C and C++,,, autoconf, Autoconf}. Please consult them
+for many more details.
+
+
+ at node Internationalization
+ at section Internationalization
+ at cindex internationalization
+
+ at pindex gettext
+GNU has a library called GNU gettext that makes it easy to translate the
+messages in a program into various languages. You should use this
+library in every program. Use English for the messages as they appear
+in the program, and let gettext provide the way to translate them into
+other languages.
+
+Using GNU gettext involves putting a call to the @code{gettext} macro
+around each string that might need translation---like this:
+
+ at example
+printf (gettext ("Processing file '%s'..."), file);
+ at end example
+
+ at noindent
+This permits GNU gettext to replace the string @code{"Processing file
+'%s'..."} with a translated version.
+
+Once a program uses gettext, please make a point of writing calls to
+ at code{gettext} when you add new strings that call for translation.
+
+Using GNU gettext in a package involves specifying a @dfn{text domain
+name} for the package. The text domain name is used to separate the
+translations for this package from the translations for other packages.
+Normally, the text domain name should be the same as the name of the
+package---for example, @samp{coreutils} for the GNU core utilities.
+
+ at cindex message text, and internationalization
+To enable gettext to work well, avoid writing code that makes
+assumptions about the structure of words or sentences. When you want
+the precise text of a sentence to vary depending on the data, use two or
+more alternative string constants each containing a complete sentences,
+rather than inserting conditionalized words or phrases into a single
+sentence framework.
+
+Here is an example of what not to do:
+
+ at smallexample
+printf ("%s is full", capacity > 5000000 ? "disk" : "floppy disk");
+ at end smallexample
+
+If you apply gettext to all strings, like this,
+
+ at smallexample
+printf (gettext ("%s is full"),
+ capacity > 5000000 ? gettext ("disk") : gettext ("floppy disk"));
+ at end smallexample
+
+ at noindent
+the translator will hardly know that "disk" and "floppy disk" are meant to
+be substituted in the other string. Worse, in some languages (like French)
+the construction will not work: the translation of the word "full" depends
+on the gender of the first part of the sentence; it happens to be not the
+same for "disk" as for "floppy disk".
+
+Complete sentences can be translated without problems:
+
+ at example
+printf (capacity > 5000000 ? gettext ("disk is full")
+ : gettext ("floppy disk is full"));
+ at end example
+
+A similar problem appears at the level of sentence structure with this
+code:
+
+ at example
+printf ("# Implicit rule search has%s been done.\n",
+ f->tried_implicit ? "" : " not");
+ at end example
+
+ at noindent
+Adding @code{gettext} calls to this code cannot give correct results for
+all languages, because negation in some languages requires adding words
+at more than one place in the sentence. By contrast, adding
+ at code{gettext} calls does the job straightforwardly if the code starts
+out like this:
+
+ at example
+printf (f->tried_implicit
+ ? "# Implicit rule search has been done.\n",
+ : "# Implicit rule search has not been done.\n");
+ at end example
+
+Another example is this one:
+
+ at example
+printf ("%d file%s processed", nfiles,
+ nfiles != 1 ? "s" : "");
+ at end example
+
+ at noindent
+The problem with this example is that it assumes that plurals are made
+by adding `s'. If you apply gettext to the format string, like this,
+
+ at example
+printf (gettext ("%d file%s processed"), nfiles,
+ nfiles != 1 ? "s" : "");
+ at end example
+
+ at noindent
+the message can use different words, but it will still be forced to use
+`s' for the plural. Here is a better way, with gettext being applied to
+the two strings independently:
+
+ at example
+printf ((nfiles != 1 ? gettext ("%d files processed")
+ : gettext ("%d file processed")),
+ nfiles);
+ at end example
+
+ at noindent
+But this still doesn't work for languages like Polish, which has three
+plural forms: one for nfiles == 1, one for nfiles == 2, 3, 4, 22, 23, 24, ...
+and one for the rest. The GNU @code{ngettext} function solves this problem:
+
+ at example
+printf (ngettext ("%d files processed", "%d file processed", nfiles),
+ nfiles);
+ at end example
+
+
+ at node Character Set
+ at section Character Set
+ at cindex character set
+ at cindex encodings
+ at cindex ASCII characters
+ at cindex non-ASCII characters
+
+Sticking to the ASCII character set (plain text, 7-bit characters) is
+preferred in GNU source code comments, text documents, and other
+contexts, unless there is good reason to do something else because of
+the application domain. For example, if source code deals with the
+French Revolutionary calendar, it is OK if its literal strings contain
+accented characters in month names like ``Flor@'eal''. Also, it is OK
+(but not required) to use non-ASCII characters to represent proper
+names of contributors in change logs (@pxref{Change Logs}).
+
+If you need to use non-ASCII characters, you should normally stick
+with one encoding, certainly within a single file. UTF-8 is likely to
+be the best choice.
+
+
+ at node Quote Characters
+ at section Quote Characters
+ at cindex quote characters
+ at cindex locale-specific quote characters
+ at cindex left quote
+ at cindex right quote
+ at cindex opening quote
+ at cindex single quote
+ at cindex double quote
+ at cindex grave accent
+ at set txicodequoteundirected
+ at set txicodequotebacktick
+
+In the C locale, the output of GNU programs should stick to plain
+ASCII for quotation characters in messages to users: preferably 0x22
+(@samp{"}) or 0x27 (@samp{'}) for both opening and closing quotes.
+Although GNU programs traditionally used 0x60 (@samp{`}) for opening
+and 0x27 (@samp{'}) for closing quotes, nowadays quotes @samp{`like
+this'} are typically rendered asymmetrically, so quoting @samp{"like
+this"} or @samp{'like this'} typically looks better.
+
+It is ok, but not required, for GNU programs to generate
+locale-specific quotes in non-C locales. For example:
+
+ at example
+printf (gettext ("Processing file '%s'..."), file);
+ at end example
+
+ at noindent
+Here, a French translation might cause @code{gettext} to return the
+string @code{"Traitement de fichier
+ at guilsinglleft{}@tie{}%s at tie{}@guilsinglright{}..."}, yielding quotes
+more appropriate for a French locale.
+
+Sometimes a program may need to use opening and closing quotes
+directly. By convention, @code{gettext} translates the string
+ at samp{"`"} to the opening quote and the string @samp{"'"} to the
+closing quote, and a program can use these translations. Generally,
+though, it is better to translate quote characters in the context of
+longer strings.
+
+If the output of your program is ever likely to be parsed by another
+program, it is good to provide an option that makes this parsing
+reliable. For example, you could escape special characters using
+conventions from the C language or the Bourne shell. See for example
+the option @option{--quoting-style} of GNU @code{ls}.
+
+ at clear txicodequoteundirected
+ at clear txicodequotebacktick
+
+
+ at node Mmap
+ at section Mmap
+ at findex mmap
+
+Don't assume that @code{mmap} either works on all files or fails
+for all files. It may work on some files and fail on others.
+
+The proper way to use @code{mmap} is to try it on the specific file for
+which you want to use it---and if @code{mmap} doesn't work, fall back on
+doing the job in another way using @code{read} and @code{write}.
+
+The reason this precaution is needed is that the GNU kernel (the HURD)
+provides a user-extensible file system, in which there can be many
+different kinds of ``ordinary files''. Many of them support
+ at code{mmap}, but some do not. It is important to make programs handle
+all these kinds of files.
+
+
+ at node Documentation
+ at chapter Documenting Programs
+ at cindex documentation
+
+A GNU program should ideally come with full free documentation, adequate
+for both reference and tutorial purposes. If the package can be
+programmed or extended, the documentation should cover programming or
+extending it, as well as just using it.
+
+ at menu
+* GNU Manuals:: Writing proper manuals.
+* Doc Strings and Manuals:: Compiling doc strings doesn't make a manual.
+* Manual Structure Details:: Specific structure conventions.
+* License for Manuals:: Writing the distribution terms for a manual.
+* Manual Credits:: Giving credit to documentation contributors.
+* Printed Manuals:: Mentioning the printed manual.
+* NEWS File:: NEWS files supplement manuals.
+* Change Logs:: Recording changes.
+* Man Pages:: Man pages are secondary.
+* Reading other Manuals:: How far you can go in learning
+ from other manuals.
+ at end menu
+
+ at node GNU Manuals
+ at section GNU Manuals
+
+The preferred document format for the GNU system is the Texinfo
+formatting language. Every GNU package should (ideally) have
+documentation in Texinfo both for reference and for learners. Texinfo
+makes it possible to produce a good quality formatted book, using
+ at TeX{}, and to generate an Info file. It is also possible to generate
+HTML output from Texinfo source. See the Texinfo manual, either the
+hardcopy, or the on-line version available through @code{info} or the
+Emacs Info subsystem (@kbd{C-h i}).
+
+Nowadays some other formats such as Docbook and Sgmltexi can be
+converted automatically into Texinfo. It is ok to produce the Texinfo
+documentation by conversion this way, as long as it gives good results.
+
+Make sure your manual is clear to a reader who knows nothing about the
+topic and reads it straight through. This means covering basic topics
+at the beginning, and advanced topics only later. This also means
+defining every specialized term when it is first used.
+
+Programmers tend to carry over the structure of the program as the
+structure for its documentation. But this structure is not
+necessarily good for explaining how to use the program; it may be
+irrelevant and confusing for a user.
+
+Instead, the right way to structure documentation is according to the
+concepts and questions that a user will have in mind when reading it.
+This principle applies at every level, from the lowest (ordering
+sentences in a paragraph) to the highest (ordering of chapter topics
+within the manual). Sometimes this structure of ideas matches the
+structure of the implementation of the software being documented---but
+often they are different. An important part of learning to write good
+documentation is to learn to notice when you have unthinkingly
+structured the documentation like the implementation, stop yourself,
+and look for better alternatives.
+
+For example, each program in the GNU system probably ought to be
+documented in one manual; but this does not mean each program should
+have its own manual. That would be following the structure of the
+implementation, rather than the structure that helps the user
+understand.
+
+Instead, each manual should cover a coherent @emph{topic}. For example,
+instead of a manual for @code{diff} and a manual for @code{diff3}, we
+have one manual for ``comparison of files'' which covers both of those
+programs, as well as @code{cmp}. By documenting these programs
+together, we can make the whole subject clearer.
+
+The manual which discusses a program should certainly document all of
+the program's command-line options and all of its commands. It should
+give examples of their use. But don't organize the manual as a list
+of features. Instead, organize it logically, by subtopics. Address
+the questions that a user will ask when thinking about the job that
+the program does. Don't just tell the reader what each feature can
+do---say what jobs it is good for, and show how to use it for those
+jobs. Explain what is recommended usage, and what kinds of usage
+users should avoid.
+
+In general, a GNU manual should serve both as tutorial and reference.
+It should be set up for convenient access to each topic through Info,
+and for reading straight through (appendixes aside). A GNU manual
+should give a good introduction to a beginner reading through from the
+start, and should also provide all the details that hackers want.
+The Bison manual is a good example of this---please take a look at it
+to see what we mean.
+
+That is not as hard as it first sounds. Arrange each chapter as a
+logical breakdown of its topic, but order the sections, and write their
+text, so that reading the chapter straight through makes sense. Do
+likewise when structuring the book into chapters, and when structuring a
+section into paragraphs. The watchword is, @emph{at each point, address
+the most fundamental and important issue raised by the preceding text.}
+
+If necessary, add extra chapters at the beginning of the manual which
+are purely tutorial and cover the basics of the subject. These provide
+the framework for a beginner to understand the rest of the manual. The
+Bison manual provides a good example of how to do this.
+
+To serve as a reference, a manual should have an Index that list all the
+functions, variables, options, and important concepts that are part of
+the program. One combined Index should do for a short manual, but
+sometimes for a complex package it is better to use multiple indices.
+The Texinfo manual includes advice on preparing good index entries, see
+ at ref{Index Entries, , Making Index Entries, texinfo, GNU Texinfo}, and
+see @ref{Indexing Commands, , Defining the Entries of an
+Index, texinfo, GNU Texinfo}.
+
+Don't use Unix man pages as a model for how to write GNU documentation;
+most of them are terse, badly structured, and give inadequate
+explanation of the underlying concepts. (There are, of course, some
+exceptions.) Also, Unix man pages use a particular format which is
+different from what we use in GNU manuals.
+
+Please include an email address in the manual for where to report
+bugs @emph{in the text of the manual}.
+
+Please do not use the term ``pathname'' that is used in Unix
+documentation; use ``file name'' (two words) instead. We use the term
+``path'' only for search paths, which are lists of directory names.
+
+Please do not use the term ``illegal'' to refer to erroneous input to
+a computer program. Please use ``invalid'' for this, and reserve the
+term ``illegal'' for activities prohibited by law.
+
+Please do not write @samp{()} after a function name just to indicate
+it is a function. @code{foo ()} is not a function, it is a function
+call with no arguments.
+
+ at node Doc Strings and Manuals
+ at section Doc Strings and Manuals
+
+Some programming systems, such as Emacs, provide a documentation string
+for each function, command or variable. You may be tempted to write a
+reference manual by compiling the documentation strings and writing a
+little additional text to go around them---but you must not do it. That
+approach is a fundamental mistake. The text of well-written
+documentation strings will be entirely wrong for a manual.
+
+A documentation string needs to stand alone---when it appears on the
+screen, there will be no other text to introduce or explain it.
+Meanwhile, it can be rather informal in style.
+
+The text describing a function or variable in a manual must not stand
+alone; it appears in the context of a section or subsection. Other text
+at the beginning of the section should explain some of the concepts, and
+should often make some general points that apply to several functions or
+variables. The previous descriptions of functions and variables in the
+section will also have given information about the topic. A description
+written to stand alone would repeat some of that information; this
+redundancy looks bad. Meanwhile, the informality that is acceptable in
+a documentation string is totally unacceptable in a manual.
+
+The only good way to use documentation strings in writing a good manual
+is to use them as a source of information for writing good text.
+
+ at node Manual Structure Details
+ at section Manual Structure Details
+ at cindex manual structure
+
+The title page of the manual should state the version of the programs or
+packages documented in the manual. The Top node of the manual should
+also contain this information. If the manual is changing more
+frequently than or independent of the program, also state a version
+number for the manual in both of these places.
+
+Each program documented in the manual should have a node named
+ at samp{@var{program} Invocation} or @samp{Invoking @var{program}}. This
+node (together with its subnodes, if any) should describe the program's
+command line arguments and how to run it (the sort of information people
+would look for in a man page). Start with an @samp{@@example}
+containing a template for all the options and arguments that the program
+uses.
+
+Alternatively, put a menu item in some menu whose item name fits one of
+the above patterns. This identifies the node which that item points to
+as the node for this purpose, regardless of the node's actual name.
+
+The @samp{--usage} feature of the Info reader looks for such a node
+or menu item in order to find the relevant text, so it is essential
+for every Texinfo file to have one.
+
+If one manual describes several programs, it should have such a node for
+each program described in the manual.
+
+ at node License for Manuals
+ at section License for Manuals
+ at cindex license for manuals
+
+Please use the GNU Free Documentation License for all GNU manuals that
+are more than a few pages long. Likewise for a collection of short
+documents---you only need one copy of the GNU FDL for the whole
+collection. For a single short document, you can use a very permissive
+non-copyleft license, to avoid taking up space with a long license.
+
+See @uref{http://www.gnu.org/copyleft/fdl-howto.html} for more explanation
+of how to employ the GFDL.
+
+Note that it is not obligatory to include a copy of the GNU GPL or GNU
+LGPL in a manual whose license is neither the GPL nor the LGPL. It can
+be a good idea to include the program's license in a large manual; in a
+short manual, whose size would be increased considerably by including
+the program's license, it is probably better not to include it.
+
+ at node Manual Credits
+ at section Manual Credits
+ at cindex credits for manuals
+
+Please credit the principal human writers of the manual as the authors,
+on the title page of the manual. If a company sponsored the work, thank
+the company in a suitable place in the manual, but do not cite the
+company as an author.
+
+ at node Printed Manuals
+ at section Printed Manuals
+
+The FSF publishes some GNU manuals in printed form. To encourage sales
+of these manuals, the on-line versions of the manual should mention at
+the very start that the printed manual is available and should point at
+information for getting it---for instance, with a link to the page
+ at url{http://www.gnu.org/order/order.html}. This should not be included
+in the printed manual, though, because there it is redundant.
+
+It is also useful to explain in the on-line forms of the manual how the
+user can print out the manual from the sources.
+
+ at node NEWS File
+ at section The NEWS File
+ at cindex @file{NEWS} file
+
+In addition to its manual, the package should have a file named
+ at file{NEWS} which contains a list of user-visible changes worth
+mentioning. In each new release, add items to the front of the file and
+identify the version they pertain to. Don't discard old items; leave
+them in the file after the newer items. This way, a user upgrading from
+any previous version can see what is new.
+
+If the @file{NEWS} file gets very long, move some of the older items
+into a file named @file{ONEWS} and put a note at the end referring the
+user to that file.
+
+ at node Change Logs
+ at section Change Logs
+ at cindex change logs
+
+Keep a change log to describe all the changes made to program source
+files. The purpose of this is so that people investigating bugs in the
+future will know about the changes that might have introduced the bug.
+Often a new bug can be found by looking at what was recently changed.
+More importantly, change logs can help you eliminate conceptual
+inconsistencies between different parts of a program, by giving you a
+history of how the conflicting concepts arose and who they came from.
+
+ at menu
+* Change Log Concepts::
+* Style of Change Logs::
+* Simple Changes::
+* Conditional Changes::
+* Indicating the Part Changed::
+ at end menu
+
+ at node Change Log Concepts
+ at subsection Change Log Concepts
+
+You can think of the change log as a conceptual ``undo list'' which
+explains how earlier versions were different from the current version.
+People can see the current version; they don't need the change log
+to tell them what is in it. What they want from a change log is a
+clear explanation of how the earlier version differed.
+
+The change log file is normally called @file{ChangeLog} and covers an
+entire directory. Each directory can have its own change log, or a
+directory can use the change log of its parent directory---it's up to
+you.
+
+Another alternative is to record change log information with a version
+control system such as RCS or CVS. This can be converted automatically
+to a @file{ChangeLog} file using @code{rcs2log}; in Emacs, the command
+ at kbd{C-x v a} (@code{vc-update-change-log}) does the job.
+
+There's no need to describe the full purpose of the changes or how
+they work together. However, sometimes it is useful to write one line
+to describe the overall purpose of a change or a batch of changes. If
+you think that a change calls for explanation, you're probably right.
+Please do explain it---but please put the full explanation in comments
+in the code, where people will see it whenever they see the code. For
+example, ``New function'' is enough for the change log when you add a
+function, because there should be a comment before the function
+definition to explain what it does.
+
+In the past, we recommended not mentioning changes in non-software
+files (manuals, help files, etc.) in change logs. However, we've been
+advised that it is a good idea to include them, for the sake of
+copyright records.
+
+The easiest way to add an entry to @file{ChangeLog} is with the Emacs
+command @kbd{M-x add-change-log-entry}. An entry should have an
+asterisk, the name of the changed file, and then in parentheses the name
+of the changed functions, variables or whatever, followed by a colon.
+Then describe the changes you made to that function or variable.
+
+ at node Style of Change Logs
+ at subsection Style of Change Logs
+ at cindex change logs, style
+
+Here are some simple examples of change log entries, starting with the
+header line that says who made the change and when it was installed,
+followed by descriptions of specific changes. (These examples are
+drawn from Emacs and GCC.)
+
+ at example
+1998-08-17 Richard Stallman <rms@@gnu.org>
+
+* register.el (insert-register): Return nil.
+(jump-to-register): Likewise.
+
+* sort.el (sort-subr): Return nil.
+
+* tex-mode.el (tex-bibtex-file, tex-file, tex-region):
+Restart the tex shell if process is gone or stopped.
+(tex-shell-running): New function.
+
+* expr.c (store_one_arg): Round size up for move_block_to_reg.
+(expand_call): Round up when emitting USE insns.
+* stmt.c (assign_parms): Round size up for move_block_from_reg.
+ at end example
+
+It's important to name the changed function or variable in full. Don't
+abbreviate function or variable names, and don't combine them.
+Subsequent maintainers will often search for a function name to find all
+the change log entries that pertain to it; if you abbreviate the name,
+they won't find it when they search.
+
+For example, some people are tempted to abbreviate groups of function
+names by writing @samp{* register.el (@{insert,jump-to@}-register)};
+this is not a good idea, since searching for @code{jump-to-register} or
+ at code{insert-register} would not find that entry.
+
+Separate unrelated change log entries with blank lines. When two
+entries represent parts of the same change, so that they work together,
+then don't put blank lines between them. Then you can omit the file
+name and the asterisk when successive entries are in the same file.
+
+Break long lists of function names by closing continued lines with
+ at samp{)}, rather than @samp{,}, and opening the continuation with
+ at samp{(} as in this example:
+
+ at example
+* keyboard.c (menu_bar_items, tool_bar_items)
+(Fexecute_extended_command): Deal with 'keymap' property.
+ at end example
+
+When you install someone else's changes, put the contributor's name in
+the change log entry rather than in the text of the entry. In other
+words, write this:
+
+ at example
+2002-07-14 John Doe <jdoe@@gnu.org>
+
+ * sewing.c: Make it sew.
+ at end example
+
+ at noindent
+rather than this:
+
+ at example
+2002-07-14 Usual Maintainer <usual@@gnu.org>
+
+ * sewing.c: Make it sew. Patch by jdoe@@gnu.org.
+ at end example
+
+As for the date, that should be the date you applied the change.
+
+ at node Simple Changes
+ at subsection Simple Changes
+
+Certain simple kinds of changes don't need much detail in the change
+log.
+
+When you change the calling sequence of a function in a simple fashion,
+and you change all the callers of the function to use the new calling
+sequence, there is no need to make individual entries for all the
+callers that you changed. Just write in the entry for the function
+being called, ``All callers changed''---like this:
+
+ at example
+* keyboard.c (Fcommand_execute): New arg SPECIAL.
+All callers changed.
+ at end example
+
+When you change just comments or doc strings, it is enough to write an
+entry for the file, without mentioning the functions. Just ``Doc
+fixes'' is enough for the change log.
+
+There's no technical need to make change log entries for documentation
+files. This is because documentation is not susceptible to bugs that
+are hard to fix. Documentation does not consist of parts that must
+interact in a precisely engineered fashion. To correct an error, you
+need not know the history of the erroneous passage; it is enough to
+compare what the documentation says with the way the program actually
+works.
+
+However, you should keep change logs for documentation files when the
+project gets copyright assignments from its contributors, so as to
+make the records of authorship more accurate.
+
+ at node Conditional Changes
+ at subsection Conditional Changes
+ at cindex conditional changes, and change logs
+ at cindex change logs, conditional changes
+
+Source files can often contain code that is conditional to build-time
+or static conditions. For example, C programs can contain
+compile-time @code{#if} conditionals; programs implemented in
+interpreted languages can contain module imports of function
+definitions that are only performed for certain versions of the
+interpreter; and Automake @file{Makefile.am} files can contain
+variable definitions or target declarations that are only to be
+considered if a configure-time Automake conditional is true.
+
+Many changes are conditional as well: sometimes you add a new variable,
+or function, or even a new program or library, which is entirely
+dependent on a build-time condition. It is useful to indicate
+in the change log the conditions for which a change applies.
+
+Our convention for indicating conditional changes is to use
+ at emph{square brackets around the name of the condition}.
+
+Conditional changes can happen in numerous scenarios and with many
+variations, so here are some examples to help clarify. This first
+example describes changes in C, Perl, and Python files which are
+conditional but do not have an associated function or entity name:
+
+ at example
+* xterm.c [SOLARIS2]: Include <string.h>.
+* FilePath.pm [$^O eq 'VMS']: Import the VMS::Feature module.
+* framework.py [sys.version_info < (2, 6)]: Make "with" statement
+ available by importing it from __future__,
+ to support also python 2.5.
+ at end example
+
+Our other examples will for simplicity be limited to C, as the minor
+changes necessary to adapt them to other languages should be
+self-evident.
+
+Next, here is an entry describing a new definition which is entirely
+conditional: the C macro @code{FRAME_WINDOW_P} is defined (and used)
+only when the macro @code{HAVE_X_WINDOWS} is defined:
+
+ at example
+* frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
+ at end example
+
+Next, an entry for a change within the function @code{init_display},
+whose definition as a whole is unconditional, but the changes
+themselves are contained in a @samp{#ifdef HAVE_LIBNCURSES}
+conditional:
+
+ at example
+* dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
+ at end example
+
+Finally, here is an entry for a change that takes effect only when
+a certain macro is @emph{not} defined:
+
+ at example
+(gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
+ at end example
+
+ at node Indicating the Part Changed
+ at subsection Indicating the Part Changed
+
+Indicate the part of a function which changed by using angle brackets
+enclosing an indication of what the changed part does. Here is an entry
+for a change in the part of the function @code{sh-while-getopts} that
+deals with @code{sh} commands:
+
+ at example
+* progmodes/sh-script.el (sh-while-getopts) <sh>: Handle case that
+user-specified option string is empty.
+ at end example
+
+
+ at node Man Pages
+ at section Man Pages
+ at cindex man pages
+
+In the GNU project, man pages are secondary. It is not necessary or
+expected for every GNU program to have a man page, but some of them do.
+It's your choice whether to include a man page in your program.
+
+When you make this decision, consider that supporting a man page
+requires continual effort each time the program is changed. The time
+you spend on the man page is time taken away from more useful work.
+
+For a simple program which changes little, updating the man page may be
+a small job. Then there is little reason not to include a man page, if
+you have one.
+
+For a large program that changes a great deal, updating a man page may
+be a substantial burden. If a user offers to donate a man page, you may
+find this gift costly to accept. It may be better to refuse the man
+page unless the same person agrees to take full responsibility for
+maintaining it---so that you can wash your hands of it entirely. If
+this volunteer later ceases to do the job, then don't feel obliged to
+pick it up yourself; it may be better to withdraw the man page from the
+distribution until someone else agrees to update it.
+
+When a program changes only a little, you may feel that the
+discrepancies are small enough that the man page remains useful without
+updating. If so, put a prominent note near the beginning of the man
+page explaining that you don't maintain it and that the Texinfo manual
+is more authoritative. The note should say how to access the Texinfo
+documentation.
+
+Be sure that man pages include a copyright statement and free license.
+The simple all-permissive license is appropriate for simple man pages
+(@pxref{License Notices for Other Files,,,maintain,Information for GNU
+Maintainers}).
+
+For long man pages, with enough explanation and documentation that
+they can be considered true manuals, use the GFDL (@pxref{License for
+Manuals}).
+
+Finally, the GNU help2man program
+(@uref{http://www.gnu.org/software/help2man/}) is one way to automate
+generation of a man page, in this case from @option{--help} output.
+This is sufficient in many cases.
+
+ at node Reading other Manuals
+ at section Reading other Manuals
+
+There may be non-free books or documentation files that describe the
+program you are documenting.
+
+It is ok to use these documents for reference, just as the author of a
+new algebra textbook can read other books on algebra. A large portion
+of any non-fiction book consists of facts, in this case facts about how
+a certain program works, and these facts are necessarily the same for
+everyone who writes about the subject. But be careful not to copy your
+outline structure, wording, tables or examples from preexisting non-free
+documentation. Copying from free documentation may be ok; please check
+with the FSF about the individual case.
+
+ at node Managing Releases
+ at chapter The Release Process
+ at cindex releasing
+
+Making a release is more than just bundling up your source files in a
+tar file and putting it up for FTP. You should set up your software so
+that it can be configured to run on a variety of systems. Your Makefile
+should conform to the GNU standards described below, and your directory
+layout should also conform to the standards discussed below. Doing so
+makes it easy to include your package into the larger framework of
+all GNU software.
+
+ at menu
+* Configuration:: How configuration of GNU packages should work.
+* Makefile Conventions:: Makefile conventions.
+* Releases:: Making releases
+ at end menu
+
+ at node Configuration
+ at section How Configuration Should Work
+ at cindex program configuration
+
+ at pindex configure
+Each GNU distribution should come with a shell script named
+ at code{configure}. This script is given arguments which describe the
+kind of machine and system you want to compile the program for.
+The @code{configure} script must record the configuration options so
+that they affect compilation.
+
+The description here is the specification of the interface for the
+ at code{configure} script in GNU packages. Many packages implement it
+using GNU Autoconf (@pxref{Top,, Introduction, autoconf, Autoconf})
+and/or GNU Automake (@pxref{Top,, Introduction, automake, Automake}),
+but you do not have to use these tools. You can implement it any way
+you like; for instance, by making @code{configure} be a wrapper around
+a completely different configuration system.
+
+Another way for the @code{configure} script to operate is to make a
+link from a standard name such as @file{config.h} to the proper
+configuration file for the chosen system. If you use this technique,
+the distribution should @emph{not} contain a file named
+ at file{config.h}. This is so that people won't be able to build the
+program without configuring it first.
+
+Another thing that @code{configure} can do is to edit the Makefile. If
+you do this, the distribution should @emph{not} contain a file named
+ at file{Makefile}. Instead, it should include a file @file{Makefile.in} which
+contains the input used for editing. Once again, this is so that people
+won't be able to build the program without configuring it first.
+
+If @code{configure} does write the @file{Makefile}, then @file{Makefile}
+should have a target named @file{Makefile} which causes @code{configure}
+to be rerun, setting up the same configuration that was set up last
+time. The files that @code{configure} reads should be listed as
+dependencies of @file{Makefile}.
+
+All the files which are output from the @code{configure} script should
+have comments at the beginning explaining that they were generated
+automatically using @code{configure}. This is so that users won't think
+of trying to edit them by hand.
+
+The @code{configure} script should write a file named @file{config.status}
+which describes which configuration options were specified when the
+program was last configured. This file should be a shell script which,
+if run, will recreate the same configuration.
+
+The @code{configure} script should accept an option of the form
+ at samp{--srcdir=@var{dirname}} to specify the directory where sources are found
+(if it is not the current directory). This makes it possible to build
+the program in a separate directory, so that the actual source directory
+is not modified.
+
+If the user does not specify @samp{--srcdir}, then @code{configure} should
+check both @file{.} and @file{..} to see if it can find the sources. If
+it finds the sources in one of these places, it should use them from
+there. Otherwise, it should report that it cannot find the sources, and
+should exit with nonzero status.
+
+Usually the easy way to support @samp{--srcdir} is by editing a
+definition of @code{VPATH} into the Makefile. Some rules may need to
+refer explicitly to the specified source directory. To make this
+possible, @code{configure} can add to the Makefile a variable named
+ at code{srcdir} whose value is precisely the specified directory.
+
+In addition, the @samp{configure} script should take options
+corresponding to most of the standard directory variables
+(@pxref{Directory Variables}). Here is the list:
+
+ at example
+--prefix --exec-prefix --bindir --sbindir --libexecdir --sysconfdir
+--sharedstatedir --localstatedir --libdir --includedir --oldincludedir
+--datarootdir --datadir --infodir --localedir --mandir --docdir
+--htmldir --dvidir --pdfdir --psdir
+ at end example
+
+The @code{configure} script should also take an argument which specifies the
+type of system to build the program for. This argument should look like
+this:
+
+ at example
+ at var{cpu}- at var{company}- at var{system}
+ at end example
+
+For example, an Athlon-based GNU/Linux system might be
+ at samp{i686-pc-linux-gnu}.
+
+The @code{configure} script needs to be able to decode all plausible
+alternatives for how to describe a machine. Thus,
+ at samp{athlon-pc-gnu/linux} would be a valid alias. There is a shell
+script called
+ at uref{http://git.savannah.gnu.org/@/gitweb/@/?p=config.git;a=blob_plain;f=config.sub;hb=HEAD,
+ at file{config.sub}} that you can use as a subroutine to validate system
+types and canonicalize aliases.
+
+The @code{configure} script should also take the option
+ at option{--build=@var{buildtype}}, which should be equivalent to a
+plain @var{buildtype} argument. For example, @samp{configure
+--build=i686-pc-linux-gnu} is equivalent to @samp{configure
+i686-pc-linux-gnu}. When the build type is not specified by an option
+or argument, the @code{configure} script should normally guess it using
+the shell script
+ at uref{http://git.savannah.gnu.org/@/gitweb/@/?p=config.git;a=blob_plain;f=config.guess;hb=HEAD,
+ at file{config.guess}}.
+
+ at cindex optional features, configure-time
+Other options are permitted to specify in more detail the software
+or hardware present on the machine, to include or exclude optional parts
+of the package, or to adjust the name of some tools or arguments to them:
+
+ at table @samp
+ at item --enable- at var{feature}@r{[}=@var{parameter}@r{]}
+Configure the package to build and install an optional user-level
+facility called @var{feature}. This allows users to choose which
+optional features to include. Giving an optional @var{parameter} of
+ at samp{no} should omit @var{feature}, if it is built by default.
+
+No @samp{--enable} option should @strong{ever} cause one feature to
+replace another. No @samp{--enable} option should ever substitute one
+useful behavior for another useful behavior. The only proper use for
+ at samp{--enable} is for questions of whether to build part of the program
+or exclude it.
+
+ at item --with- at var{package}
+ at c @r{[}=@var{parameter}@r{]}
+The package @var{package} will be installed, so configure this package
+to work with @var{package}.
+
+ at c Giving an optional @var{parameter} of
+ at c @samp{no} should omit @var{package}, if it is used by default.
+
+Possible values of @var{package} include
+ at samp{gnu-as} (or @samp{gas}), @samp{gnu-ld}, @samp{gnu-libc},
+ at samp{gdb},
+ at samp{x},
+and
+ at samp{x-toolkit}.
+
+Do not use a @samp{--with} option to specify the file name to use to
+find certain files. That is outside the scope of what @samp{--with}
+options are for.
+
+ at item @var{variable}=@var{value}
+Set the value of the variable @var{variable} to @var{value}. This is
+used to override the default values of commands or arguments in the
+build process. For example, the user could issue @samp{configure
+CFLAGS=-g CXXFLAGS=-g} to build with debugging information and without
+the default optimization.
+
+Specifying variables as arguments to @code{configure}, like this:
+ at example
+./configure CC=gcc
+ at end example
+is preferable to setting them in environment variables:
+ at example
+CC=gcc ./configure
+ at end example
+as it helps to recreate the same configuration later with
+ at file{config.status}. However, both methods should be supported.
+ at end table
+
+All @code{configure} scripts should accept all of the ``detail''
+options and the variable settings, whether or not they make any
+difference to the particular package at hand. In particular, they
+should accept any option that starts with @samp{--with-} or
+ at samp{--enable-}. This is so users will be able to configure an
+entire GNU source tree at once with a single set of options.
+
+You will note that the categories @samp{--with-} and @samp{--enable-}
+are narrow: they @strong{do not} provide a place for any sort of option
+you might think of. That is deliberate. We want to limit the possible
+configuration options in GNU software. We do not want GNU programs to
+have idiosyncratic configuration options.
+
+Packages that perform part of the compilation process may support
+cross-compilation. In such a case, the host and target machines for the
+program may be different.
+
+The @code{configure} script should normally treat the specified type of
+system as both the host and the target, thus producing a program which
+works for the same type of machine that it runs on.
+
+To compile a program to run on a host type that differs from the build
+type, use the configure option @option{--host=@var{hosttype}}, where
+ at var{hosttype} uses the same syntax as @var{buildtype}. The host type
+normally defaults to the build type.
+
+To configure a cross-compiler, cross-assembler, or what have you, you
+should specify a target different from the host, using the configure
+option @samp{--target=@var{targettype}}. The syntax for
+ at var{targettype} is the same as for the host type. So the command would
+look like this:
+
+ at example
+./configure --host=@var{hosttype} --target=@var{targettype}
+ at end example
+
+The target type normally defaults to the host type.
+Programs for which cross-operation is not meaningful need not accept the
+ at samp{--target} option, because configuring an entire operating system for
+cross-operation is not a meaningful operation.
+
+Some programs have ways of configuring themselves automatically. If
+your program is set up to do this, your @code{configure} script can simply
+ignore most of its arguments.
+
+ at comment The makefile standards are in a separate file that is also
+ at comment included by make.texinfo. Done by roland at gnu.ai.mit.edu on 1/6/93.
+ at comment For this document, turn chapters into sections, etc.
+ at lowersections
+ at include make-stds.texi
+ at raisesections
+
+ at node Releases
+ at section Making Releases
+ at cindex packaging
+
+You should identify each release with a pair of version numbers, a
+major version and a minor. We have no objection to using more than
+two numbers, but it is very unlikely that you really need them.
+
+Package the distribution of @code{Foo version 69.96} up in a gzipped tar
+file with the name @file{foo-69.96.tar.gz}. It should unpack into a
+subdirectory named @file{foo-69.96}.
+
+Building and installing the program should never modify any of the files
+contained in the distribution. This means that all the files that form
+part of the program in any way must be classified into @dfn{source
+files} and @dfn{non-source files}. Source files are written by humans
+and never changed automatically; non-source files are produced from
+source files by programs under the control of the Makefile.
+
+ at cindex @file{README} file
+The distribution should contain a file named @file{README} which gives
+the name of the package, and a general description of what it does. It
+is also good to explain the purpose of each of the first-level
+subdirectories in the package, if there are any. The @file{README} file
+should either state the version number of the package, or refer to where
+in the package it can be found.
+
+The @file{README} file should refer to the file @file{INSTALL}, which
+should contain an explanation of the installation procedure.
+
+The @file{README} file should also refer to the file which contains the
+copying conditions. The GNU GPL, if used, should be in a file called
+ at file{COPYING}. If the GNU LGPL is used, it should be in a file called
+ at file{COPYING.LESSER}.
+
+Naturally, all the source files must be in the distribution. It is
+okay to include non-source files in the distribution along with the
+source files they are generated from, provided they are up-to-date
+with the source they are made from, and machine-independent, so that
+normal building of the distribution will never modify them. We
+commonly include non-source files produced by Autoconf, Automake,
+Bison, @code{lex}, @TeX{}, and @code{makeinfo}; this helps avoid
+unnecessary dependencies between our distributions, so that users can
+install whichever packages they want to install.
+
+Non-source files that might actually be modified by building and
+installing the program should @strong{never} be included in the
+distribution. So if you do distribute non-source files, always make
+sure they are up to date when you make a new distribution.
+
+Make sure that all the files in the distribution are world-readable, and
+that directories are world-readable and world-searchable (octal mode 755).
+We used to recommend that all directories in the distribution also be
+world-writable (octal mode 777), because ancient versions of @code{tar}
+would otherwise not cope when extracting the archive as an unprivileged
+user. That can easily lead to security issues when creating the archive,
+however, so now we recommend against that.
+
+Don't include any symbolic links in the distribution itself. If the tar
+file contains symbolic links, then people cannot even unpack it on
+systems that don't support symbolic links. Also, don't use multiple
+names for one file in different directories, because certain file
+systems cannot handle this and that prevents unpacking the
+distribution.
+
+Try to make sure that all the file names will be unique on MS-DOS. A
+name on MS-DOS consists of up to 8 characters, optionally followed by a
+period and up to three characters. MS-DOS will truncate extra
+characters both before and after the period. Thus,
+ at file{foobarhacker.c} and @file{foobarhacker.o} are not ambiguous; they
+are truncated to @file{foobarha.c} and @file{foobarha.o}, which are
+distinct.
+
+ at cindex @file{texinfo.tex}, in a distribution
+Include in your distribution a copy of the @file{texinfo.tex} you used
+to test print any @file{*.texinfo} or @file{*.texi} files.
+
+Likewise, if your program uses small GNU software packages like regex,
+getopt, obstack, or termcap, include them in the distribution file.
+Leaving them out would make the distribution file a little smaller at
+the expense of possible inconvenience to a user who doesn't know what
+other files to get.
+
+ at node References
+ at chapter References to Non-Free Software and Documentation
+ at cindex references to non-free material
+
+A GNU program should not recommend, promote, or grant legitimacy to
+the use of any non-free program. Proprietary software is a social and
+ethical problem, and our aim is to put an end to that problem. We
+can't stop some people from writing proprietary programs, or stop
+other people from using them, but we can and should refuse to
+advertise them to new potential customers, or to give the public the
+idea that their existence is ethical.
+
+The GNU definition of free software is found on the GNU web site at
+ at url{http://www.gnu.org/@/philosophy/@/free-sw.html}, and the definition
+of free documentation is found at
+ at url{http://www.gnu.org/@/philosophy/@/free-doc.html}. The terms ``free''
+and ``non-free'', used in this document, refer to those definitions.
+
+A list of important licenses and whether they qualify as free is in
+ at url{http://www.gnu.org/@/licenses/@/license-list.html}. If it is not
+clear whether a license qualifies as free, please ask the GNU Project
+by writing to @email{licensing@@gnu.org}. We will answer, and if the
+license is an important one, we will add it to the list.
+
+When a non-free program or system is well known, you can mention it in
+passing---that is harmless, since users who might want to use it
+probably already know about it. For instance, it is fine to explain
+how to build your package on top of some widely used non-free
+operating system, or how to use it together with some widely used
+non-free program.
+
+However, you should give only the necessary information to help those
+who already use the non-free program to use your program with
+it---don't give, or refer to, any further information about the
+proprietary program, and don't imply that the proprietary program
+enhances your program, or that its existence is in any way a good
+thing. The goal should be that people already using the proprietary
+program will get the advice they need about how to use your free
+program with it, while people who don't already use the proprietary
+program will not see anything likely to lead them to take an interest
+in it.
+
+If a non-free program or system is obscure in your program's domain,
+your program should not mention or support it at all, since doing so
+would tend to popularize the non-free program more than it popularizes
+your program. (You cannot hope to find many additional users for your
+program among the users of Foobar, if the existence of Foobar is not
+generally known among people who might want to use your program.)
+
+Sometimes a program is free software in itself but depends on a
+non-free platform in order to run. For instance, many Java programs
+depend on some non-free Java libraries. To recommend or promote such
+a program is to promote the other programs it needs. This is why we
+are careful about listing Java programs in the Free Software
+Directory: we don't want to promote the non-free Java libraries.
+
+We hope this particular problem with Java will be gone by and by, as
+we replace the remaining non-free standard Java libraries with free
+software, but the general principle will remain the same: don't
+recommend, promote or legitimize programs that depend on non-free
+software to run.
+
+Some free programs strongly encourage the use of non-free software. A
+typical example is @command{mplayer}. It is free software in itself,
+and the free code can handle some kinds of files. However,
+ at command{mplayer} recommends use of non-free codecs for other kinds of
+files, and users that install @command{mplayer} are very likely to
+install those codecs along with it. To recommend @command{mplayer}
+is, in effect, to promote use of the non-free codecs.
+
+Thus, you should not recommend programs that strongly encourage the
+use of non-free software. This is why we do not list
+ at command{mplayer} in the Free Software Directory.
+
+A GNU package should not refer the user to any non-free documentation
+for free software. Free documentation that can be included in free
+operating systems is essential for completing the GNU system, or any
+free operating system, so encouraging it is a priority; to recommend
+use of documentation that we are not allowed to include undermines the
+impetus for the community to produce documentation that we can
+include. So GNU packages should never recommend non-free
+documentation.
+
+By contrast, it is ok to refer to journal articles and textbooks in
+the comments of a program for explanation of how it functions, even
+though they are non-free. This is because we don't include such
+things in the GNU system even if they are free---they are outside the
+scope of what a software distribution needs to include.
+
+Referring to a web site that describes or recommends a non-free
+program is promoting that program, so please do not make links to (or
+mention by name) web sites that contain such material. This policy is
+relevant particularly for the web pages for a GNU package.
+
+Following links from nearly any web site can lead eventually to
+non-free software; this is inherent in the nature of the web. So it
+makes no sense to criticize a site for having such links. As long as
+the site does not itself recommend a non-free program, there is no
+need to consider the question of the sites that it links to for other
+reasons.
+
+Thus, for example, you should not refer to AT&T's web site if that
+recommends AT&T's non-free software packages; you should not refer to
+a site that links to AT&T's site presenting it as a place to get some
+non-free program, because that link recommends and legitimizes the
+non-free program. However, that a site contains a link to AT&T's web
+site for some other purpose (such as long-distance telephone service)
+is not an objection against it.
+
+ at node GNU Free Documentation License
+ at appendix GNU Free Documentation License
+
+ at cindex FDL, GNU Free Documentation License
+ at include fdl.texi
+
+ at node Index
+ at unnumbered Index
+ at printindex cp
+
+ at bye
+
+Local variables:
+eval: (add-hook 'write-file-hooks 'time-stamp)
+time-stamp-start: "@set lastupdate "
+time-stamp-end: "$"
+time-stamp-format: "%:b %:d, %:y"
+compile-command: "cd work.s && make"
+End:
diff --git a/debian/docs/src/autoconf/2.69/version.texi b/debian/docs/src/autoconf/2.69/version.texi
new file mode 100644
index 0000000..b9e94c9
--- /dev/null
+++ b/debian/docs/src/autoconf/2.69/version.texi
@@ -0,0 +1,4 @@
+ at set UPDATED 24 April 2012
+ at set UPDATED-MONTH April 2012
+ at set EDITION 2.69
+ at set VERSION 2.69
diff --git a/debian/docs/src/automake/1.11.5/automake.texi b/debian/docs/src/automake/1.11.5/automake.texi
new file mode 100644
index 0000000..10b605e
--- /dev/null
+++ b/debian/docs/src/automake/1.11.5/automake.texi
@@ -0,0 +1,13615 @@
+\input texinfo @c -*-texinfo-*-
+ at c %**start of header
+ at setfilename automake-1.11.info
+ at settitle automake-1.11
+ at setchapternewpage off
+ at c %**end of header
+
+ at include version.texi
+
+ at c @ovar(ARG, DEFAULT)
+ at c -------------------
+ at c The ARG is an optional argument. To be used for macro arguments in
+ at c their documentation (@defmac).
+ at macro ovar{varname}
+ at r{[}@var{\varname\}@r{]}
+ at end macro
+
+ at set PACKAGE_BUGREPORT bug-automake@@gnu.org
+
+ at copying
+
+This manual is for GNU Automake (version @value{VERSION},
+ at value{UPDATED}), a program that creates GNU standards-compliant
+Makefiles from template files.
+
+Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
+2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012 Free Software
+Foundation, Inc.
+
+ at quotation
+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 no Front-Cover texts,
+and with no Back-Cover Texts. A copy of the license is included in the
+section entitled ``GNU Free Documentation License.''
+
+ at end quotation
+ at end copying
+
+ at dircategory Software development
+ at direntry
+* Automake: (automake-1.11). Making GNU standards-compliant Makefiles.
+ at end direntry
+
+ at dircategory Individual utilities
+ at direntry
+* aclocal-invocation: (automake-1.11)aclocal Invocation. Generating aclocal.m4.
+* automake-invocation: (automake-1.11)automake Invocation. Generating Makefile.in.
+ at end direntry
+
+ at titlepage
+ at title GNU Automake
+ at subtitle For version @value{VERSION}, @value{UPDATED}
+ at author David MacKenzie
+ at author Tom Tromey
+ at author Alexandre Duret-Lutz
+ at page
+ at vskip 0pt plus 1filll
+ at insertcopying
+ at end titlepage
+
+ at contents
+
+ at c We use the following macros to define indices:
+ at c @cindex concepts, and anything that does not fit elsewhere
+ at c @vindex Makefile variables
+ at c @trindex targets
+ at c @acindex Autoconf/Automake/Libtool/M4/... macros
+ at c @opindex tool options
+
+ at c Define an index of configure macros.
+ at defcodeindex ac
+ at c Define an index of options.
+ at defcodeindex op
+ at c Define an index of targets.
+ at defcodeindex tr
+ at c Define an index of commands.
+ at defcodeindex cm
+
+ at c Put the macros in the function index.
+ at syncodeindex ac fn
+
+ at c Put everything else into one index (arbitrarily chosen to be the
+ at c concept index).
+ at syncodeindex op cp
+ at syncodeindex tr cp
+ at syncodeindex cm cp
+
+ at ifnottex
+ at node Top
+ at comment node-name, next, previous, up
+ at top GNU Automake
+
+ at insertcopying
+
+ at menu
+* Introduction:: Automake's purpose
+* Autotools Introduction:: An Introduction to the Autotools
+* Generalities:: General ideas
+* Examples:: Some example packages
+* automake Invocation:: Creating a Makefile.in
+* configure:: Scanning configure.ac, using aclocal
+* Directories:: Declaring subdirectories
+* Programs:: Building programs and libraries
+* Other Objects:: Other derived objects
+* Other GNU Tools:: Other GNU Tools
+* Documentation:: Building documentation
+* Install:: What gets installed
+* Clean:: What gets cleaned
+* Dist:: What goes in a distribution
+* Tests:: Support for test suites
+* Rebuilding:: Automatic rebuilding of Makefile
+* Options:: Changing Automake's behavior
+* Miscellaneous:: Miscellaneous rules
+* Include:: Including extra files in an Automake template
+* Conditionals:: Conditionals
+* Silencing Make:: Obtain less verbose output from @command{make}
+* Gnits:: The effect of @option{--gnu} and @option{--gnits}
+* Cygnus:: The effect of @option{--cygnus} (deprecated, soon to be removed)
+* Not Enough:: When Automake is not Enough
+* Distributing:: Distributing the Makefile.in
+* API Versioning:: About compatibility between Automake versions
+* Upgrading:: Upgrading to a Newer Automake Version
+* FAQ:: Frequently Asked Questions
+* History:: Notes about the history of Automake
+* Copying This Manual:: How to make copies of this manual
+* Indices:: Indices of variables, macros, and concepts
+
+ at detailmenu
+ --- The Detailed Node Listing ---
+
+An Introduction to the Autotools
+
+* GNU Build System:: Introducing the GNU Build System
+* Use Cases:: Use Cases for the GNU Build System
+* Why Autotools:: How Autotools Help
+* Hello World:: A Small Hello World Package
+
+Use Cases for the GNU Build System
+
+* Basic Installation:: Common installation procedure
+* Standard Targets:: A list of standard Makefile targets
+* Standard Directory Variables:: A list of standard directory variables
+* Standard Configuration Variables:: Using configuration variables
+* config.site:: Using a config.site file
+* VPATH Builds:: Parallel build trees
+* Two-Part Install:: Installing data and programs separately
+* Cross-Compilation:: Building for other architectures
+* Renaming:: Renaming programs at install time
+* DESTDIR:: Building binary packages with DESTDIR
+* Preparing Distributions:: Rolling out tarballs
+* Dependency Tracking:: Automatic dependency tracking
+* Nested Packages:: The GNU Build Systems can be nested
+
+A Small Hello World
+
+* Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch
+* amhello's configure.ac Setup Explained::
+* amhello's Makefile.am Setup Explained::
+
+General ideas
+
+* General Operation:: General operation of Automake
+* Strictness:: Standards conformance checking
+* Uniform:: The Uniform Naming Scheme
+* Length Limitations:: Staying below the command line length limit
+* Canonicalization:: How derived variables are named
+* User Variables:: Variables reserved for the user
+* Auxiliary Programs:: Programs automake might require
+
+Some example packages
+
+* Complete:: A simple example, start to finish
+* true:: Building true and false
+
+Scanning @file{configure.ac}, using @command{aclocal}
+
+* Requirements:: Configuration requirements
+* Optional:: Other things Automake recognizes
+* aclocal Invocation:: Auto-generating aclocal.m4
+* Macros:: Autoconf macros supplied with Automake
+
+Auto-generating aclocal.m4
+
+* aclocal Options:: Options supported by aclocal
+* Macro Search Path:: How aclocal finds .m4 files
+* Extending aclocal:: Writing your own aclocal macros
+* Local Macros:: Organizing local macros
+* Serials:: Serial lines in Autoconf macros
+* Future of aclocal:: aclocal's scheduled death
+
+Autoconf macros supplied with Automake
+
+* Public Macros:: Macros that you can use.
+* Obsolete Macros:: Macros that you should stop using.
+* Private Macros:: Macros that you should not use.
+
+Directories
+
+* Subdirectories:: Building subdirectories recursively
+* Conditional Subdirectories:: Conditionally not building directories
+* Alternative:: Subdirectories without recursion
+* Subpackages:: Nesting packages
+
+Conditional Subdirectories
+
+* SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
+* Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
+* Subdirectories with AC_SUBST:: Another way for conditional recursion
+* Unconfigured Subdirectories:: Not even creating a @samp{Makefile}
+
+Building Programs and Libraries
+
+* A Program:: Building a program
+* A Library:: Building a library
+* A Shared Library:: Building a Libtool library
+* Program and Library Variables:: Variables controlling program and
+ library builds
+* Default _SOURCES:: Default source files
+* LIBOBJS:: Special handling for LIBOBJS and ALLOCA
+* Program Variables:: Variables used when building a program
+* Yacc and Lex:: Yacc and Lex support
+* C++ Support:: Compiling C++ sources
+* Objective C Support:: Compiling Objective C sources
+* Unified Parallel C Support:: Compiling Unified Parallel C sources
+* Assembly Support:: Compiling assembly sources
+* Fortran 77 Support:: Compiling Fortran 77 sources
+* Fortran 9x Support:: Compiling Fortran 9x sources
+* Java Support with gcj:: Compiling Java sources using gcj
+* Vala Support:: Compiling Vala sources
+* Support for Other Languages:: Compiling other languages
+* ANSI:: Automatic de-ANSI-fication (deprecated, soon to be removed)
+* Dependencies:: Automatic dependency tracking
+* EXEEXT:: Support for executable extensions
+
+Building a program
+
+* Program Sources:: Defining program sources
+* Linking:: Linking with libraries or extra objects
+* Conditional Sources:: Handling conditional sources
+* Conditional Programs:: Building a program conditionally
+
+Building a Shared Library
+
+* Libtool Concept:: Introducing Libtool
+* Libtool Libraries:: Declaring Libtool Libraries
+* Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
+* Conditional Libtool Sources:: Choosing Library Sources Conditionally
+* Libtool Convenience Libraries:: Building Convenience Libtool Libraries
+* Libtool Modules:: Building Libtool Modules
+* Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
+* LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
+* Libtool Issues:: Common Issues Related to Libtool's Use
+
+Common Issues Related to Libtool's Use
+
+* Error required file ltmain.sh not found:: The need to run libtoolize
+* Objects created both with libtool and without:: Avoid a specific build race
+
+Fortran 77 Support
+
+* Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
+* Compiling Fortran 77 Files:: Compiling Fortran 77 sources
+* Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
+
+Mixing Fortran 77 With C and C++
+
+* How the Linker is Chosen:: Automatic linker selection
+
+Fortran 9x Support
+
+* Compiling Fortran 9x Files:: Compiling Fortran 9x sources
+
+Other Derived Objects
+
+* Scripts:: Executable scripts
+* Headers:: Header files
+* Data:: Architecture-independent data files
+* Sources:: Derived sources
+
+Built Sources
+
+* Built Sources Example:: Several ways to handle built sources.
+
+Other GNU Tools
+
+* Emacs Lisp:: Emacs Lisp
+* gettext:: Gettext
+* Libtool:: Libtool
+* Java:: Java bytecode compilation (deprecated)
+* Python:: Python
+
+Building documentation
+
+* Texinfo:: Texinfo
+* Man Pages:: Man pages
+
+What Gets Installed
+
+* Basics of Installation:: What gets installed where
+* The Two Parts of Install:: Installing data and programs separately
+* Extending Installation:: Adding your own rules for installation
+* Staged Installs:: Installation in a temporary location
+* Install Rules for the User:: Useful additional rules
+
+What Goes in a Distribution
+
+* Basics of Distribution:: Files distributed by default
+* Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes
+* The dist Hook:: A target for last-minute distribution changes
+* Checking the Distribution:: @samp{make distcheck} explained
+* The Types of Distributions:: A variety of formats and compression methods
+
+Support for test suites
+
+* Simple Tests:: Listing programs and scripts in @code{TESTS}
+* Simple Tests using parallel-tests:: More powerful test driver
+* DejaGnu Tests:: Interfacing with the external testing framework
+* Install Tests:: Running tests on installed packages
+
+Miscellaneous Rules
+
+* Tags:: Interfacing to etags and mkid
+* Suffixes:: Handling new file extensions
+* Multilibs:: Support for multilibs (deprecated, soon to be removed).
+
+Conditionals
+
+* Usage of Conditionals:: Declaring conditional content
+* Limits of Conditionals:: Enclosing complete statements
+
+Silencing Make
+
+* Make verbosity:: Make is verbose by default
+* Tricks For Silencing Make:: Standard and generic ways to silence make
+* Automake silent-rules Option:: How Automake can help in silencing make
+
+When Automake Isn't Enough
+
+* Extending:: Adding new rules or overriding existing ones.
+* Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
+
+Frequently Asked Questions about Automake
+
+* CVS:: CVS and generated files
+* maintainer-mode:: missing and AM_MAINTAINER_MODE
+* Wildcards:: Why doesn't Automake support wildcards?
+* Limitations on File Names:: Limitations on source and installed file names
+* distcleancheck:: Files left in build directory after distclean
+* Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
+* Renamed Objects:: Why are object files sometimes renamed?
+* Per-Object Flags:: How to simulate per-object flags?
+* Multiple Outputs:: Writing rules for tools with many output files
+* Hard-Coded Install Paths:: Installing to hard-coded locations
+* Debugging Make Rules:: Strategies when things don't work as expected
+* Reporting Bugs:: Feedback on bugs and feature requests
+
+History of Automake
+
+* Timeline:: The Automake story.
+* Dependency Tracking Evolution:: Evolution of Automatic Dependency Tracking
+* Releases:: Statistics about Automake Releases
+
+Dependency Tracking in Automake
+
+* First Take on Dependencies:: Precomputed dependency tracking
+* Dependencies As Side Effects:: Update at developer compile time
+* Dependencies for the User:: Update at user compile time
+* Techniques for Dependencies:: Alternative approaches
+* Recommendations for Tool Writers:: What tool writers can do to help
+* Future Directions for Dependencies:: Languages Automake does not know
+
+Copying This Manual
+
+* GNU Free Documentation License:: License for copying this manual
+
+Indices
+
+* Macro Index:: Index of Autoconf macros
+* Variable Index:: Index of Makefile variables
+* General Index:: General index
+
+ at end detailmenu
+ at end menu
+
+ at end ifnottex
+
+
+ at node Introduction
+ at chapter Introduction
+
+Automake is a tool for automatically generating @file{Makefile.in}s
+from files called @file{Makefile.am}. Each @file{Makefile.am} is
+basically a series of @command{make} variable
+definitions at footnote{These variables are also called @dfn{make macros}
+in Make terminology, however in this manual we reserve the term
+ at dfn{macro} for Autoconf's macros.}, with rules being thrown in
+occasionally. The generated @file{Makefile.in}s are compliant with
+the GNU Makefile standards.
+
+ at cindex GNU Makefile standards
+
+The GNU Makefile Standards Document
+(@pxref{Makefile Conventions, , , standards, The GNU Coding Standards})
+is long, complicated, and subject to change. The goal of Automake is to
+remove the burden of Makefile maintenance from the back of the
+individual GNU maintainer (and put it on the back of the Automake
+maintainers).
+
+The typical Automake input file is simply a series of variable definitions.
+Each such file is processed to create a @file{Makefile.in}. There
+should generally be one @file{Makefile.am} per directory of a project.
+
+ at cindex Constraints of Automake
+ at cindex Automake constraints
+
+Automake does constrain a project in certain ways; for instance, it
+assumes that the project uses Autoconf (@pxref{Top, , Introduction,
+autoconf, The Autoconf Manual}), and enforces certain restrictions on
+the @file{configure.ac} contents at footnote{Older Autoconf versions used
+ at file{configure.in}. Autoconf 2.50 and greater promotes
+ at file{configure.ac} over @file{configure.in}. The rest of this
+documentation will refer to @file{configure.ac}, but Automake also
+supports @file{configure.in} for backward compatibility.}.
+
+ at cindex Automake requirements
+ at cindex Requirements, Automake
+
+Automake requires @command{perl} in order to generate the
+ at file{Makefile.in}s. However, the distributions created by Automake are
+fully GNU standards-compliant, and do not require @command{perl} in order
+to be built.
+
+ at cindex Bugs, reporting
+ at cindex Reporting bugs
+ at cindex E-mail, bug reports
+
+For more information on bug reports, @xref{Reporting Bugs}.
+
+ at node Autotools Introduction
+ at chapter An Introduction to the Autotools
+
+If you are new to Automake, maybe you know that it is part of a set of
+tools called @emph{The Autotools}. Maybe you've already delved into a
+package full of files named @file{configure}, @file{configure.ac},
+ at file{Makefile.in}, @file{Makefile.am}, @file{aclocal.m4}, @dots{},
+some of them claiming to be @emph{generated by} Autoconf or Automake.
+But the exact purpose of these files and their relations is probably
+fuzzy. The goal of this chapter is to introduce you to this machinery,
+to show you how it works and how powerful it is. If you've never
+installed or seen such a package, do not worry: this chapter will walk
+you through it.
+
+If you need some teaching material, more illustrations, or a less
+ at command{automake}-centered continuation, some slides for this
+introduction are available in Alexandre Duret-Lutz's
+ at uref{http://www.lrde.epita.fr/@/~adl/@/autotools.html,
+Autotools Tutorial}.
+This chapter is the written version of the first part of his tutorial.
+
+ at menu
+* GNU Build System:: Introducing the GNU Build System
+* Use Cases:: Use Cases for the GNU Build System
+* Why Autotools:: How Autotools Help
+* Hello World:: A Small Hello World Package
+ at end menu
+
+ at node GNU Build System
+ at section Introducing the GNU Build System
+ at cindex GNU Build System, introduction
+
+It is a truth universally acknowledged, that as a developer in
+possession of a new package, you must be in want of a build system.
+
+In the Unix world, such a build system is traditionally achieved using
+the command @command{make} (@pxref{Top, , Overview, make, The GNU Make
+Manual}). You express the recipe to build your package in a
+ at file{Makefile}. This file is a set of rules to build the files in
+the package. For instance the program @file{prog} may be built by
+running the linker on the files @file{main.o}, @file{foo.o}, and
+ at file{bar.o}; the file @file{main.o} may be built by running the
+compiler on @file{main.c}; etc. Each time @command{make} is run, it
+reads @file{Makefile}, checks the existence and modification time of
+the files mentioned, decides what files need to be built (or rebuilt),
+and runs the associated commands.
+
+When a package needs to be built on a different platform than the one
+it was developed on, its @file{Makefile} usually needs to be adjusted.
+For instance the compiler may have another name or require more
+options. In 1991, David J. MacKenzie got tired of customizing
+ at file{Makefile} for the 20 platforms he had to deal with. Instead, he
+handcrafted a little shell script called @file{configure} to
+automatically adjust the @file{Makefile} (@pxref{Genesis, , Genesis,
+autoconf, The Autoconf Manual}). Compiling his package was now
+as simple as running @code{./configure && make}.
+
+ at cindex GNU Coding Standards
+
+Today this process has been standardized in the GNU project. The GNU
+Coding Standards (@pxref{Managing Releases, The Release Process, ,
+standards, The GNU Coding Standards}) explains how each package of the
+GNU project should have a @file{configure} script, and the minimal
+interface it should have. The @file{Makefile} too should follow some
+established conventions. The result? A unified build system that
+makes all packages almost indistinguishable by the installer. In its
+simplest scenario, all the installer has to do is to unpack the
+package, run @code{./configure && make && make install}, and repeat
+with the next package to install.
+
+We call this build system the @dfn{GNU Build System}, since it was
+grown out of the GNU project. However it is used by a vast number of
+other packages: following any existing convention has its advantages.
+
+ at cindex Autotools, introduction
+
+The Autotools are tools that will create a GNU Build System for your
+package. Autoconf mostly focuses on @file{configure} and Automake on
+ at file{Makefile}s. It is entirely possible to create a GNU Build
+System without the help of these tools. However it is rather
+burdensome and error-prone. We will discuss this again after some
+illustration of the GNU Build System in action.
+
+ at node Use Cases
+ at section Use Cases for the GNU Build System
+ at cindex GNU Build System, use cases
+ at cindex GNU Build System, features
+ at cindex Features of the GNU Build System
+ at cindex Use Cases for the GNU Build System
+ at cindex @file{amhello-1.0.tar.gz}, location
+ at cindex @file{amhello-1.0.tar.gz}, use cases
+
+In this section we explore several use cases for the GNU Build System.
+You can replay all these examples on the @file{amhello-1.0.tar.gz}
+package distributed with Automake. If Automake is installed on your
+system, you should find a copy of this file in
+ at file{@var{prefix}/share/doc/automake/amhello-1.0.tar.gz}, where
+ at var{prefix} is the installation prefix specified during configuration
+(@var{prefix} defaults to @file{/usr/local}, however if Automake was
+installed by some GNU/Linux distribution it most likely has been set
+to @file{/usr}). If you do not have a copy of Automake installed,
+you can find a copy of this file inside the @file{doc/} directory of
+the Automake package.
+
+Some of the following use cases present features that are in fact
+extensions to the GNU Build System. Read: they are not specified by
+the GNU Coding Standards, but they are nonetheless part of the build
+system created by the Autotools. To keep things simple, we do not
+point out the difference. Our objective is to show you many of the
+features that the build system created by the Autotools will offer to
+you.
+
+ at menu
+* Basic Installation:: Common installation procedure
+* Standard Targets:: A list of standard Makefile targets
+* Standard Directory Variables:: A list of standard directory variables
+* Standard Configuration Variables:: Using configuration variables
+* config.site:: Using a config.site file
+* VPATH Builds:: Parallel build trees
+* Two-Part Install:: Installing data and programs separately
+* Cross-Compilation:: Building for other architectures
+* Renaming:: Renaming programs at install time
+* DESTDIR:: Building binary packages with DESTDIR
+* Preparing Distributions:: Rolling out tarballs
+* Dependency Tracking:: Automatic dependency tracking
+* Nested Packages:: The GNU Build Systems can be nested
+ at end menu
+
+ at node Basic Installation
+ at subsection Basic Installation
+ at cindex Configuration, basics
+ at cindex Installation, basics
+ at cindex GNU Build System, basics
+
+The most common installation procedure looks as follows.
+
+ at example
+~ % @kbd{tar zxf amhello-1.0.tar.gz}
+~ % @kbd{cd amhello-1.0}
+~/amhello-1.0 % @kbd{./configure}
+ at dots{}
+config.status: creating Makefile
+config.status: creating src/Makefile
+ at dots{}
+~/amhello-1.0 % @kbd{make}
+ at dots{}
+~/amhello-1.0 % @kbd{make check}
+ at dots{}
+~/amhello-1.0 % @kbd{su}
+Password:
+/home/adl/amhello-1.0 # @kbd{make install}
+ at dots{}
+/home/adl/amhello-1.0 # @kbd{exit}
+~/amhello-1.0 % @kbd{make installcheck}
+ at dots{}
+ at end example
+
+ at cindex Unpacking
+
+The user first unpacks the package. Here, and in the following
+examples, we will use the non-portable @code{tar zxf} command for
+simplicity. On a system without GNU @command{tar} installed, this
+command should read @code{gunzip -c amhello-1.0.tar.gz | tar xf -}.
+
+The user then enters the newly created directory to run the
+ at file{configure} script. This script probes the system for various
+features, and finally creates the @file{Makefile}s. In this toy
+example there are only two @file{Makefile}s, but in real-world projects,
+there may be many more, usually one @file{Makefile} per directory.
+
+It is now possible to run @code{make}. This will construct all the
+programs, libraries, and scripts that need to be constructed for the
+package. In our example, this compiles the @file{hello} program.
+All files are constructed in place, in the source tree; we will see
+later how this can be changed.
+
+ at code{make check} causes the package's tests to be run. This step is
+not mandatory, but it is often good to make sure the programs that
+have been built behave as they should, before you decide to install
+them. Our example does not contain any tests, so running @code{make
+check} is a no-op.
+
+ at cindex su, before @code{make install}
+After everything has been built, and maybe tested, it is time to
+install it on the system. That means copying the programs,
+libraries, header files, scripts, and other data files from the
+source directory to their final destination on the system. The
+command @code{make install} will do that. However, by default
+everything will be installed in subdirectories of @file{/usr/local}:
+binaries will go into @file{/usr/local/bin}, libraries will end up in
+ at file{/usr/local/lib}, etc. This destination is usually not writable
+by any user, so we assume that we have to become root before we can
+run @code{make install}. In our example, running @code{make install}
+will copy the program @file{hello} into @file{/usr/local/bin}
+and @file{README} into @file{/usr/local/share/doc/amhello}.
+
+A last and optional step is to run @code{make installcheck}. This
+command may run tests on the installed files. @code{make check} tests
+the files in the source tree, while @code{make installcheck} tests
+their installed copies. The tests run by the latter can be different
+from those run by the former. For instance, there are tests that
+cannot be run in the source tree. Conversely, some packages are set
+up so that @code{make installcheck} will run the very same tests as
+ at code{make check}, only on different files (non-installed
+vs.@: installed). It can make a difference, for instance when the
+source tree's layout is different from that of the installation.
+Furthermore it may help to diagnose an incomplete installation.
+
+Presently most packages do not have any @code{installcheck} tests
+because the existence of @code{installcheck} is little known, and its
+usefulness is neglected. Our little toy package is no better: @code{make
+installcheck} does nothing.
+
+ at node Standard Targets
+ at subsection Standard @file{Makefile} Targets
+
+So far we have come across four ways to run @command{make} in the GNU
+Build System: @code{make}, @code{make check}, @code{make install}, and
+ at code{make installcheck}. The words @code{check}, @code{install}, and
+ at code{installcheck}, passed as arguments to @command{make}, are called
+ at dfn{targets}. @code{make} is a shorthand for @code{make all},
+ at code{all} being the default target in the GNU Build System.
+
+Here is a list of the most useful targets that the GNU Coding Standards
+specify.
+
+ at table @code
+ at item make all
+ at trindex all
+Build programs, libraries, documentation, etc.@: (same as @code{make}).
+ at item make install
+ at trindex install
+Install what needs to be installed, copying the files from the
+package's tree to system-wide directories.
+ at item make install-strip
+ at trindex install-strip
+Same as @code{make install}, then strip debugging symbols. Some
+users like to trade space for useful bug reports at enddots{}
+ at item make uninstall
+ at trindex uninstall
+The opposite of @code{make install}: erase the installed files.
+(This needs to be run from the same build tree that was installed.)
+ at item make clean
+ at trindex clean
+Erase from the build tree the files built by @code{make all}.
+ at item make distclean
+ at trindex distclean
+Additionally erase anything @code{./configure} created.
+ at item make check
+ at trindex check
+Run the test suite, if any.
+ at item make installcheck
+ at trindex installcheck
+Check the installed programs or libraries, if supported.
+ at item make dist
+ at trindex dist
+Recreate @file{@var{package}- at var{version}.tar.gz} from all the source
+files.
+ at end table
+
+ at node Standard Directory Variables
+ at subsection Standard Directory Variables
+ at cindex directory variables
+
+The GNU Coding Standards also specify a hierarchy of variables to
+denote installation directories. Some of these are:
+
+ at multitable {Directory variable} {@code{$@{datarootdir@}/doc/$@{PACKAGE@}}}
+ at headitem Directory variable @tab Default value
+ at item @code{prefix} @tab @code{/usr/local}
+ at item @w{@ @ @code{exec_prefix}} @tab @code{$@{prefix@}}
+ at item @w{@ @ @ @ @code{bindir}} @tab @code{$@{exec_prefix@}/bin}
+ at item @w{@ @ @ @ @code{libdir}} @tab @code{$@{exec_prefix@}/lib}
+ at item @w{@ @ @ @ @dots{}}
+ at item @w{@ @ @code{includedir}} @tab @code{$@{prefix@}/include}
+ at item @w{@ @ @code{datarootdir}} @tab @code{$@{prefix@}/share}
+ at item @w{@ @ @ @ @code{datadir}} @tab @code{$@{datarootdir@}}
+ at item @w{@ @ @ @ @code{mandir}} @tab @code{$@{datarootdir@}/man}
+ at item @w{@ @ @ @ @code{infodir}} @tab @code{$@{datarootdir@}/info}
+ at item @w{@ @ @ @ @code{docdir}} @tab @code{$@{datarootdir@}/doc/$@{PACKAGE@}}
+ at item @w{@ @ @dots{}}
+ at end multitable
+
+ at c We should provide a complete table somewhere, but not here. The
+ at c complete list of directory variables it too confusing as-is. It
+ at c requires some explanations that are too complicated for this
+ at c introduction. Besides listing directories like localstatedir
+ at c would make the explanations in ``Two-Part Install'' harder.
+
+Each of these directories has a role which is often obvious from its
+name. In a package, any installable file will be installed in one of
+these directories. For instance in @code{amhello-1.0}, the program
+ at file{hello} is to be installed in @var{bindir}, the directory for
+binaries. The default value for this directory is
+ at file{/usr/local/bin}, but the user can supply a different value when
+calling @command{configure}. Also the file @file{README} will be
+installed into @var{docdir}, which defaults to
+ at file{/usr/local/share/doc/amhello}.
+
+ at opindex --prefix
+
+As a user, if you wish to install a package on your own account, you
+could proceed as follows:
+
+ at example
+~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
+ at dots{}
+~/amhello-1.0 % @kbd{make}
+ at dots{}
+~/amhello-1.0 % @kbd{make install}
+ at dots{}
+ at end example
+
+This would install @file{~/usr/bin/hello} and
+ at file{~/usr/share/doc/amhello/README}.
+
+The list of all such directory options is shown by
+ at code{./configure --help}.
+
+ at node Standard Configuration Variables
+ at subsection Standard Configuration Variables
+ at cindex configuration variables, overriding
+
+The GNU Coding Standards also define a set of standard configuration
+variables used during the build. Here are some:
+
+ at table @asis
+ at item @code{CC}
+C compiler command
+ at item @code{CFLAGS}
+C compiler flags
+ at item @code{CXX}
+C++ compiler command
+ at item @code{CXXFLAGS}
+C++ compiler flags
+ at item @code{LDFLAGS}
+linker flags
+ at item @code{CPPFLAGS}
+C/C++ preprocessor flags
+ at item @dots{}
+ at end table
+
+ at command{configure} usually does a good job at setting appropriate
+values for these variables, but there are cases where you may want to
+override them. For instance you may have several versions of a
+compiler installed and would like to use another one, you may have
+header files installed outside the default search path of the
+compiler, or even libraries out of the way of the linker.
+
+Here is how one would call @command{configure} to force it to use
+ at command{gcc-3} as C compiler, use header files from
+ at file{~/usr/include} when compiling, and libraries from
+ at file{~/usr/lib} when linking.
+
+ at example
+~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
+CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
+ at end example
+
+Again, a full list of these variables appears in the output of
+ at code{./configure --help}.
+
+ at node config.site
+ at subsection Overriding Default Configuration Setting with @file{config.site}
+ at cindex @file{config.site} example
+
+When installing several packages using the same setup, it can be
+convenient to create a file to capture common settings.
+If a file named @file{@var{prefix}/share/config.site} exists,
+ at command{configure} will source it at the beginning of its execution.
+
+Recall the command from the previous section:
+
+ at example
+~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
+CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
+ at end example
+
+Assuming we are installing many package in @file{~/usr}, and will
+always want to use these definitions of @code{CC}, @code{CPPFLAGS}, and
+ at code{LDFLAGS}, we can automate this by creating the following
+ at file{~/usr/share/config.site} file:
+
+ at example
+test -z "$CC" && CC=gcc-3
+test -z "$CPPFLAGS" && CPPFLAGS=-I$HOME/usr/include
+test -z "$LDFLAGS" && LDFLAGS=-L$HOME/usr/lib
+ at end example
+
+Now, any time a @file{configure} script is using the @file{~/usr}
+prefix, it will execute the above @file{config.site} and define
+these three variables.
+
+ at example
+~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
+configure: loading site script /home/adl/usr/share/config.site
+ at dots{}
+ at end example
+
+ at xref{Site Defaults, , Setting Site Defaults, autoconf, The Autoconf
+Manual}, for more information about this feature.
+
+
+ at node VPATH Builds
+ at subsection Parallel Build Trees (a.k.a.@: VPATH Builds)
+ at cindex Parallel build trees
+ at cindex VPATH builds
+ at cindex source tree and build tree
+ at cindex build tree and source tree
+ at cindex trees, source vs.@: build
+
+The GNU Build System distinguishes two trees: the source tree, and
+the build tree.
+
+The source tree is rooted in the directory containing
+ at file{configure}. It contains all the sources files (those that are
+distributed), and may be arranged using several subdirectories.
+
+The build tree is rooted in the directory in which @file{configure}
+was run, and is populated with all object files, programs, libraries,
+and other derived files built from the sources (and hence not
+distributed). The build tree usually has the same subdirectory layout
+as the source tree; its subdirectories are created automatically by
+the build system.
+
+If @file{configure} is executed in its own directory, the source and
+build trees are combined: derived files are constructed in the same
+directories as their sources. This was the case in our first
+installation example (@pxref{Basic Installation}).
+
+A common request from users is that they want to confine all derived
+files to a single directory, to keep their source directories
+uncluttered. Here is how we could run @file{configure} to build
+everything in a subdirectory called @file{build/}.
+
+ at example
+~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
+~ % @kbd{cd amhello-1.0}
+~/amhello-1.0 % @kbd{mkdir build && cd build}
+~/amhello-1.0/build % @kbd{../configure}
+ at dots{}
+~/amhello-1.0/build % @kbd{make}
+ at dots{}
+ at end example
+
+These setups, where source and build trees are different, are often
+called @dfn{parallel builds} or @dfn{VPATH builds}. The expression
+ at emph{parallel build} is misleading: the word @emph{parallel} is a
+reference to the way the build tree shadows the source tree, it is not
+about some concurrency in the way build commands are run. For this
+reason we refer to such setups using the name @emph{VPATH builds} in
+the following. @emph{VPATH} is the name of the @command{make} feature
+used by the @file{Makefile}s to allow these builds (@pxref{General
+Search, , @code{VPATH} Search Path for All Prerequisites, make, The
+GNU Make Manual}).
+
+ at cindex multiple configurations, example
+ at cindex debug build, example
+ at cindex optimized build, example
+
+VPATH builds have other interesting uses. One is to build the same
+sources with multiple configurations. For instance:
+
+ at c Keep in sync with amhello-cflags.test.
+ at example
+~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
+~ % @kbd{cd amhello-1.0}
+~/amhello-1.0 % @kbd{mkdir debug optim && cd debug}
+~/amhello-1.0/debug % @kbd{../configure CFLAGS='-g -O0'}
+ at dots{}
+~/amhello-1.0/debug % @kbd{make}
+ at dots{}
+~/amhello-1.0/debug % cd ../optim
+~/amhello-1.0/optim % @kbd{../configure CFLAGS='-O3 -fomit-frame-pointer'}
+ at dots{}
+~/amhello-1.0/optim % @kbd{make}
+ at dots{}
+ at end example
+
+With network file systems, a similar approach can be used to build the
+same sources on different machines. For instance, suppose that the
+sources are installed on a directory shared by two hosts: @code{HOST1}
+and @code{HOST2}, which may be different platforms.
+
+ at example
+~ % @kbd{cd /nfs/src}
+/nfs/src % @kbd{tar zxf ~/amhello-1.0.tar.gz}
+ at end example
+
+On the first host, you could create a local build directory:
+ at example
+[HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
+[HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
+...
+[HOST1] /tmp/amh % @kbd{make && sudo make install}
+...
+ at end example
+
+ at noindent
+(Here we assume that the installer has configured @command{sudo} so it
+can execute @code{make install} with root privileges; it is more convenient
+than using @command{su} like in @ref{Basic Installation}).
+
+On the second host, you would do exactly the same, possibly at
+the same time:
+ at example
+[HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
+[HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
+...
+[HOST2] /tmp/amh % @kbd{make && sudo make install}
+...
+ at end example
+
+ at cindex read-only source tree
+ at cindex source tree, read-only
+
+In this scenario, nothing forbids the @file{/nfs/src/amhello-1.0}
+directory from being read-only. In fact VPATH builds are also a means
+of building packages from a read-only medium such as a CD-ROM. (The
+FSF used to sell CD-ROM with unpacked source code, before the GNU
+project grew so big.)
+
+ at node Two-Part Install
+ at subsection Two-Part Installation
+
+In our last example (@pxref{VPATH Builds}), a source tree was shared
+by two hosts, but compilation and installation were done separately on
+each host.
+
+The GNU Build System also supports networked setups where part of the
+installed files should be shared amongst multiple hosts. It does so
+by distinguishing architecture-dependent files from
+architecture-independent files, and providing two @file{Makefile}
+targets to install each of these classes of files.
+
+ at trindex install-exec
+ at trindex install-data
+
+These targets are @code{install-exec} for architecture-dependent files
+and @code{install-data} for architecture-independent files.
+The command we used up to now, @code{make install}, can be thought of
+as a shorthand for @code{make install-exec install-data}.
+
+From the GNU Build System point of view, the distinction between
+architecture-dependent files and architecture-independent files is
+based exclusively on the directory variable used to specify their
+installation destination. In the list of directory variables we
+provided earlier (@pxref{Standard Directory Variables}), all the
+variables based on @var{exec-prefix} designate architecture-dependent
+directories whose files will be installed by @code{make install-exec}.
+The others designate architecture-independent directories and will
+serve files installed by @code{make install-data}. @xref{The Two Parts
+of Install}, for more details.
+
+Here is how we could revisit our two-host installation example,
+assuming that (1) we want to install the package directly in
+ at file{/usr}, and (2) the directory @file{/usr/share} is shared by the
+two hosts.
+
+On the first host we would run
+ at example
+[HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
+[HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
+...
+[HOST1] /tmp/amh % @kbd{make && sudo make install}
+...
+ at end example
+
+On the second host, however, we need only install the
+architecture-specific files.
+ at example
+[HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
+[HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
+...
+[HOST2] /tmp/amh % @kbd{make && sudo make install-exec}
+...
+ at end example
+
+In packages that have installation checks, it would make sense to run
+ at code{make installcheck} (@pxref{Basic Installation}) to verify that
+the package works correctly despite the apparent partial installation.
+
+ at node Cross-Compilation
+ at subsection Cross-Compilation
+ at cindex cross-compilation
+
+To @dfn{cross-compile} is to build on one platform a binary that will
+run on another platform. When speaking of cross-compilation, it is
+important to distinguish between the @dfn{build platform} on which
+the compilation is performed, and the @dfn{host platform} on which the
+resulting executable is expected to run. The following
+ at command{configure} options are used to specify each of them:
+
+ at table @option
+ at item --build=@var{build}
+ at opindex --build=@var{build}
+The system on which the package is built.
+ at item --host=@var{host}
+ at opindex --host=@var{host}
+The system where built programs and libraries will run.
+ at end table
+
+When the @option{--host} is used, @command{configure} will search for
+the cross-compiling suite for this platform. Cross-compilation tools
+commonly have their target architecture as prefix of their name. For
+instance my cross-compiler for MinGW32 has its binaries called
+ at code{i586-mingw32msvc-gcc}, @code{i586-mingw32msvc-ld},
+ at code{i586-mingw32msvc-as}, etc.
+
+ at cindex MinGW cross-compilation example
+ at cindex cross-compilation example
+
+Here is how we could build @code{amhello-1.0} for
+ at code{i586-mingw32msvc} on a GNU/Linux PC.
+
+ at c Keep in sync with amhello-cross-compile.test.
+ at smallexample
+~/amhello-1.0 % @kbd{./configure --build i686-pc-linux-gnu --host i586-mingw32msvc}
+checking for a BSD-compatible install... /usr/bin/install -c
+checking whether build environment is sane... yes
+checking for gawk... gawk
+checking whether make sets $(MAKE)... yes
+checking for i586-mingw32msvc-strip... i586-mingw32msvc-strip
+checking for i586-mingw32msvc-gcc... i586-mingw32msvc-gcc
+checking for C compiler default output file name... a.exe
+checking whether the C compiler works... yes
+checking whether we are cross compiling... yes
+checking for suffix of executables... .exe
+checking for suffix of object files... o
+checking whether we are using the GNU C compiler... yes
+checking whether i586-mingw32msvc-gcc accepts -g... yes
+checking for i586-mingw32msvc-gcc option to accept ANSI C...
+ at dots{}
+~/amhello-1.0 % @kbd{make}
+ at dots{}
+~/amhello-1.0 % @kbd{cd src; file hello.exe}
+hello.exe: MS Windows PE 32-bit Intel 80386 console executable not relocatable
+ at end smallexample
+
+The @option{--host} and @option{--build} options are usually all we
+need for cross-compiling. The only exception is if the package being
+built is itself a cross-compiler: we need a third option to specify
+its target architecture.
+
+ at table @option
+ at item --target=@var{target}
+ at opindex --target=@var{target}
+When building compiler tools: the system for which the tools will
+create output.
+ at end table
+
+For instance when installing GCC, the GNU Compiler Collection, we can
+use @option{--target=@/@var{target}} to specify that we want to build
+GCC as a cross-compiler for @var{target}. Mixing @option{--build} and
+ at option{--target}, we can actually cross-compile a cross-compiler;
+such a three-way cross-compilation is known as a @dfn{Canadian cross}.
+
+ at xref{Specifying Names, , Specifying the System Type, autoconf, The
+Autoconf Manual}, for more information about these @command{configure}
+options.
+
+ at node Renaming
+ at subsection Renaming Programs at Install Time
+ at cindex Renaming programs
+ at cindex Transforming program names
+ at cindex Programs, renaming during installation
+
+The GNU Build System provides means to automatically rename
+executables and manpages before they are installed (@pxref{Man Pages}).
+This is especially convenient
+when installing a GNU package on a system that already has a
+proprietary implementation you do not want to overwrite. For instance,
+you may want to install GNU @command{tar} as @command{gtar} so you can
+distinguish it from your vendor's @command{tar}.
+
+This can be done using one of these three @command{configure} options.
+
+ at table @option
+ at item --program-prefix=@var{prefix}
+ at opindex --program-prefix=@var{prefix}
+Prepend @var{prefix} to installed program names.
+ at item --program-suffix=@var{suffix}
+ at opindex --program-suffix=@var{suffix}
+Append @var{suffix} to installed program names.
+ at item --program-transform-name=@var{program}
+ at opindex --program-transform-name=@var{program}
+Run @code{sed @var{program}} on installed program names.
+ at end table
+
+The following commands would install @file{hello}
+as @file{/usr/local/bin/test-hello}, for instance.
+
+ at example
+~/amhello-1.0 % @kbd{./configure --program-prefix test-}
+ at dots{}
+~/amhello-1.0 % @kbd{make}
+ at dots{}
+~/amhello-1.0 % @kbd{sudo make install}
+ at dots{}
+ at end example
+
+ at node DESTDIR
+ at subsection Building Binary Packages Using DESTDIR
+ at vindex DESTDIR
+
+The GNU Build System's @code{make install} and @code{make uninstall}
+interface does not exactly fit the needs of a system administrator
+who has to deploy and upgrade packages on lots of hosts. In other
+words, the GNU Build System does not replace a package manager.
+
+Such package managers usually need to know which files have been
+installed by a package, so a mere @code{make install} is
+inappropriate.
+
+ at cindex Staged installation
+
+The @code{DESTDIR} variable can be used to perform a staged
+installation. The package should be configured as if it was going to
+be installed in its final location (e.g., @code{--prefix /usr}), but
+when running @code{make install}, the @code{DESTDIR} should be set to
+the absolute name of a directory into which the installation will be
+diverted. From this directory it is easy to review which files are
+being installed where, and finally copy them to their final location
+by some means.
+
+ at cindex Binary package
+
+For instance here is how we could create a binary package containing a
+snapshot of all the files to be installed.
+
+ at c Keep in sync with amhello-binpkg.test.
+ at example
+~/amhello-1.0 % @kbd{./configure --prefix /usr}
+ at dots{}
+~/amhello-1.0 % @kbd{make}
+ at dots{}
+~/amhello-1.0 % @kbd{make DESTDIR=$HOME/inst install}
+ at dots{}
+~/amhello-1.0 % @kbd{cd ~/inst}
+~/inst % @kbd{find . -type f -print > ../files.lst}
+~/inst % @kbd{tar zcvf ~/amhello-1.0-i686.tar.gz `cat ../files.lst`}
+./usr/bin/hello
+./usr/share/doc/amhello/README
+ at end example
+
+After this example, @code{amhello-1.0-i686.tar.gz} is ready to be
+uncompressed in @file{/} on many hosts. (Using @code{`cat ../files.lst`}
+instead of @samp{.} as argument for @command{tar} avoids entries for
+each subdirectory in the archive: we would not like @command{tar} to
+restore the modification time of @file{/}, @file{/usr/}, etc.)
+
+Note that when building packages for several architectures, it might
+be convenient to use @code{make install-data} and @code{make
+install-exec} (@pxref{Two-Part Install}) to gather
+architecture-independent files in a single package.
+
+ at xref{Install}, for more information.
+
+ at c We should document PRE_INSTALL/POST_INSTALL/NORMAL_INSTALL and their
+ at c UNINSTALL counterparts.
+
+ at node Preparing Distributions
+ at subsection Preparing Distributions
+ at cindex Preparing distributions
+ at cindex Packages, preparation
+ at cindex Distributions, preparation
+
+We have already mentioned @code{make dist}. This target collects all
+your source files and the necessary parts of the build system to
+create a tarball named @file{@var{package}- at var{version}.tar.gz}.
+
+ at cindex @code{distcheck} better than @code{dist}
+
+Another, more useful command is @code{make distcheck}. The
+ at code{distcheck} target constructs
+ at file{@var{package}- at var{version}.tar.gz} just as well as @code{dist},
+but it additionally ensures most of the use cases presented so far
+work:
+
+ at itemize @bullet
+ at item
+It attempts a full compilation of the package (@pxref{Basic
+Installation}), unpacking the newly constructed tarball, running
+ at code{make}, @code{make check}, @code{make install}, as well as
+ at code{make installcheck}, and even @code{make dist},
+ at item
+it tests VPATH builds with read-only source tree (@pxref{VPATH Builds}),
+ at item
+it makes sure @code{make clean}, @code{make distclean}, and @code{make
+uninstall} do not omit any file (@pxref{Standard Targets}),
+ at item
+and it checks that @code{DESTDIR} installations work (@pxref{DESTDIR}).
+ at end itemize
+
+All of these actions are performed in a temporary subdirectory, so
+that no root privileges are required.
+
+Releasing a package that fails @code{make distcheck} means that one of
+the scenarios we presented will not work and some users will be
+disappointed. Therefore it is a good practice to release a package
+only after a successful @code{make distcheck}. This of course does
+not imply that the package will be flawless, but at least it will
+prevent some of the embarrassing errors you may find in packages
+released by people who have never heard about @code{distcheck} (like
+ at code{DESTDIR} not working because of a typo, or a distributed file
+being erased by @code{make clean}, or even @code{VPATH} builds not
+working).
+
+ at xref{Creating amhello}, to recreate @file{amhello-1.0.tar.gz} using
+ at code{make distcheck}. @xref{Checking the Distribution}, for more
+information about @code{distcheck}.
+
+ at node Dependency Tracking
+ at subsection Automatic Dependency Tracking
+ at cindex Dependency tracking
+
+Dependency tracking is performed as a side-effect of compilation.
+Each time the build system compiles a source file, it computes its
+list of dependencies (in C these are the header files included by the
+source being compiled). Later, any time @command{make} is run and a
+dependency appears to have changed, the dependent files will be
+rebuilt.
+
+Automake generates code for automatic dependency tracking by default,
+unless the developer chooses to override it; for more information,
+ at pxref{Dependencies}.
+
+When @command{configure} is executed, you can see it probing each
+compiler for the dependency mechanism it supports (several mechanisms
+can be used):
+
+ at example
+~/amhello-1.0 % @kbd{./configure --prefix /usr}
+ at dots{}
+checking dependency style of gcc... gcc3
+ at dots{}
+ at end example
+
+Because dependencies are only computed as a side-effect of the
+compilation, no dependency information exists the first time a package
+is built. This is OK because all the files need to be built anyway:
+ at code{make} does not have to decide which files need to be rebuilt.
+In fact, dependency tracking is completely useless for one-time builds
+and there is a @command{configure} option to disable this:
+
+ at table @option
+ at item --disable-dependency-tracking
+ at opindex --disable-dependency-tracking
+Speed up one-time builds.
+ at end table
+
+Some compilers do not offer any practical way to derive the list of
+dependencies as a side-effect of the compilation, requiring a separate
+run (maybe of another tool) to compute these dependencies. The
+performance penalty implied by these methods is important enough to
+disable them by default. The option @option{--enable-dependency-tracking}
+must be passed to @command{configure} to activate them.
+
+ at table @option
+ at item --enable-dependency-tracking
+ at opindex --enable-dependency-tracking
+Do not reject slow dependency extractors.
+ at end table
+
+ at xref{Dependency Tracking Evolution}, for some discussion about the
+different dependency tracking schemes used by Automake over the years.
+
+ at node Nested Packages
+ at subsection Nested Packages
+ at cindex Nested packages
+ at cindex Packages, nested
+ at cindex Subpackages
+
+Although nesting packages isn't something we would recommend to
+someone who is discovering the Autotools, it is a nice feature worthy
+of mention in this small advertising tour.
+
+Autoconfiscated packages (that means packages whose build system have
+been created by Autoconf and friends) can be nested to arbitrary
+depth.
+
+A typical setup is that package A will distribute one of the libraries
+it needs in a subdirectory. This library B is a complete package with
+its own GNU Build System. The @command{configure} script of A will
+run the @command{configure} script of B as part of its execution,
+building and installing A will also build and install B. Generating a
+distribution for A will also include B.
+
+It is possible to gather several packages like this. GCC is a heavy
+user of this feature. This gives installers a single package to
+configure, build and install, while it allows developers to work on
+subpackages independently.
+
+When configuring nested packages, the @command{configure} options
+given to the top-level @command{configure} are passed recursively to
+nested @command{configure}s. A package that does not understand an
+option will ignore it, assuming it is meaningful to some other
+package.
+
+ at opindex --help=recursive
+
+The command @code{configure --help=recursive} can be used to display
+the options supported by all the included packages.
+
+ at xref{Subpackages}, for an example setup.
+
+ at node Why Autotools
+ at section How Autotools Help
+ at cindex Autotools, purpose
+
+There are several reasons why you may not want to implement the GNU
+Build System yourself (read: write a @file{configure} script and
+ at file{Makefile}s yourself).
+
+ at itemize @bullet
+ at item
+As we have seen, the GNU Build System has a lot of
+features (@pxref{Use Cases}).
+Some users may expect features you have not implemented because
+you did not need them.
+ at item
+Implementing these features portably is difficult and exhausting.
+Think of writing portable shell scripts, and portable
+ at file{Makefile}s, for systems you may not have handy. @xref{Portable
+Shell, , Portable Shell Programming, autoconf, The Autoconf Manual}, to
+convince yourself.
+ at item
+You will have to upgrade your setup to follow changes to the GNU
+Coding Standards.
+ at end itemize
+
+The GNU Autotools take all this burden off your back and provide:
+
+ at itemize @bullet
+ at item
+Tools to create a portable, complete, and self-contained GNU Build
+System, from simple instructions.
+ at emph{Self-contained} meaning the resulting build system does not
+require the GNU Autotools.
+ at item
+A central place where fixes and improvements are made:
+a bug-fix for a portability issue will benefit every package.
+ at end itemize
+
+Yet there also exist reasons why you may want NOT to use the
+Autotools at enddots{} For instance you may be already using (or used to)
+another incompatible build system. Autotools will only be useful if
+you do accept the concepts of the GNU Build System. People who have their
+own idea of how a build system should work will feel frustrated by the
+Autotools.
+
+ at node Hello World
+ at section A Small Hello World
+ at cindex Example Hello World
+ at cindex Hello World example
+ at cindex @file{amhello-1.0.tar.gz}, creation
+
+In this section we recreate the @file{amhello-1.0} package from
+scratch. The first subsection shows how to call the Autotools to
+instantiate the GNU Build System, while the second explains the
+meaning of the @file{configure.ac} and @file{Makefile.am} files read
+by the Autotools.
+
+ at anchor{amhello Explained}
+ at menu
+* Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch
+* amhello's configure.ac Setup Explained::
+* amhello's Makefile.am Setup Explained::
+ at end menu
+
+ at node Creating amhello
+ at subsection Creating @file{amhello-1.0.tar.gz}
+
+Here is how we can recreate @file{amhello-1.0.tar.gz} from scratch.
+The package is simple enough so that we will only need to write 5
+files. (You may copy them from the final @file{amhello-1.0.tar.gz}
+that is distributed with Automake if you do not want to write them.)
+
+Create the following files in an empty directory.
+
+ at itemize @bullet
+
+ at item
+ at file{src/main.c} is the source file for the @file{hello} program. We
+store it in the @file{src/} subdirectory, because later, when the package
+evolves, it will ease the addition of a @file{man/} directory for man
+pages, a @file{data/} directory for data files, etc.
+ at example
+~/amhello % @kbd{cat src/main.c}
+#include <config.h>
+#include <stdio.h>
+
+int
+main (void)
+@{
+ puts ("Hello World!");
+ puts ("This is " PACKAGE_STRING ".");
+ return 0;
+@}
+ at end example
+
+ at item
+ at file{README} contains some very limited documentation for our little
+package.
+ at example
+~/amhello % @kbd{cat README}
+This is a demonstration package for GNU Automake.
+Type `info Automake' to read the Automake manual.
+ at end example
+
+ at item
+ at file{Makefile.am} and @file{src/Makefile.am} contain Automake
+instructions for these two directories.
+
+ at example
+~/amhello % @kbd{cat src/Makefile.am}
+bin_PROGRAMS = hello
+hello_SOURCES = main.c
+~/amhello % @kbd{cat Makefile.am}
+SUBDIRS = src
+dist_doc_DATA = README
+ at end example
+
+ at item
+Finally, @file{configure.ac} contains Autoconf instructions to
+create the @command{configure} script.
+
+ at example
+~/amhello % @kbd{cat configure.ac}
+AC_INIT([amhello], [1.0], [@value{PACKAGE_BUGREPORT}])
+AM_INIT_AUTOMAKE([-Wall -Werror foreign])
+AC_PROG_CC
+AC_CONFIG_HEADERS([config.h])
+AC_CONFIG_FILES([
+ Makefile
+ src/Makefile
+])
+AC_OUTPUT
+ at end example
+ at end itemize
+
+ at cindex @command{autoreconf}, example
+
+Once you have these five files, it is time to run the Autotools to
+instantiate the build system. Do this using the @command{autoreconf}
+command as follows:
+
+ at example
+~/amhello % @kbd{autoreconf --install}
+configure.ac: installing `./install-sh'
+configure.ac: installing `./missing'
+src/Makefile.am: installing `./depcomp'
+ at end example
+
+At this point the build system is complete.
+
+In addition to the three scripts mentioned in its output, you can see
+that @command{autoreconf} created four other files: @file{configure},
+ at file{config.h.in}, @file{Makefile.in}, and @file{src/Makefile.in}.
+The latter three files are templates that will be adapted to the
+system by @command{configure} under the names @file{config.h},
+ at file{Makefile}, and @file{src/Makefile}. Let's do this:
+
+ at example
+~/amhello % @kbd{./configure}
+checking for a BSD-compatible install... /usr/bin/install -c
+checking whether build environment is sane... yes
+checking for gawk... no
+checking for mawk... mawk
+checking whether make sets $(MAKE)... yes
+checking for gcc... gcc
+checking for C compiler default output file name... a.out
+checking whether the C compiler works... yes
+checking whether we are cross compiling... no
+checking for suffix of executables...
+checking for suffix of object files... o
+checking whether we are using the GNU C compiler... yes
+checking whether gcc accepts -g... yes
+checking for gcc option to accept ISO C89... none needed
+checking for style of include used by make... GNU
+checking dependency style of gcc... gcc3
+configure: creating ./config.status
+config.status: creating Makefile
+config.status: creating src/Makefile
+config.status: creating config.h
+config.status: executing depfiles commands
+ at end example
+
+ at trindex distcheck
+ at cindex @code{distcheck} example
+
+You can see @file{Makefile}, @file{src/Makefile}, and @file{config.h}
+being created at the end after @command{configure} has probed the
+system. It is now possible to run all the targets we wish
+(@pxref{Standard Targets}). For instance:
+
+ at example
+~/amhello % @kbd{make}
+ at dots{}
+~/amhello % @kbd{src/hello}
+Hello World!
+This is amhello 1.0.
+~/amhello % @kbd{make distcheck}
+ at dots{}
+=============================================
+amhello-1.0 archives ready for distribution:
+amhello-1.0.tar.gz
+=============================================
+ at end example
+
+Note that running @command{autoreconf} is only needed initially when
+the GNU Build System does not exist. When you later change some
+instructions in a @file{Makefile.am} or @file{configure.ac}, the
+relevant part of the build system will be regenerated automatically
+when you execute @command{make}.
+
+ at command{autoreconf} is a script that calls @command{autoconf},
+ at command{automake}, and a bunch of other commands in the right order.
+If you are beginning with these tools, it is not important to figure
+out in which order all these tools should be invoked and why. However,
+because Autoconf and Automake have separate manuals, the important
+point to understand is that @command{autoconf} is in charge of
+creating @file{configure} from @file{configure.ac}, while
+ at command{automake} is in charge of creating @file{Makefile.in}s from
+ at file{Makefile.am}s and @file{configure.ac}. This should at least
+direct you to the right manual when seeking answers.
+
+
+ at node amhello's configure.ac Setup Explained
+ at subsection @code{amhello}'s @file{configure.ac} Setup Explained
+
+ at cindex @file{configure.ac}, Hello World
+
+Let us begin with the contents of @file{configure.ac}.
+
+ at example
+AC_INIT([amhello], [1.0], [@value{PACKAGE_BUGREPORT}])
+AM_INIT_AUTOMAKE([-Wall -Werror foreign])
+AC_PROG_CC
+AC_CONFIG_HEADERS([config.h])
+AC_CONFIG_FILES([
+ Makefile
+ src/Makefile
+])
+AC_OUTPUT
+ at end example
+
+This file is read by both @command{autoconf} (to create
+ at file{configure}) and @command{automake} (to create the various
+ at file{Makefile.in}s). It contains a series of M4 macros that will be
+expanded as shell code to finally form the @file{configure} script.
+We will not elaborate on the syntax of this file, because the Autoconf
+manual has a whole section about it (@pxref{Writing Autoconf Input, ,
+Writing @file{configure.ac}, autoconf, The Autoconf Manual}).
+
+The macros prefixed with @code{AC_} are Autoconf macros, documented
+in the Autoconf manual (@pxref{Autoconf Macro Index, , Autoconf Macro
+Index, autoconf, The Autoconf Manual}). The macros that start with
+ at code{AM_} are Automake macros, documented later in this manual
+(@pxref{Macro Index}).
+
+The first two lines of @file{configure.ac} initialize Autoconf and
+Automake. @code{AC_INIT} takes in as parameters the name of the package,
+its version number, and a contact address for bug-reports about the
+package (this address is output at the end of @code{./configure
+--help}, for instance). When adapting this setup to your own package,
+by all means please do not blindly copy Automake's address: use the
+mailing list of your package, or your own mail address.
+
+ at opindex -Wall
+ at opindex -Werror
+ at opindex foreign
+
+The argument to @code{AM_INIT_AUTOMAKE} is a list of options for
+ at command{automake} (@pxref{Options}). @option{-Wall} and
+ at option{-Werror} ask @command{automake} to turn on all warnings and
+report them as errors. We are speaking of @strong{Automake} warnings
+here, such as dubious instructions in @file{Makefile.am}. This has
+absolutely nothing to do with how the compiler will be called, even
+though it may support options with similar names. Using @option{-Wall
+-Werror} is a safe setting when starting to work on a package: you do
+not want to miss any issues. Later you may decide to relax things a
+bit. The @option{foreign} option tells Automake that this package
+will not follow the GNU Standards. GNU packages should always
+distribute additional files such as @file{ChangeLog}, @file{AUTHORS},
+etc. We do not want @command{automake} to complain about these
+missing files in our small example.
+
+The @code{AC_PROG_CC} line causes the @command{configure} script to
+search for a C compiler and define the variable @code{CC} with its
+name. The @file{src/Makefile.in} file generated by Automake uses the
+variable @code{CC} to build @file{hello}, so when @command{configure}
+creates @file{src/Makefile} from @file{src/Makefile.in}, it will define
+ at code{CC} with the value it has found. If Automake is asked to create
+a @file{Makefile.in} that uses @code{CC} but @file{configure.ac} does
+not define it, it will suggest you add a call to @code{AC_PROG_CC}.
+
+The @code{AC_CONFIG_HEADERS([config.h])} invocation causes the
+ at command{configure} script to create a @file{config.h} file gathering
+ at samp{#define}s defined by other macros in @file{configure.ac}. In our
+case, the @code{AC_INIT} macro already defined a few of them. Here
+is an excerpt of @file{config.h} after @command{configure} has run:
+
+ at smallexample
+ at dots{}
+/* Define to the address where bug reports for this package should be sent. */
+#define PACKAGE_BUGREPORT "@value{PACKAGE_BUGREPORT}"
+
+/* Define to the full name and version of this package. */
+#define PACKAGE_STRING "amhello 1.0"
+ at dots{}
+ at end smallexample
+
+As you probably noticed, @file{src/main.c} includes @file{config.h} so
+it can use @code{PACKAGE_STRING}. In a real-world project,
+ at file{config.h} can grow really big, with one @samp{#define} per
+feature probed on the system.
+
+The @code{AC_CONFIG_FILES} macro declares the list of files that
+ at command{configure} should create from their @file{*.in} templates.
+Automake also scans this list to find the @file{Makefile.am} files it must
+process. (This is important to remember: when adding a new directory
+to your project, you should add its @file{Makefile} to this list,
+otherwise Automake will never process the new @file{Makefile.am} you
+wrote in that directory.)
+
+Finally, the @code{AC_OUTPUT} line is a closing command that actually
+produces the part of the script in charge of creating the files
+registered with @code{AC_CONFIG_HEADERS} and @code{AC_CONFIG_FILES}.
+
+ at cindex @command{autoscan}
+
+When starting a new project, we suggest you start with such a simple
+ at file{configure.ac}, and gradually add the other tests it requires.
+The command @command{autoscan} can also suggest a few of the tests
+your package may need (@pxref{autoscan Invocation, , Using
+ at command{autoscan} to Create @file{configure.ac}, autoconf, The
+Autoconf Manual}).
+
+
+ at node amhello's Makefile.am Setup Explained
+ at subsection @code{amhello}'s @file{Makefile.am} Setup Explained
+
+ at cindex @file{Makefile.am}, Hello World
+
+We now turn to @file{src/Makefile.am}. This file contains
+Automake instructions to build and install @file{hello}.
+
+ at example
+bin_PROGRAMS = hello
+hello_SOURCES = main.c
+ at end example
+
+A @file{Makefile.am} has the same syntax as an ordinary
+ at file{Makefile}. When @command{automake} processes a
+ at file{Makefile.am} it copies the entire file into the output
+ at file{Makefile.in} (that will be later turned into @file{Makefile} by
+ at command{configure}) but will react to certain variable definitions
+by generating some build rules and other variables.
+Often @file{Makefile.am}s contain only a list of variable definitions as
+above, but they can also contain other variable and rule definitions that
+ at command{automake} will pass along without interpretation.
+
+Variables that end with @code{_PROGRAMS} are special variables
+that list programs that the resulting @file{Makefile} should build.
+In Automake speak, this @code{_PROGRAMS} suffix is called a
+ at dfn{primary}; Automake recognizes other primaries such as
+ at code{_SCRIPTS}, @code{_DATA}, @code{_LIBRARIES}, etc.@: corresponding
+to different types of files.
+
+The @samp{bin} part of the @code{bin_PROGRAMS} tells
+ at command{automake} that the resulting programs should be installed in
+ at var{bindir}. Recall that the GNU Build System uses a set of variables
+to denote destination directories and allow users to customize these
+locations (@pxref{Standard Directory Variables}). Any such directory
+variable can be put in front of a primary (omitting the @code{dir}
+suffix) to tell @command{automake} where to install the listed files.
+
+Programs need to be built from source files, so for each program
+ at code{@var{prog}} listed in a @code{@w{_PROGRAMS}} variable,
+ at command{automake} will look for another variable named
+ at code{@var{prog}_SOURCES} listing its source files. There may be more
+than one source file: they will all be compiled and linked together.
+
+Automake also knows that source files need to be distributed when
+creating a tarball (unlike built programs). So a side-effect of this
+ at code{hello_SOURCES} declaration is that @file{main.c} will be
+part of the tarball created by @code{make dist}.
+
+Finally here are some explanations regarding the top-level
+ at file{Makefile.am}.
+
+ at example
+SUBDIRS = src
+dist_doc_DATA = README
+ at end example
+
+ at code{SUBDIRS} is a special variable listing all directories that
+ at command{make} should recurse into before processing the current
+directory. So this line is responsible for @command{make} building
+ at file{src/hello} even though we run it from the top-level. This line
+also causes @code{make install} to install @file{src/hello} before
+installing @file{README} (not that this order matters).
+
+The line @code{dist_doc_DATA = README} causes @file{README} to be
+distributed and installed in @var{docdir}. Files listed with the
+ at code{_DATA} primary are not automatically part of the tarball built
+with @code{make dist}, so we add the @code{dist_} prefix so they get
+distributed. However, for @file{README} it would not have been
+necessary: @command{automake} automatically distributes any
+ at file{README} file it encounters (the list of other files
+automatically distributed is presented by @code{automake --help}).
+The only important effect of this second line is therefore to install
+ at file{README} during @code{make install}.
+
+One thing not covered in this example is accessing the installation
+directory values (@pxref{Standard Directory Variables}) from your
+program code, that is, converting them into defined macros. For this,
+ at pxref{Defining Directories,,, autoconf, The Autoconf Manual}.
+
+
+ at node Generalities
+ at chapter General ideas
+
+The following sections cover a few basic ideas that will help you
+understand how Automake works.
+
+ at menu
+* General Operation:: General operation of Automake
+* Strictness:: Standards conformance checking
+* Uniform:: The Uniform Naming Scheme
+* Length Limitations:: Staying below the command line length limit
+* Canonicalization:: How derived variables are named
+* User Variables:: Variables reserved for the user
+* Auxiliary Programs:: Programs automake might require
+ at end menu
+
+
+ at node General Operation
+ at section General Operation
+
+Automake works by reading a @file{Makefile.am} and generating a
+ at file{Makefile.in}. Certain variables and rules defined in the
+ at file{Makefile.am} instruct Automake to generate more specialized code;
+for instance, a @code{bin_PROGRAMS} variable definition will cause rules
+for compiling and linking programs to be generated.
+
+ at cindex Non-standard targets
+ at cindex @code{git-dist}, non-standard example
+ at trindex git-dist
+
+The variable definitions and rules in the @file{Makefile.am} are
+copied mostly verbatim into the generated file, with all variable
+definitions preceding all rules. This allows you to add almost
+arbitrary code into the generated @file{Makefile.in}. For instance,
+the Automake distribution includes a non-standard rule for the
+ at code{git-dist} target, which the Automake maintainer uses to make
+distributions from the source control system.
+
+ at cindex GNU make extensions
+
+Note that most GNU make extensions are not recognized by Automake. Using
+such extensions in a @file{Makefile.am} will lead to errors or confusing
+behavior.
+
+ at cindex Append operator
+ at cmindex +=
+A special exception is that the GNU make append operator, @samp{+=}, is
+supported. This operator appends its right hand argument to the variable
+specified on the left. Automake will translate the operator into
+an ordinary @samp{=} operator; @samp{+=} will thus work with any make program.
+
+Automake tries to keep comments grouped with any adjoining rules or
+variable definitions.
+
+ at cindex Limitations of automake parser
+ at cindex Automake parser, limitations of
+ at cindex indentation in Makefile.am
+Generally, Automake is not particularly smart in the parsing of unusual
+Makefile constructs, so you're advised to avoid fancy constructs or
+``creative'' use of whitespaces.
+ at c Keep this in sync with doc-parsing-buglets-tabs.test.
+For example, @key{TAB} characters cannot be used between a target name
+and the following ``@code{:}'' character, and variable assignments
+shouldn't be indented with @key{TAB} characters.
+ at c Keep this in sync with doc-parsing-buglets-colneq-subst.test.
+Also, using more complex macro in target names can cause trouble:
+
+ at example
+% @kbd{cat Makefile.am}
+$(FOO:=x): bar
+% @kbd{automake}
+Makefile.am:1: bad characters in variable name `$(FOO'
+Makefile.am:1: `:='-style assignments are not portable
+ at end example
+
+ at cindex Make targets, overriding
+ at cindex Make rules, overriding
+ at cindex Overriding make rules
+ at cindex Overriding make targets
+
+A rule defined in @file{Makefile.am} generally overrides any such
+rule of a similar name that would be automatically generated by
+ at command{automake}. Although this is a supported feature, it is generally
+best to avoid making use of it, as sometimes the generated rules are
+very particular.
+
+ at cindex Variables, overriding
+ at cindex Overriding make variables
+
+Similarly, a variable defined in @file{Makefile.am} or
+ at code{AC_SUBST}ed from @file{configure.ac} will override any
+definition of the variable that @command{automake} would ordinarily
+create. This feature is more often useful than the ability to
+override a rule. Be warned that many of the variables generated by
+ at command{automake} are considered to be for internal use only, and their
+names might change in future releases.
+
+ at cindex Recursive operation of Automake
+ at cindex Automake, recursive operation
+ at cindex Example of recursive operation
+
+When examining a variable definition, Automake will recursively examine
+variables referenced in the definition. For example, if Automake is
+looking at the content of @code{foo_SOURCES} in this snippet
+
+ at c Keep in sync with interp.test.
+ at example
+xs = a.c b.c
+foo_SOURCES = c.c $(xs)
+ at end example
+
+it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
+contents of @code{foo_SOURCES}.
+
+ at cindex @code{##} (special Automake comment)
+ at cindex Special Automake comment
+ at cindex Comment, special to Automake
+
+Automake also allows a form of comment that is @emph{not} copied into
+the output; all lines beginning with @samp{##} (leading spaces allowed)
+are completely ignored by Automake.
+
+It is customary to make the first line of @file{Makefile.am} read:
+
+ at cindex Makefile.am, first line
+ at cindex First line of Makefile.am
+
+ at example
+## Process this file with automake to produce Makefile.in
+ at end example
+
+ at c FIXME discuss putting a copyright into Makefile.am here? I would but
+ at c I don't know quite what to say.
+
+ at c FIXME document customary ordering of Makefile.am here!
+
+
+ at node Strictness
+ at section Strictness
+
+ at cindex Non-GNU packages
+
+While Automake is intended to be used by maintainers of GNU packages, it
+does make some effort to accommodate those who wish to use it, but do
+not want to use all the GNU conventions.
+
+ at cindex Strictness, defined
+ at cindex Strictness, @option{foreign}
+ at cindex @option{foreign} strictness
+ at cindex Strictness, @option{gnu}
+ at cindex @option{gnu} strictness
+ at cindex Strictness, @option{gnits}
+ at cindex @option{gnits} strictness
+
+To this end, Automake supports three levels of @dfn{strictness}---the
+strictness indicating how stringently Automake should check standards
+conformance.
+
+The valid strictness levels are:
+
+ at table @option
+ at item foreign
+Automake will check for only those things that are absolutely
+required for proper operations. For instance, whereas GNU standards
+dictate the existence of a @file{NEWS} file, it will not be required in
+this mode. The name comes from the fact that Automake is intended to be
+used for GNU programs; these relaxed rules are not the standard mode of
+operation.
+
+ at item gnu
+Automake will check---as much as possible---for compliance to the GNU
+standards for packages. This is the default.
+
+ at item gnits
+Automake will check for compliance to the as-yet-unwritten @dfn{Gnits
+standards}. These are based on the GNU standards, but are even more
+detailed. Unless you are a Gnits standards contributor, it is
+recommended that you avoid this option until such time as the Gnits
+standard is actually published (which may never happen).
+ at end table
+
+ at xref{Gnits}, for more information on the precise implications of the
+strictness level.
+
+Automake also has a special (and @emph{today deprecated}) ``cygnus'' mode
+that is similar to strictness but handled differently. This mode is
+useful for packages that are put into a ``Cygnus'' style tree (e.g., older
+versions of the GCC and gdb trees). @xref{Cygnus}, for more information
+on this mode. Please note that this mode is deprecated and @emph{will be
+removed in the future automake versions}; you must avoid its use in new
+packages, and should stop using it in existing packages as well.
+
+
+ at node Uniform
+ at section The Uniform Naming Scheme
+
+ at cindex Uniform naming scheme
+
+Automake variables generally follow a @dfn{uniform naming scheme} that
+makes it easy to decide how programs (and other derived objects) are
+built, and how they are installed. This scheme also supports
+ at command{configure} time determination of what should be built.
+
+ at cindex @code{_PROGRAMS} primary variable
+ at cindex @code{PROGRAMS} primary variable
+ at cindex Primary variable, @code{PROGRAMS}
+ at cindex Primary variable, defined
+ at vindex _PROGRAMS
+
+At @command{make} time, certain variables are used to determine which
+objects are to be built. The variable names are made of several pieces
+that are concatenated together.
+
+The piece that tells @command{automake} what is being built is commonly called
+the @dfn{primary}. For instance, the primary @code{PROGRAMS} holds a
+list of programs that are to be compiled and linked.
+ at vindex PROGRAMS
+
+ at cindex @code{pkgdatadir}, defined
+ at cindex @code{pkgincludedir}, defined
+ at cindex @code{pkglibdir}, defined
+ at cindex @code{pkglibexecdir}, defined
+
+ at vindex pkgdatadir
+ at vindex pkgincludedir
+ at vindex pkglibdir
+ at vindex pkglibexecdir
+
+ at cindex @code{PACKAGE}, directory
+A different set of names is used to decide where the built objects
+should be installed. These names are prefixes to the primary, and they
+indicate which standard directory should be used as the installation
+directory. The standard directory names are given in the GNU standards
+(@pxref{Directory Variables, , , standards, The GNU Coding Standards}).
+Automake extends this list with @code{pkgdatadir}, @code{pkgincludedir},
+ at code{pkglibdir}, and @code{pkglibexecdir}; these are the same as the
+non- at samp{pkg} versions, but with @samp{$(PACKAGE)} appended. For instance,
+ at code{pkglibdir} is defined as @samp{$(libdir)/$(PACKAGE)}.
+
+ at cindex @code{EXTRA_}, prepending
+For each primary, there is one additional variable named by prepending
+ at samp{EXTRA_} to the primary name. This variable is used to list
+objects that may or may not be built, depending on what
+ at command{configure} decides. This variable is required because Automake
+must statically know the entire list of objects that may be built in
+order to generate a @file{Makefile.in} that will work in all cases.
+
+ at cindex @code{EXTRA_PROGRAMS}, defined
+ at cindex Example, @code{EXTRA_PROGRAMS}
+ at cindex @command{cpio} example
+
+For instance, @command{cpio} decides at configure time which programs
+should be built. Some of the programs are installed in @code{bindir},
+and some are installed in @code{sbindir}:
+
+ at example
+EXTRA_PROGRAMS = mt rmt
+bin_PROGRAMS = cpio pax
+sbin_PROGRAMS = $(MORE_PROGRAMS)
+ at end example
+
+Defining a primary without a prefix as a variable, e.g.,
+ at samp{PROGRAMS}, is an error.
+
+Note that the common @samp{dir} suffix is left off when constructing the
+variable names; thus one writes @samp{bin_PROGRAMS} and not
+ at samp{bindir_PROGRAMS}.
+
+Not every sort of object can be installed in every directory. Automake
+will flag those attempts it finds in error (but see below how to override
+the check if you really need to).
+Automake will also diagnose obvious misspellings in directory names.
+
+ at cindex Extending list of installation directories
+ at cindex Installation directories, extending list
+
+Sometimes the standard directories---even as augmented by
+Automake---are not enough. In particular it is sometimes useful, for
+clarity, to install objects in a subdirectory of some predefined
+directory. To this end, Automake allows you to extend the list of
+possible installation directories. A given prefix (e.g., @samp{zar})
+is valid if a variable of the same name with @samp{dir} appended is
+defined (e.g., @samp{zardir}).
+
+For instance, the following snippet will install @file{file.xml} into
+ at samp{$(datadir)/xml}.
+
+ at c Keep in sync with primary-prefix-couples-documented-valid.test.
+ at example
+xmldir = $(datadir)/xml
+xml_DATA = file.xml
+ at end example
+
+This feature can also be used to override the sanity checks Automake
+performs to diagnose suspicious directory/primary couples (in the
+unlikely case these checks are undesirable, and you really know what
+you're doing). For example, Automake would error out on this input:
+
+ at c Should be tested in primary-prefix-invalid-couples.test.
+ at example
+# Forbidden directory combinations, automake will error out on this.
+pkglib_PROGRAMS = foo
+doc_LIBRARIES = libquux.a
+ at end example
+
+ at noindent
+but it will succeed with this:
+
+ at c Keep in sync with primary-prefix-couples-documented-valid.test.
+ at example
+# Work around forbidden directory combinations. Do not use this
+# without a very good reason!
+my_execbindir = $(pkglibdir)
+my_doclibdir = $(docdir)
+my_execbin_PROGRAMS = foo
+my_doclib_LIBRARIES = libquux.a
+ at end example
+
+The @samp{exec} substring of the @samp{my_execbindir} variable lets
+the files be installed at the right time (@pxref{The Two Parts of
+Install}).
+
+ at cindex @samp{noinst_} primary prefix, definition
+ at vindex noinst_
+
+The special prefix @samp{noinst_} indicates that the objects in question
+should be built but not installed at all. This is usually used for
+objects required to build the rest of your package, for instance static
+libraries (@pxref{A Library}), or helper scripts.
+
+ at cindex @samp{check_} primary prefix, definition
+ at vindex check_
+
+The special prefix @samp{check_} indicates that the objects in question
+should not be built until the @samp{make check} command is run. Those
+objects are not installed either.
+
+The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
+ at samp{LTLIBRARIES}, @samp{LISP}, @samp{PYTHON}, @samp{JAVA},
+ at samp{SCRIPTS}, @samp{DATA}, @samp{HEADERS}, @samp{MANS}, and
+ at samp{TEXINFOS}.
+ at vindex PROGRAMS
+ at vindex LIBRARIES
+ at vindex LTLIBRARIES
+ at vindex LISP
+ at vindex PYTHON
+ at vindex JAVA
+ at vindex SCRIPTS
+ at vindex DATA
+ at vindex HEADERS
+ at vindex MANS
+ at vindex TEXINFOS
+
+Some primaries also allow additional prefixes that control other
+aspects of @command{automake}'s behavior. The currently defined prefixes
+are @samp{dist_}, @samp{nodist_}, @samp{nobase_}, and @samp{notrans_}.
+These prefixes are explained later (@pxref{Program and Library Variables})
+(@pxref{Man Pages}).
+
+
+ at node Length Limitations
+ at section Staying below the command line length limit
+
+ at cindex command line length limit
+ at cindex ARG_MAX
+
+Traditionally, most unix-like systems have a length limitation for the
+command line arguments and environment contents when creating new
+processes (see for example
+ at uref{http://www.in-ulm.de/@/~mascheck/@/various/@/argmax/} for an
+overview on this issue),
+which of course also applies to commands spawned by @command{make}.
+POSIX requires this limit to be at least 4096 bytes, and most modern
+systems have quite high limits (or are unlimited).
+
+In order to create portable Makefiles that do not trip over these
+limits, it is necessary to keep the length of file lists bounded.
+Unfortunately, it is not possible to do so fully transparently within
+Automake, so your help may be needed. Typically, you can split long
+file lists manually and use different installation directory names for
+each list. For example,
+
+ at example
+data_DATA = file1 @dots{} file at var{N} file at var{N+1} @dots{} file at var{2N}
+ at end example
+
+ at noindent
+may also be written as
+
+ at c Keep in sync with primary-prefix-couples-documented-valid.test.
+ at example
+data_DATA = file1 @dots{} file at var{N}
+data2dir = $(datadir)
+data2_DATA = file at var{N+1} @dots{} file at var{2N}
+ at end example
+
+ at noindent
+and will cause Automake to treat the two lists separately during
+ at code{make install}. See @ref{The Two Parts of Install} for choosing
+directory names that will keep the ordering of the two parts of
+installation Note that @code{make dist} may still only work on a host
+with a higher length limit in this example.
+
+Automake itself employs a couple of strategies to avoid long command
+lines. For example, when @samp{$@{srcdir@}/} is prepended to file
+names, as can happen with above @code{$(data_DATA)} lists, it limits
+the amount of arguments passed to external commands.
+
+Unfortunately, some system's @command{make} commands may prepend
+ at code{VPATH} prefixes like @samp{$@{srcdir@}/} to file names from the
+source tree automatically (@pxref{Automatic Rule Rewriting, , Automatic
+Rule Rewriting, autoconf, The Autoconf Manual}). In this case, the user
+may have to switch to use GNU Make, or refrain from using VPATH builds,
+in order to stay below the length limit.
+
+For libraries and programs built from many sources, convenience archives
+may be used as intermediates in order to limit the object list length
+(@pxref{Libtool Convenience Libraries}).
+
+
+ at node Canonicalization
+ at section How derived variables are named
+
+ at cindex canonicalizing Automake variables
+
+Sometimes a Makefile variable name is derived from some text the
+maintainer supplies. For instance, a program name listed in
+ at samp{_PROGRAMS} is rewritten into the name of a @samp{_SOURCES}
+variable. In cases like this, Automake canonicalizes the text, so that
+program names and the like do not have to follow Makefile variable naming
+rules. All characters in the name except for letters, numbers, the
+strudel (@@), and the underscore are turned into underscores when making
+variable references.
+
+For example, if your program is named @file{sniff-glue}, the derived
+variable name would be @samp{sniff_glue_SOURCES}, not
+ at samp{sniff-glue_SOURCES}. Similarly the sources for a library named
+ at file{libmumble++.a} should be listed in the
+ at samp{libmumble___a_SOURCES} variable.
+
+The strudel is an addition, to make the use of Autoconf substitutions in
+variable names less obfuscating.
+
+
+ at node User Variables
+ at section Variables reserved for the user
+
+ at cindex variables, reserved for the user
+ at cindex user variables
+
+Some @file{Makefile} variables are reserved by the GNU Coding Standards
+for the use of the ``user''---the person building the package. For
+instance, @code{CFLAGS} is one such variable.
+
+Sometimes package developers are tempted to set user variables such as
+ at code{CFLAGS} because it appears to make their job easier. However,
+the package itself should never set a user variable, particularly not
+to include switches that are required for proper compilation of the
+package. Since these variables are documented as being for the
+package builder, that person rightfully expects to be able to override
+any of these variables at build time.
+
+To get around this problem, Automake introduces an automake-specific
+shadow variable for each user flag variable. (Shadow variables are
+not introduced for variables like @code{CC}, where they would make no
+sense.) The shadow variable is named by prepending @samp{AM_} to the
+user variable's name. For instance, the shadow variable for
+ at code{YFLAGS} is @code{AM_YFLAGS}. The package maintainer---that is,
+the author(s) of the @file{Makefile.am} and @file{configure.ac}
+files---may adjust these shadow variables however necessary.
+
+ at xref{Flag Variables Ordering}, for more discussion about these
+variables and how they interact with per-target variables.
+
+ at node Auxiliary Programs
+ at section Programs automake might require
+
+ at cindex Programs, auxiliary
+ at cindex Auxiliary programs
+
+Automake sometimes requires helper programs so that the generated
+ at file{Makefile} can do its work properly. There are a fairly large
+number of them, and we list them here.
+
+Although all of these files are distributed and installed with
+Automake, a couple of them are maintained separately. The Automake
+copies are updated before each release, but we mention the original
+source in case you need more recent versions.
+
+ at table @code
+ at item ar-lib
+This is a wrapper primarily for the Microsoft lib archiver, to make
+it more POSIX-like.
+
+ at item ansi2knr.c
+ at itemx ansi2knr.1
+These two files are used for de-ANSI-fication support (they are
+deprecated now, and @emph{will be removed} in the next major Automake
+release; @pxref{ANSI}).
+
+ at item compile
+This is a wrapper for compilers that do not accept options @option{-c}
+and @option{-o} at the same time. It is only used when absolutely
+required. Such compilers are rare, with the Microsoft C/C++ Compiler
+as the most notable exception. This wrapper also makes the following
+common options available for that compiler, while performing file name
+translation where needed: @option{-I}, @option{-L}, @option{-l},
+ at option{-Wl,} and @option{-Xlinker}.
+
+ at item config.guess
+ at itemx config.sub
+These two programs compute the canonical triplets for the given build,
+host, or target architecture. These programs are updated regularly to
+support new architectures and fix probes broken by changes in new
+kernel versions. Each new release of Automake comes with up-to-date
+copies of these programs. If your copy of Automake is getting old,
+you are encouraged to fetch the latest versions of these files from
+ at url{http://savannah.gnu.org/git/?group=config} before making a
+release.
+
+ at item config-ml.in
+This file is not a program, it is a @file{configure} fragment used for
+multilib support (@pxref{Multilibs}). Since the Automake multilib
+support has been @emph{deprecated} and targeted for removal, this
+file is going to be @emph{removed from the Automake core} in the next
+major release. The master copy of this file is maintained in the GCC
+tree at @url{http://gcc.gnu.org/svn.html}.
+
+ at item depcomp
+This program understands how to run a compiler so that it will
+generate not only the desired output but also dependency information
+that is then used by the automatic dependency tracking feature
+(@pxref{Dependencies}).
+
+ at item elisp-comp
+This program is used to byte-compile Emacs Lisp code.
+
+ at item install-sh
+This is a replacement for the @command{install} program that works on
+platforms where @command{install} is unavailable or unusable.
+
+ at item mdate-sh
+This script is used to generate a @file{version.texi} file. It examines
+a file and prints some date information about it.
+
+ at item missing
+This wraps a number of programs that are typically only required by
+maintainers. If the program in question doesn't exist,
+ at command{missing} prints an informative warning and attempts to fix
+things so that the build can continue.
+
+ at item mkinstalldirs
+This script used to be a wrapper around @samp{mkdir -p}, which is not
+portable. Now we prefer to use @samp{install-sh -d} when @command{configure}
+finds that @samp{mkdir -p} does not work, this makes one less script to
+distribute.
+
+For backward compatibility @file{mkinstalldirs} is still used and
+distributed when @command{automake} finds it in a package. But it is no
+longer installed automatically, and it should be safe to remove it.
+
+ at item py-compile
+This is used to byte-compile Python scripts.
+
+ at item symlink-tree
+This program duplicates a tree of directories, using symbolic links
+instead of copying files. Such an operation is performed when building
+multilibs (@pxref{Multilibs}). Since the Automake multilib support has
+been @emph{deprecated} and targeted for removal, this file is going to
+be @emph{removed from the Automake core} in the next major release.
+The master copy of this file is maintained in the GCC tree at
+ at url{http://gcc.gnu.org/svn.html}.
+
+ at item texinfo.tex
+Not a program, this file is required for @samp{make dvi}, @samp{make
+ps} and @samp{make pdf} to work when Texinfo sources are in the
+package. The latest version can be downloaded from
+ at url{http://www.gnu.org/software/texinfo/}.
+
+ at item ylwrap
+This program wraps @command{lex} and @command{yacc} to rename their
+output files. It also ensures that, for instance, multiple
+ at command{yacc} instances can be invoked in a single directory in
+parallel.
+
+ at end table
+
+
+ at node Examples
+ at chapter Some example packages
+
+This section contains two small examples.
+
+The first example (@pxref{Complete}) assumes you have an existing
+project already using Autoconf, with handcrafted @file{Makefile}s, and
+that you want to convert it to using Automake. If you are discovering
+both tools, it is probably better that you look at the Hello World
+example presented earlier (@pxref{Hello World}).
+
+The second example (@pxref{true}) shows how two programs can be built
+from the same file, using different compilation parameters. It
+contains some technical digressions that are probably best skipped on
+first read.
+
+ at menu
+* Complete:: A simple example, start to finish
+* true:: Building true and false
+ at end menu
+
+
+ at node Complete
+ at section A simple example, start to finish
+
+ at cindex Complete example
+
+Let's suppose you just finished writing @code{zardoz}, a program to make
+your head float from vortex to vortex. You've been using Autoconf to
+provide a portability framework, but your @file{Makefile.in}s have been
+ad-hoc. You want to make them bulletproof, so you turn to Automake.
+
+ at cindex @code{AM_INIT_AUTOMAKE}, example use
+
+The first step is to update your @file{configure.ac} to include the
+commands that @command{automake} needs. The way to do this is to add an
+ at code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}:
+
+ at example
+AC_INIT([zardoz], [1.0])
+AM_INIT_AUTOMAKE
+ at dots{}
+ at end example
+
+Since your program doesn't have any complicating factors (e.g., it
+doesn't use @code{gettext}, it doesn't want to build a shared library),
+you're done with this part. That was easy!
+
+ at cindex @command{aclocal} program, introduction
+ at cindex @file{aclocal.m4}, preexisting
+ at cindex @file{acinclude.m4}, defined
+
+Now you must regenerate @file{configure}. But to do that, you'll need
+to tell @command{autoconf} how to find the new macro you've used. The
+easiest way to do this is to use the @command{aclocal} program to
+generate your @file{aclocal.m4} for you. But wait at dots{} maybe you
+already have an @file{aclocal.m4}, because you had to write some hairy
+macros for your program. The @command{aclocal} program lets you put
+your own macros into @file{acinclude.m4}, so simply rename and then
+run:
+
+ at example
+mv aclocal.m4 acinclude.m4
+aclocal
+autoconf
+ at end example
+
+ at cindex @command{zardoz} example
+
+Now it is time to write your @file{Makefile.am} for @code{zardoz}.
+Since @code{zardoz} is a user program, you want to install it where the
+rest of the user programs go: @code{bindir}. Additionally,
+ at code{zardoz} has some Texinfo documentation. Your @file{configure.ac}
+script uses @code{AC_REPLACE_FUNCS}, so you need to link against
+ at samp{$(LIBOBJS)}. So here's what you'd write:
+
+ at example
+bin_PROGRAMS = zardoz
+zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
+zardoz_LDADD = $(LIBOBJS)
+
+info_TEXINFOS = zardoz.texi
+ at end example
+
+Now you can run @samp{automake --add-missing} to generate your
+ at file{Makefile.in} and grab any auxiliary files you might need, and
+you're done!
+
+
+ at node true
+ at section Building true and false
+
+ at cindex Example, @command{false} and @command{true}
+ at cindex @command{false} Example
+ at cindex @command{true} Example
+
+Here is another, trickier example. It shows how to generate two
+programs (@code{true} and @code{false}) from the same source file
+(@file{true.c}). The difficult part is that each compilation of
+ at file{true.c} requires different @code{cpp} flags.
+
+ at example
+bin_PROGRAMS = true false
+false_SOURCES =
+false_LDADD = false.o
+
+true.o: true.c
+ $(COMPILE) -DEXIT_CODE=0 -c true.c
+
+false.o: true.c
+ $(COMPILE) -DEXIT_CODE=1 -o false.o -c true.c
+ at end example
+
+Note that there is no @code{true_SOURCES} definition. Automake will
+implicitly assume that there is a source file named @file{true.c}
+(@pxref{Default _SOURCES}), and
+define rules to compile @file{true.o} and link @file{true}. The
+ at samp{true.o: true.c} rule supplied by the above @file{Makefile.am},
+will override the Automake generated rule to build @file{true.o}.
+
+ at code{false_SOURCES} is defined to be empty---that way no implicit value
+is substituted. Because we have not listed the source of
+ at file{false}, we have to tell Automake how to link the program. This is
+the purpose of the @code{false_LDADD} line. A @code{false_DEPENDENCIES}
+variable, holding the dependencies of the @file{false} target will be
+automatically generated by Automake from the content of
+ at code{false_LDADD}.
+
+The above rules won't work if your compiler doesn't accept both
+ at option{-c} and @option{-o}. The simplest fix for this is to introduce a
+bogus dependency (to avoid problems with a parallel @command{make}):
+
+ at example
+true.o: true.c false.o
+ $(COMPILE) -DEXIT_CODE=0 -c true.c
+
+false.o: true.c
+ $(COMPILE) -DEXIT_CODE=1 -c true.c && mv true.o false.o
+ at end example
+
+As it turns out, there is also a much easier way to do this same task.
+Some of the above technique is useful enough that we've kept the
+example in the manual. However if you were to build @code{true} and
+ at code{false} in real life, you would probably use per-program
+compilation flags, like so:
+
+ at c Keep in sync with specflg7.test and specflg8.test.
+ at example
+bin_PROGRAMS = false true
+
+false_SOURCES = true.c
+false_CPPFLAGS = -DEXIT_CODE=1
+
+true_SOURCES = true.c
+true_CPPFLAGS = -DEXIT_CODE=0
+ at end example
+
+In this case Automake will cause @file{true.c} to be compiled twice,
+with different flags. In this instance, the names of the object files
+would be chosen by automake; they would be @file{false-true.o} and
+ at file{true-true.o}. (The name of the object files rarely matters.)
+
+ at node automake Invocation
+ at chapter Creating a @file{Makefile.in}
+ at c This node used to be named "Invoking automake". This @anchor
+ at c allows old links to still work.
+ at anchor{Invoking automake}
+
+ at cindex Multiple @file{configure.ac} files
+ at cindex Invoking @command{automake}
+ at cindex @command{automake}, invoking
+ at cindex Invocation of @command{automake}
+ at cindex @command{automake}, invocation
+
+To create all the @file{Makefile.in}s for a package, run the
+ at command{automake} program in the top level directory, with no
+arguments. @command{automake} will automatically find each
+appropriate @file{Makefile.am} (by scanning @file{configure.ac};
+ at pxref{configure}) and generate the corresponding @file{Makefile.in}.
+Note that @command{automake} has a rather simplistic view of what
+constitutes a package; it assumes that a package has only one
+ at file{configure.ac}, at the top. If your package has multiple
+ at file{configure.ac}s, then you must run @command{automake} in each
+directory holding a @file{configure.ac}. (Alternatively, you may rely
+on Autoconf's @command{autoreconf}, which is able to recurse your
+package tree and run @command{automake} where appropriate.)
+
+You can optionally give @command{automake} an argument; @file{.am} is
+appended to the argument and the result is used as the name of the
+input file. This feature is generally only used to automatically
+rebuild an out-of-date @file{Makefile.in}. Note that
+ at command{automake} must always be run from the topmost directory of a
+project, even if being used to regenerate the @file{Makefile.in} in
+some subdirectory. This is necessary because @command{automake} must
+scan @file{configure.ac}, and because @command{automake} uses the
+knowledge that a @file{Makefile.in} is in a subdirectory to change its
+behavior in some cases.
+
+ at vindex AUTOCONF
+Automake will run @command{autoconf} to scan @file{configure.ac} and
+its dependencies (i.e., @file{aclocal.m4} and any included file),
+therefore @command{autoconf} must be in your @env{PATH}. If there is
+an @env{AUTOCONF} variable in your environment it will be used
+instead of @command{autoconf}, this allows you to select a particular
+version of Autoconf. By the way, don't misunderstand this paragraph:
+ at command{automake} runs @command{autoconf} to @strong{scan} your
+ at file{configure.ac}, this won't build @file{configure} and you still
+have to run @command{autoconf} yourself for this purpose.
+
+ at cindex @command{automake} options
+ at cindex Options, @command{automake}
+ at cindex Strictness, command line
+
+ at command{automake} accepts the following options:
+
+ at cindex Extra files distributed with Automake
+ at cindex Files distributed with Automake
+ at cindex @file{config.guess}
+
+ at table @code
+ at item -a
+ at itemx --add-missing
+ at opindex -a
+ at opindex --add-missing
+Automake requires certain common files to exist in certain situations;
+for instance, @file{config.guess} is required if @file{configure.ac} invokes
+ at code{AC_CANONICAL_HOST}. Automake is distributed with several of these
+files (@pxref{Auxiliary Programs}); this option will cause the missing
+ones to be automatically added to the package, whenever possible. In
+general if Automake tells you a file is missing, try using this option.
+By default Automake tries to make a symbolic link pointing to its own
+copy of the missing file; this can be changed with @option{--copy}.
+
+Many of the potentially-missing files are common scripts whose
+location may be specified via the @code{AC_CONFIG_AUX_DIR} macro.
+Therefore, @code{AC_CONFIG_AUX_DIR}'s setting affects whether a
+file is considered missing, and where the missing file is added
+(@pxref{Optional}).
+
+In some strictness modes, additional files are installed, see @ref{Gnits}
+for more information.
+
+ at item --libdir=@var{dir}
+ at opindex --libdir
+Look for Automake data files in directory @var{dir} instead of in the
+installation directory. This is typically used for debugging.
+
+ at item -c
+ at opindex -c
+ at itemx --copy
+ at opindex --copy
+When used with @option{--add-missing}, causes installed files to be
+copied. The default is to make a symbolic link.
+
+ at item --cygnus
+ at opindex --cygnus
+Causes the generated @file{Makefile.in}s to follow Cygnus rules, instead
+of GNU or Gnits rules. For more information, see @ref{Cygnus}.
+Note that @emph{this mode of operation is deprecated, and will be removed}
+in a future Automake release.
+
+ at item -f
+ at opindex -f
+ at itemx --force-missing
+ at opindex --force-missing
+When used with @option{--add-missing}, causes standard files to be reinstalled
+even if they already exist in the source tree. This involves removing
+the file from the source tree before creating the new symlink (or, with
+ at option{--copy}, copying the new file).
+
+ at item --foreign
+ at opindex --foreign
+Set the global strictness to @option{foreign}. For more information, see
+ at ref{Strictness}.
+
+ at item --gnits
+ at opindex --gnits
+Set the global strictness to @option{gnits}. For more information, see
+ at ref{Gnits}.
+
+ at item --gnu
+ at opindex --gnu
+Set the global strictness to @option{gnu}. For more information, see
+ at ref{Gnits}. This is the default strictness.
+
+ at item --help
+ at opindex --help
+Print a summary of the command line options and exit.
+
+ at item -i
+ at itemx --ignore-deps
+ at opindex -i
+This disables the dependency tracking feature in generated
+ at file{Makefile}s; see @ref{Dependencies}.
+
+ at item --include-deps
+ at opindex --include-deps
+This enables the dependency tracking feature. This feature is enabled
+by default. This option is provided for historical reasons only and
+probably should not be used.
+
+ at item --no-force
+ at opindex --no-force
+Ordinarily @command{automake} creates all @file{Makefile.in}s mentioned in
+ at file{configure.ac}. This option causes it to only update those
+ at file{Makefile.in}s that are out of date with respect to one of their
+dependents.
+
+ at item -o @var{dir}
+ at itemx --output-dir=@var{dir}
+ at opindex -o
+ at opindex --output-dir
+Put the generated @file{Makefile.in} in the directory @var{dir}.
+Ordinarily each @file{Makefile.in} is created in the directory of the
+corresponding @file{Makefile.am}. This option is deprecated and will be
+removed in a future release.
+
+ at item -v
+ at itemx --verbose
+ at opindex -v
+ at opindex --verbose
+Cause Automake to print information about which files are being read or
+created.
+
+ at item --version
+ at opindex --version
+Print the version number of Automake and exit.
+
+ at item -W CATEGORY
+ at itemx --warnings=@var{category}
+ at opindex -W
+ at opindex --warnings
+Output warnings falling in @var{category}. @var{category} can be
+one of:
+ at table @code
+ at item gnu
+warnings related to the GNU Coding Standards
+(@pxref{Top, , , standards, The GNU Coding Standards}).
+ at item obsolete
+obsolete features or constructions
+ at item override
+user redefinitions of Automake rules or variables
+ at item portability
+portability issues (e.g., use of @command{make} features that are
+known to be not portable)
+ at item extra-portability
+extra portability issues related to obscure tools. One example of such
+a tool is the Microsoft @command{lib} archiver.
+ at item syntax
+weird syntax, unused variables, typos
+ at item unsupported
+unsupported or incomplete features
+ at item all
+all the warnings
+ at item none
+turn off all the warnings
+ at item error
+treat warnings as errors
+ at end table
+
+A category can be turned off by prefixing its name with @samp{no-}. For
+instance, @option{-Wno-syntax} will hide the warnings about unused
+variables.
+
+The categories output by default are @samp{syntax} and
+ at samp{unsupported}. Additionally, @samp{gnu} and @samp{portability}
+are enabled in @option{--gnu} and @option{--gnits} strictness.
+On the other hand, the @option{silent-rules} options (@pxref{Options})
+turns off portability warnings about recursive variable expansions.
+
+ at c Checked by extra-portability.test
+Turning off @samp{portability} will also turn off @samp{extra-portability},
+and similarly turning on @samp{extra-portability} will also turn on
+ at samp{portability}. However, turning on @samp{portability} or turning
+off @samp{extra-portability} will not affect the other category.
+
+ at vindex WARNINGS
+The environment variable @env{WARNINGS} can contain a comma separated
+list of categories to enable. It will be taken into account before the
+command-line switches, this way @option{-Wnone} will also ignore any
+warning category enabled by @env{WARNINGS}. This variable is also used
+by other tools like @command{autoconf}; unknown categories are ignored
+for this reason.
+
+ at end table
+
+ at vindex AUTOMAKE_JOBS
+If the environment variable @env{AUTOMAKE_JOBS} contains a positive
+number, it is taken as the maximum number of Perl threads to use in
+ at command{automake} for generating multiple @file{Makefile.in} files
+concurrently. This is an experimental feature.
+
+
+ at node configure
+ at chapter Scanning @file{configure.ac}, using @command{aclocal}
+
+ at cindex @file{configure.ac}, scanning
+ at cindex Scanning @file{configure.ac}
+ at cindex Using @command{aclocal}
+ at cindex @command{aclocal}, using
+
+Automake scans the package's @file{configure.ac} to determine certain
+information about the package. Some @command{autoconf} macros are required
+and some variables must be defined in @file{configure.ac}. Automake
+will also use information from @file{configure.ac} to further tailor its
+output.
+
+Automake also supplies some Autoconf macros to make the maintenance
+easier. These macros can automatically be put into your
+ at file{aclocal.m4} using the @command{aclocal} program.
+
+ at menu
+* Requirements:: Configuration requirements
+* Optional:: Other things Automake recognizes
+* aclocal Invocation:: Auto-generating aclocal.m4
+* Macros:: Autoconf macros supplied with Automake
+ at end menu
+
+
+ at node Requirements
+ at section Configuration requirements
+
+ at cindex Automake requirements
+ at cindex Requirements of Automake
+
+ at acindex AM_INIT_AUTOMAKE
+The one real requirement of Automake is that your @file{configure.ac}
+call @code{AM_INIT_AUTOMAKE}. This macro does several things that are
+required for proper Automake operation (@pxref{Macros}).
+
+Here are the other macros that Automake requires but which are not run
+by @code{AM_INIT_AUTOMAKE}:
+
+ at table @code
+ at item AC_CONFIG_FILES
+ at itemx AC_OUTPUT
+ at acindex AC_CONFIG_FILES
+ at acindex AC_OUTPUT
+These two macros are usually invoked as follows near the end of
+ at file{configure.ac}.
+
+ at example
+ at dots{}
+AC_CONFIG_FILES([
+ Makefile
+ doc/Makefile
+ src/Makefile
+ src/lib/Makefile
+ @dots{}
+])
+AC_OUTPUT
+ at end example
+
+Automake uses these to determine which files to create (@pxref{Output, ,
+Creating Output Files, autoconf, The Autoconf Manual}). A listed file
+is considered to be an Automake generated @file{Makefile} if there
+exists a file with the same name and the @file{.am} extension appended.
+Typically, @samp{AC_CONFIG_FILES([foo/Makefile])} will cause Automake to
+generate @file{foo/Makefile.in} if @file{foo/Makefile.am} exists.
+
+When using @code{AC_CONFIG_FILES} with multiple input files, as in
+
+ at example
+AC_CONFIG_FILES([Makefile:top.in:Makefile.in:bot.in])
+ at end example
+
+ at noindent
+ at command{automake} will generate the first @file{.in} input file for
+which a @file{.am} file exists. If no such file exists the output
+file is not considered to be generated by Automake.
+
+Files created by @code{AC_CONFIG_FILES}, be they Automake
+ at file{Makefile}s or not, are all removed by @samp{make distclean}.
+Their inputs are automatically distributed, unless they
+are the output of prior @code{AC_CONFIG_FILES} commands.
+Finally, rebuild rules are generated in the Automake @file{Makefile}
+existing in the subdirectory of the output file, if there is one, or
+in the top-level @file{Makefile} otherwise.
+
+The above machinery (cleaning, distributing, and rebuilding) works
+fine if the @code{AC_CONFIG_FILES} specifications contain only
+literals. If part of the specification uses shell variables,
+ at command{automake} will not be able to fulfill this setup, and you will
+have to complete the missing bits by hand. For instance, on
+
+ at c Keep in sync with output11.test.
+ at example
+file=input
+ at dots{}
+AC_CONFIG_FILES([output:$file],, [file=$file])
+ at end example
+
+ at noindent
+ at command{automake} will output rules to clean @file{output}, and
+rebuild it. However the rebuild rule will not depend on @file{input},
+and this file will not be distributed either. (You must add
+ at samp{EXTRA_DIST = input} to your @file{Makefile.am} if @file{input} is a
+source file.)
+
+Similarly
+
+ at c Keep in sync with output11.test.
+ at example
+file=output
+file2=out:in
+ at dots{}
+AC_CONFIG_FILES([$file:input],, [file=$file])
+AC_CONFIG_FILES([$file2],, [file2=$file2])
+ at end example
+
+ at noindent
+will only cause @file{input} to be distributed. No file will be
+cleaned automatically (add @samp{DISTCLEANFILES = output out}
+yourself), and no rebuild rule will be output.
+
+Obviously @command{automake} cannot guess what value @samp{$file} is
+going to hold later when @file{configure} is run, and it cannot use
+the shell variable @samp{$file} in a @file{Makefile}. However, if you
+make reference to @samp{$file} as @samp{$@{file@}} (i.e., in a way
+that is compatible with @command{make}'s syntax) and furthermore use
+ at code{AC_SUBST} to ensure that @samp{$@{file@}} is meaningful in a
+ at file{Makefile}, then @command{automake} will be able to use
+ at samp{$@{file@}} to generate all these rules. For instance, here is
+how the Automake package itself generates versioned scripts for its
+test suite:
+
+ at example
+AC_SUBST([APIVERSION], @dots{})
+ at dots{}
+AC_CONFIG_FILES(
+ [tests/aclocal-$@{APIVERSION@}:tests/aclocal.in],
+ [chmod +x tests/aclocal-$@{APIVERSION@}],
+ [APIVERSION=$APIVERSION])
+AC_CONFIG_FILES(
+ [tests/automake-$@{APIVERSION@}:tests/automake.in],
+ [chmod +x tests/automake-$@{APIVERSION@}])
+ at end example
+
+ at noindent
+Here cleaning, distributing, and rebuilding are done automatically,
+because @samp{$@{APIVERSION@}} is known at @command{make}-time.
+
+Note that you should not use shell variables to declare
+ at file{Makefile} files for which @command{automake} must create
+ at file{Makefile.in}. Even @code{AC_SUBST} does not help here, because
+ at command{automake} needs to know the file name when it runs in order
+to check whether @file{Makefile.am} exists. (In the very hairy case
+that your setup requires such use of variables, you will have to tell
+Automake which @file{Makefile.in}s to generate on the command-line.)
+
+It is possible to let @command{automake} emit conditional rules for
+ at code{AC_CONFIG_FILES} with the help of @code{AM_COND_IF}
+(@pxref{Optional}).
+
+To summarize:
+ at itemize @bullet
+ at item
+Use literals for @file{Makefile}s, and for other files whenever possible.
+ at item
+Use @samp{$file} (or @samp{$@{file@}} without @samp{AC_SUBST([file])})
+for files that @command{automake} should ignore.
+ at item
+Use @samp{$@{file@}} and @samp{AC_SUBST([file])} for files
+that @command{automake} should not ignore.
+ at end itemize
+
+ at end table
+
+
+ at node Optional
+ at section Other things Automake recognizes
+
+ at cindex Macros Automake recognizes
+ at cindex Recognized macros by Automake
+
+Every time Automake is run it calls Autoconf to trace
+ at file{configure.ac}. This way it can recognize the use of certain
+macros and tailor the generated @file{Makefile.in} appropriately.
+Currently recognized macros and their effects are:
+
+ at ftable @code
+ at item AC_CANONICAL_BUILD
+ at itemx AC_CANONICAL_HOST
+ at itemx AC_CANONICAL_TARGET
+ at vindex build_triplet
+ at vindex host_triplet
+ at vindex target_triplet
+Automake will ensure that @file{config.guess} and @file{config.sub}
+exist. Also, the @file{Makefile} variables @code{build_triplet},
+ at code{host_triplet} and @code{target_triplet} are introduced. See
+ at ref{Canonicalizing, , Getting the Canonical System Type, autoconf,
+The Autoconf Manual}.
+
+ at item AC_CONFIG_AUX_DIR
+Automake will look for various helper scripts, such as
+ at file{install-sh}, in the directory named in this macro invocation.
+ at c This list is accurate relative to version 1.8
+(The full list of scripts is: @file{ar-lib}, @file{config.guess},
+ at file{config.sub}, @file{depcomp}, @file{elisp-comp}, @file{compile},
+ at file{install-sh}, @file{ltmain.sh}, @file{mdate-sh}, @file{missing},
+ at file{mkinstalldirs}, @file{py-compile}, @file{texinfo.tex}, and
+ at file{ylwrap}.) Not all scripts are always searched for; some scripts
+will only be sought if the generated @file{Makefile.in} requires them.
+
+If @code{AC_CONFIG_AUX_DIR} is not given, the scripts are looked for in
+their standard locations. For @file{mdate-sh},
+ at file{texinfo.tex}, and @file{ylwrap}, the standard location is the
+source directory corresponding to the current @file{Makefile.am}. For
+the rest, the standard location is the first one of @file{.}, @file{..},
+or @file{../..} (relative to the top source directory) that provides any
+one of the helper scripts. @xref{Input, , Finding `configure' Input,
+autoconf, The Autoconf Manual}.
+
+Required files from @code{AC_CONFIG_AUX_DIR} are automatically
+distributed, even if there is no @file{Makefile.am} in this directory.
+
+ at item AC_CONFIG_LIBOBJ_DIR
+Automake will require the sources file declared with
+ at code{AC_LIBSOURCE} (see below) in the directory specified by this
+macro.
+
+ at item AC_CONFIG_HEADERS
+Automake will generate rules to rebuild these headers. Older versions
+of Automake required the use of @code{AM_CONFIG_HEADER}
+(@pxref{Macros}); this is no longer the case.
+
+As with @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
+specification using shell variables will be ignored as far as
+cleaning, distributing, and rebuilding is concerned.
+
+ at item AC_CONFIG_LINKS
+Automake will generate rules to remove @file{configure} generated
+links on @samp{make distclean} and to distribute named source files as
+part of @samp{make dist}.
+
+As for @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
+specification using shell variables will be ignored as far as cleaning
+and distributing is concerned. (There are no rebuild rules for links.)
+
+ at item AC_LIBOBJ
+ at itemx AC_LIBSOURCE
+ at itemx AC_LIBSOURCES
+ at vindex LIBOBJS
+Automake will automatically distribute any file listed in
+ at code{AC_LIBSOURCE} or @code{AC_LIBSOURCES}.
+
+Note that the @code{AC_LIBOBJ} macro calls @code{AC_LIBSOURCE}. So if
+an Autoconf macro is documented to call @samp{AC_LIBOBJ([file])}, then
+ at file{file.c} will be distributed automatically by Automake. This
+encompasses many macros like @code{AC_FUNC_ALLOCA},
+ at code{AC_FUNC_MEMCMP}, @code{AC_REPLACE_FUNCS}, and others.
+
+By the way, direct assignments to @code{LIBOBJS} are no longer
+supported. You should always use @code{AC_LIBOBJ} for this purpose.
+ at xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
+autoconf, The Autoconf Manual}.
+
+ at item AC_PROG_RANLIB
+This is required if any libraries are built in the package.
+ at xref{Particular Programs, , Particular Program Checks, autoconf, The
+Autoconf Manual}.
+
+ at item AC_PROG_CXX
+This is required if any C++ source is included. @xref{Particular
+Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
+
+ at item AC_PROG_OBJC
+This is required if any Objective C source is included. @xref{Particular
+Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
+
+ at item AC_PROG_F77
+This is required if any Fortran 77 source is included. This macro is
+distributed with Autoconf version 2.13 and later. @xref{Particular
+Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
+
+ at item AC_F77_LIBRARY_LDFLAGS
+This is required for programs and shared libraries that are a mixture of
+languages that include Fortran 77 (@pxref{Mixing Fortran 77 With C and
+C++}). @xref{Macros, , Autoconf macros supplied with Automake}.
+
+ at item AC_FC_SRCEXT
+Automake will add the flags computed by @code{AC_FC_SRCEXT} to compilation
+of files with the respective source extension (@pxref{Fortran Compiler, ,
+Fortran Compiler Characteristics, autoconf, The Autoconf Manual}).
+
+ at item AC_PROG_FC
+This is required if any Fortran 90/95 source is included. This macro is
+distributed with Autoconf version 2.58 and later. @xref{Particular
+Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
+
+ at item AC_PROG_LIBTOOL
+Automake will turn on processing for @command{libtool} (@pxref{Top, ,
+Introduction, libtool, The Libtool Manual}).
+
+ at item AC_PROG_YACC
+ at vindex YACC
+If a Yacc source file is seen, then you must either use this macro or
+define the variable @code{YACC} in @file{configure.ac}. The former is
+preferred (@pxref{Particular Programs, , Particular Program Checks,
+autoconf, The Autoconf Manual}).
+
+ at item AC_PROG_LEX
+If a Lex source file is seen, then this macro must be used.
+ at xref{Particular Programs, , Particular Program Checks, autoconf, The
+Autoconf Manual}.
+
+ at item AC_REQUIRE_AUX_FILE
+For each @code{AC_REQUIRE_AUX_FILE([@var{file}])},
+ at command{automake} will ensure that @file{@var{file}} exists in the
+aux directory, and will complain otherwise. It
+will also automatically distribute the file. This macro should be
+used by third-party Autoconf macros that require some supporting
+files in the aux directory specified with @code{AC_CONFIG_AUX_DIR}
+above. @xref{Input, , Finding @command{configure} Input, autoconf,
+The Autoconf Manual}.
+
+ at item AC_SUBST
+The first argument is automatically defined as a variable in each
+generated @file{Makefile.in}, unless @code{AM_SUBST_NOTMAKE} is also
+used for this variable. @xref{Setting Output Variables, , Setting
+Output Variables, autoconf, The Autoconf Manual}.
+
+For every substituted variable @var{var}, @command{automake} will add
+a line @code{@var{var} = @var{value}} to each @file{Makefile.in} file.
+Many Autoconf macros invoke @code{AC_SUBST} to set output variables
+this way, e.g., @code{AC_PATH_XTRA} defines @code{X_CFLAGS} and
+ at code{X_LIBS}. Thus, you can access these variables as
+ at code{$(X_CFLAGS)} and @code{$(X_LIBS)} in any @file{Makefile.am}
+if @code{AC_PATH_XTRA} is called.
+
+ at item AM_C_PROTOTYPES
+This is required when using the deprecated de-ANSI-fication feature;
+ at pxref{ANSI}. @emph{It will be removed} in the next major Automake
+release.
+
+ at item AM_CONDITIONAL
+This introduces an Automake conditional (@pxref{Conditionals}).
+
+ at item AM_COND_IF
+This macro allows @code{automake} to detect subsequent access within
+ at file{configure.ac} to a conditional previously introduced with
+ at code{AM_CONDITIONAL}, thus enabling conditional @code{AC_CONFIG_FILES}
+(@pxref{Usage of Conditionals}).
+
+ at item AM_GNU_GETTEXT
+This macro is required for packages that use GNU gettext
+(@pxref{gettext}). It is distributed with gettext. If Automake sees
+this macro it ensures that the package meets some of gettext's
+requirements.
+
+ at item AM_GNU_GETTEXT_INTL_SUBDIR
+This macro specifies that the @file{intl/} subdirectory is to be built,
+even if the @code{AM_GNU_GETTEXT} macro was invoked with a first argument
+of @samp{external}.
+
+ at item AM_MAINTAINER_MODE(@ovar{default-mode})
+ at opindex --enable-maintainer-mode
+ at opindex --disable-maintainer-mode
+This macro adds an @option{--enable-maintainer-mode} option to
+ at command{configure}. If this is used, @command{automake} will cause
+``maintainer-only'' rules to be turned off by default in the
+generated @file{Makefile.in}s, unless @var{default-mode} is
+ at samp{enable}. This macro defines the @code{MAINTAINER_MODE}
+conditional, which you can use in your own @file{Makefile.am}.
+ at xref{maintainer-mode}.
+
+ at item AM_SUBST_NOTMAKE(@var{var})
+Prevent Automake from defining a variable @var{var}, even if it is
+substituted by @command{config.status}. Normally, Automake defines a
+ at command{make} variable for each @command{configure} substitution,
+i.e., for each @code{AC_SUBST([@var{var}])}. This macro prevents that
+definition from Automake. If @code{AC_SUBST} has not been called
+for this variable, then @code{AM_SUBST_NOTMAKE} has no effects.
+Preventing variable definitions may be useful for substitution of
+multi-line values, where @code{@var{var} = @@@var{value}@@} might yield
+unintended results.
+
+ at item m4_include
+Files included by @file{configure.ac} using this macro will be
+detected by Automake and automatically distributed. They will also
+appear as dependencies in @file{Makefile} rules.
+
+ at code{m4_include} is seldom used by @file{configure.ac} authors, but
+can appear in @file{aclocal.m4} when @command{aclocal} detects that
+some required macros come from files local to your package (as opposed to
+macros installed in a system-wide directory, @pxref{aclocal Invocation}).
+
+ at end ftable
+
+ at node aclocal Invocation
+ at section Auto-generating aclocal.m4
+ at c This node used to be named "Invoking automake". This @anchor
+ at c allows old links to still work.
+ at anchor{Invoking aclocal}
+
+ at cindex Invocation of @command{aclocal}
+ at cindex @command{aclocal}, Invocation
+ at cindex Invoking @command{aclocal}
+ at cindex @command{aclocal}, Invoking
+
+Automake includes a number of Autoconf macros that can be used in
+your package (@pxref{Macros}); some of them are actually required by
+Automake in certain situations. These macros must be defined in your
+ at file{aclocal.m4}; otherwise they will not be seen by
+ at command{autoconf}.
+
+The @command{aclocal} program will automatically generate
+ at file{aclocal.m4} files based on the contents of @file{configure.ac}.
+This provides a convenient way to get Automake-provided macros,
+without having to search around. The @command{aclocal} mechanism
+allows other packages to supply their own macros (@pxref{Extending
+aclocal}). You can also use it to maintain your own set of custom
+macros (@pxref{Local Macros}).
+
+At startup, @command{aclocal} scans all the @file{.m4} files it can
+find, looking for macro definitions (@pxref{Macro Search Path}). Then
+it scans @file{configure.ac}. Any mention of one of the macros found
+in the first step causes that macro, and any macros it in turn
+requires, to be put into @file{aclocal.m4}.
+
+ at emph{Putting} the file that contains the macro definition into
+ at file{aclocal.m4} is usually done by copying the entire text of this
+file, including unused macro definitions as well as both @samp{#} and
+ at samp{dnl} comments. If you want to make a comment that will be
+completely ignored by @command{aclocal}, use @samp{##} as the comment
+leader.
+
+When a file selected by @command{aclocal} is located in a subdirectory
+specified as a relative search path with @command{aclocal}'s @option{-I}
+argument, @command{aclocal} assumes the file belongs to the package
+and uses @code{m4_include} instead of copying it into
+ at file{aclocal.m4}. This makes the package smaller, eases dependency
+tracking, and cause the file to be distributed automatically.
+(@xref{Local Macros}, for an example.) Any macro that is found in a
+system-wide directory, or via an absolute search path will be copied.
+So use @samp{-I `pwd`/reldir} instead of @samp{-I reldir} whenever
+some relative directory should be considered outside the package.
+
+The contents of @file{acinclude.m4}, if this file exists, are also
+automatically included in @file{aclocal.m4}. We recommend against
+using @file{acinclude.m4} in new packages (@pxref{Local Macros}).
+
+ at vindex AUTOM4TE
+ at cindex autom4te
+While computing @file{aclocal.m4}, @command{aclocal} runs
+ at command{autom4te} (@pxref{Using autom4te, , Using @command{Autom4te},
+autoconf, The Autoconf Manual}) in order to trace the macros that are
+really used, and omit from @file{aclocal.m4} all macros that are
+mentioned but otherwise unexpanded (this can happen when a macro is
+called conditionally). @command{autom4te} is expected to be in the
+ at env{PATH}, just as @command{autoconf}. Its location can be
+overridden using the @env{AUTOM4TE} environment variable.
+
+ at menu
+* aclocal Options:: Options supported by aclocal
+* Macro Search Path:: How aclocal finds .m4 files
+* Extending aclocal:: Writing your own aclocal macros
+* Local Macros:: Organizing local macros
+* Serials:: Serial lines in Autoconf macros
+* Future of aclocal:: aclocal's scheduled death
+ at end menu
+
+ at node aclocal Options
+ at subsection aclocal Options
+
+ at cindex @command{aclocal}, Options
+ at cindex Options, @command{aclocal}
+
+ at command{aclocal} accepts the following options:
+
+ at table @code
+ at item --automake-acdir=@var{dir}
+ at opindex --automake-acdir
+Look for the automake-provided macro files in @var{dir} instead of
+in the installation directory. This is typically used for debugging.
+
+ at item --system-acdir=@var{dir}
+ at opindex --system-acdir
+Look for the system-wide third-party macro files (and the special
+ at file{dirlist} file) in @var{dir} instead of in the installation
+directory. This is typically used for debugging.
+
+ at item --acdir=@var{dir}
+ at opindex --acdir
+ at emph{Deprecated} shorthand for ``@option{--automake-acdir=@var{dir}
+--system-acdir=@var{dir}}''. Will be removed in future aclocal versions.
+
+ at item --diff[=@var{command}]
+ at opindex --diff
+Run @var{command} on M4 file that would be installed or overwritten
+by @option{--install}. The default @var{command} is @samp{diff -u}.
+This option implies @option{--install} and @option{--dry-run}.
+
+ at item --dry-run
+ at opindex --dry-run
+Do not actually overwrite (or create) @file{aclocal.m4} and M4
+files installed by @option{--install}.
+
+ at item --help
+ at opindex --help
+Print a summary of the command line options and exit.
+
+ at item -I @var{dir}
+ at opindex -I
+Add the directory @var{dir} to the list of directories searched for
+ at file{.m4} files.
+
+ at item --install
+ at opindex --install
+Install system-wide third-party macros into the first directory
+specified with @samp{-I @var{dir}} instead of copying them in the
+output file.
+ at c The following semantics is checked by `aclocal-install-absdir.test'.
+Note that this will happen also if @var{dir} is an absolute path.
+
+ at cindex serial number and @option{--install}
+When this option is used, and only when this option is used,
+ at command{aclocal} will also honor @samp{#serial @var{number}} lines
+that appear in macros: an M4 file is ignored if there exists another
+M4 file with the same basename and a greater serial number in the
+search path (@pxref{Serials}).
+
+ at item --force
+ at opindex --force
+Always overwrite the output file. The default is to overwrite the output
+file only when really needed, i.e., when its contents changes or if one
+of its dependencies is younger.
+
+This option forces the update of @file{aclocal.m4} (or the file
+specified with @file{--output} below) and only this file, it has
+absolutely no influence on files that may need to be installed by
+ at option{--install}.
+
+ at item --output=@var{file}
+ at opindex --output
+Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
+
+ at item --print-ac-dir
+ at opindex --print-ac-dir
+Prints the name of the directory that @command{aclocal} will search to
+find third-party @file{.m4} files. When this option is given, normal
+processing is suppressed. This option was used @emph{in the past} by
+third-party packages to determine where to install @file{.m4} macro
+files, but @emph{this usage is today discouraged}, since it causes
+ at samp{$(prefix)} not to be thoroughly honoured (which violates the
+GNU Coding Standards), and a similar semantics can be better obtained
+with the @env{ACLOCAL_PATH} environment variable; @pxref{Extending aclocal}.
+
+ at item --verbose
+ at opindex --verbose
+Print the names of the files it examines.
+
+ at item --version
+ at opindex --version
+Print the version number of Automake and exit.
+
+ at item -W CATEGORY
+ at item --warnings=@var{category}
+ at opindex -W
+ at opindex --warnings
+Output warnings falling in @var{category}. @var{category} can be
+one of:
+ at table @code
+ at item syntax
+dubious syntactic constructs, underquoted macros, unused macros, etc.
+ at item unsupported
+unknown macros
+ at item all
+all the warnings, this is the default
+ at item none
+turn off all the warnings
+ at item error
+treat warnings as errors
+ at end table
+
+All warnings are output by default.
+
+ at vindex WARNINGS
+The environment variable @env{WARNINGS} is honored in the same
+way as it is for @command{automake} (@pxref{automake Invocation}).
+
+ at end table
+
+ at node Macro Search Path
+ at subsection Macro Search Path
+
+ at cindex Macro search path
+ at cindex @command{aclocal} search path
+
+By default, @command{aclocal} searches for @file{.m4} files in the following
+directories, in this order:
+
+ at table @code
+ at item @var{acdir-APIVERSION}
+This is where the @file{.m4} macros distributed with Automake itself
+are stored. @var{APIVERSION} depends on the Automake release used;
+for example, for Automake 1.11.x, @var{APIVERSION} = @code{1.11}.
+
+ at item @var{acdir}
+This directory is intended for third party @file{.m4} files, and is
+configured when @command{automake} itself is built. This is
+ at file{@@datadir@@/aclocal/}, which typically
+expands to @file{$@{prefix@}/share/aclocal/}. To find the compiled-in
+value of @var{acdir}, use the @option{--print-ac-dir} option
+(@pxref{aclocal Options}).
+ at end table
+
+As an example, suppose that @command{automake-1.11.2} was configured with
+ at option{--prefix=@-/usr/local}. Then, the search path would be:
+
+ at enumerate
+ at item @file{/usr/local/share/aclocal-1.11.2/}
+ at item @file{/usr/local/share/aclocal/}
+ at end enumerate
+
+The paths for the @var{acdir} and @var{acdir-APIVERSION} directories can
+be changed respectively through aclocal options @option{--system-acdir}
+and @option{--automake-acdir} (@pxref{aclocal Options}). Note however
+that these options are only intended for use by the internal Automake
+test suite, or for debugging under highly unusual situations; they are
+not ordinarily needed by end-users.
+
+As explained in (@pxref{aclocal Options}), there are several options that
+can be used to change or extend this search path.
+
+ at subsubheading Modifying the Macro Search Path: @samp{-I @var{dir}}
+
+Any extra directories specified using @option{-I} options
+(@pxref{aclocal Options}) are @emph{prepended} to this search list. Thus,
+ at samp{aclocal -I /foo -I /bar} results in the following search path:
+
+ at enumerate
+ at item @file{/foo}
+ at item @file{/bar}
+ at item @var{acdir}- at var{APIVERSION}
+ at item @var{acdir}
+ at end enumerate
+
+ at subsubheading Modifying the Macro Search Path: @file{dirlist}
+ at cindex @file{dirlist}
+
+There is a third mechanism for customizing the search path. If a
+ at file{dirlist} file exists in @var{acdir}, then that file is assumed to
+contain a list of directory patterns, one per line. @command{aclocal}
+expands these patterns to directory names, and adds them to the search
+list @emph{after} all other directories. @file{dirlist} entries may
+use shell wildcards such as @samp{*}, @samp{?}, or @code{[...]}.
+
+For example, suppose
+ at file{@var{acdir}/dirlist} contains the following:
+
+ at example
+/test1
+/test2
+/test3*
+ at end example
+
+ at noindent
+and that @command{aclocal} was called with the @samp{-I /foo -I /bar} options.
+Then, the search path would be
+
+ at c @code looks better than @file here
+ at enumerate
+ at item @code{/foo}
+ at item @code{/bar}
+ at item @var{acdir}- at var{APIVERSION}
+ at item @var{acdir}
+ at item @code{/test1}
+ at item @code{/test2}
+ at end enumerate
+
+ at noindent
+and all directories with path names starting with @code{/test3}.
+
+If the @option{--system-acdir=@var{dir}} option is used, then
+ at command{aclocal} will search for the @file{dirlist} file in
+ at var{dir}; but remember the warnings above against the use of
+ at option{--system-acdir}.
+
+ at file{dirlist} is useful in the following situation: suppose that
+ at command{automake} version @code{1.11.2} is installed with
+ at samp{--prefix=/usr} by the system vendor. Thus, the default search
+directories are
+
+ at c @code looks better than @file here
+ at enumerate
+ at item @code{/usr/share/aclocal-1.11/}
+ at item @code{/usr/share/aclocal/}
+ at end enumerate
+
+However, suppose further that many packages have been manually
+installed on the system, with $prefix=/usr/local, as is typical. In
+that case, many of these ``extra'' @file{.m4} files are in
+ at file{/usr/local/share/aclocal}. The only way to force
+ at file{/usr/bin/aclocal} to find these ``extra'' @file{.m4} files is to
+always call @samp{aclocal -I /usr/local/share/aclocal}. This is
+inconvenient. With @file{dirlist}, one may create a file
+ at file{/usr/share/aclocal/dirlist} containing only the single line
+
+ at example
+/usr/local/share/aclocal
+ at end example
+
+Now, the ``default'' search path on the affected system is
+
+ at c @code looks better than @file here
+ at enumerate
+ at item @code{/usr/share/aclocal-1.11/}
+ at item @code{/usr/share/aclocal/}
+ at item @code{/usr/local/share/aclocal/}
+ at end enumerate
+
+without the need for @option{-I} options; @option{-I} options can be reserved
+for project-specific needs (@file{my-source-dir/m4/}), rather than
+using it to work around local system-dependent tool installation
+directories.
+
+Similarly, @file{dirlist} can be handy if you have installed a local
+copy of Automake in your account and want @command{aclocal} to look for
+macros installed at other places on the system.
+
+ at anchor{ACLOCAL_PATH}
+ at subsubheading Modifying the Macro Search Path: @file{ACLOCAL_PATH}
+ at cindex @env{ACLOCAL_PATH}
+
+The fourth and last mechanism to customize the macro search path is
+also the simplest. Any directory included in the colon-separated
+environment variable @env{ACLOCAL_PATH} is added to the search path
+ at c Keep in sync with aclocal-path-precedence.test.
+and takes precedence over system directories (including those found via
+ at file{dirlist}), with the exception of the versioned directory
+ at var{acdir-APIVERSION} (@pxref{Macro Search Path}). However, directories
+passed via @option{-I} will take precedence over directories in
+ at env{ACLOCAL_PATH}.
+
+ at c Keep in sync with aclocal-path-installed.test.
+Also note that, if the @option{--install} option is used, any @file{.m4}
+file containing a required macro that is found in a directory listed in
+ at env{ACLOCAL_PATH} will be installed locally.
+ at c Keep in sync with aclocal-path-installed-serial.test.
+In this case, serial numbers in @file{.m4} are honoured too,
+ at pxref{Serials}.
+
+Conversely to @file{dirlist}, @env{ACLOCAL_PATH} is useful if you are
+using a global copy of Automake and want @command{aclocal} to look for
+macros somewhere under your home directory.
+
+ at subsubheading Planned future incompatibilities
+
+The order in which the directories in the macro search path are currently
+looked up is confusing and/or suboptimal in various aspects, and is
+probably going to be changed in the future Automake release. In
+particular, directories in @env{ACLOCAL_PATH} and @file{@var{acdir}}
+might end up taking precedence over @file{@var{acdir-APIVERSION}}, and
+directories in @file{@var{acdir}/dirlist} might end up taking precedence
+over @file{@var{acdir}}. @emph{This is a possible future incompatibility!}
+
+ at node Extending aclocal
+ at subsection Writing your own aclocal macros
+
+ at cindex @command{aclocal}, extending
+ at cindex Extending @command{aclocal}
+
+The @command{aclocal} program doesn't have any built-in knowledge of any
+macros, so it is easy to extend it with your own macros.
+
+This can be used by libraries that want to supply their own Autoconf
+macros for use by other programs. For instance, the @command{gettext}
+library supplies a macro @code{AM_GNU_GETTEXT} that should be used by
+any package using @command{gettext}. When the library is installed, it
+installs this macro so that @command{aclocal} will find it.
+
+A macro file's name should end in @file{.m4}. Such files should be
+installed in @file{$(datadir)/aclocal}. This is as simple as writing:
+
+ at c Keep in sync with primary-prefix-couples-documented-valid.test.
+ at example
+aclocaldir = $(datadir)/aclocal
+aclocal_DATA = mymacro.m4 myothermacro.m4
+ at end example
+
+ at noindent
+Please do use @file{$(datadir)/aclocal}, and not something based on
+the result of @samp{aclocal --print-ac-dir} (@pxref{Hard-Coded Install
+Paths}, for arguments). It might also be helpful to suggest to
+the user to add the @file{$(datadir)/aclocal} directory to his
+ at env{ACLOCAL_PATH} variable (@pxref{ACLOCAL_PATH}) so that
+ at command{aclocal} will find the @file{.m4} files installed by your
+package automatically.
+
+A file of macros should be a series of properly quoted
+ at code{AC_DEFUN}'s (@pxref{Macro Definitions, , , autoconf, The
+Autoconf Manual}). The @command{aclocal} programs also understands
+ at code{AC_REQUIRE} (@pxref{Prerequisite Macros, , , autoconf, The
+Autoconf Manual}), so it is safe to put each macro in a separate file.
+Each file should have no side effects but macro definitions.
+Especially, any call to @code{AC_PREREQ} should be done inside the
+defined macro, not at the beginning of the file.
+
+ at cindex underquoted @code{AC_DEFUN}
+ at acindex AC_DEFUN
+ at acindex AC_PREREQ
+
+Starting with Automake 1.8, @command{aclocal} will warn about all
+underquoted calls to @code{AC_DEFUN}. We realize this will annoy a
+lot of people, because @command{aclocal} was not so strict in the past
+and many third party macros are underquoted; and we have to apologize
+for this temporary inconvenience. The reason we have to be stricter
+is that a future implementation of @command{aclocal} (@pxref{Future of
+aclocal}) will have to temporarily include all these third party
+ at file{.m4} files, maybe several times, including even files that are
+not actually needed. Doing so should alleviate many problems of the
+current implementation, however it requires a stricter style from the
+macro authors. Hopefully it is easy to revise the existing macros.
+For instance,
+
+ at example
+# bad style
+AC_PREREQ(2.57)
+AC_DEFUN(AX_FOOBAR,
+[AC_REQUIRE([AX_SOMETHING])dnl
+AX_FOO
+AX_BAR
+])
+ at end example
+
+ at noindent
+should be rewritten as
+
+ at example
+AC_DEFUN([AX_FOOBAR],
+[AC_PREREQ([2.57])dnl
+AC_REQUIRE([AX_SOMETHING])dnl
+AX_FOO
+AX_BAR
+])
+ at end example
+
+Wrapping the @code{AC_PREREQ} call inside the macro ensures that
+Autoconf 2.57 will not be required if @code{AX_FOOBAR} is not actually
+used. Most importantly, quoting the first argument of @code{AC_DEFUN}
+allows the macro to be redefined or included twice (otherwise this
+first argument would be expanded during the second definition). For
+consistency we like to quote even arguments such as @code{2.57} that
+do not require it.
+
+If you have been directed here by the @command{aclocal} diagnostic but
+are not the maintainer of the implicated macro, you will want to
+contact the maintainer of that macro. Please make sure you have the
+latest version of the macro and that the problem hasn't already been
+reported before doing so: people tend to work faster when they aren't
+flooded by mails.
+
+Another situation where @command{aclocal} is commonly used is to
+manage macros that are used locally by the package, @ref{Local
+Macros}.
+
+ at node Local Macros
+ at subsection Handling Local Macros
+
+Feature tests offered by Autoconf do not cover all needs. People
+often have to supplement existing tests with their own macros, or
+with third-party macros.
+
+There are two ways to organize custom macros in a package.
+
+The first possibility (the historical practice) is to list all your
+macros in @file{acinclude.m4}. This file will be included in
+ at file{aclocal.m4} when you run @command{aclocal}, and its macro(s) will
+henceforth be visible to @command{autoconf}. However if it contains
+numerous macros, it will rapidly become difficult to maintain, and it
+will be almost impossible to share macros between packages.
+
+ at vindex ACLOCAL_AMFLAGS
+The second possibility, which we do recommend, is to write each macro
+in its own file and gather all these files in a directory. This
+directory is usually called @file{m4/}. To build @file{aclocal.m4},
+one should therefore instruct @command{aclocal} to scan @file{m4/}.
+From the command line, this is done with @samp{aclocal -I m4}. The
+top-level @file{Makefile.am} should also be updated to define
+
+ at example
+ACLOCAL_AMFLAGS = -I m4
+ at end example
+
+ at code{ACLOCAL_AMFLAGS} contains options to pass to @command{aclocal}
+when @file{aclocal.m4} is to be rebuilt by @command{make}. This line is
+also used by @command{autoreconf} (@pxref{autoreconf Invocation, ,
+Using @command{autoreconf} to Update @file{configure} Scripts,
+autoconf, The Autoconf Manual}) to run @command{aclocal} with suitable
+options, or by @command{autopoint} (@pxref{autopoint Invocation, ,
+Invoking the @command{autopoint} Program, gettext, GNU gettext tools})
+and @command{gettextize} (@pxref{gettextize Invocation, , Invoking the
+ at command{gettextize} Program, gettext, GNU gettext tools}) to locate
+the place where Gettext's macros should be installed. So even if you
+do not really care about the rebuild rules, you should define
+ at code{ACLOCAL_AMFLAGS}.
+
+When @samp{aclocal -I m4} is run, it will build an @file{aclocal.m4}
+that @code{m4_include}s any file from @file{m4/} that defines a
+required macro. Macros not found locally will still be searched in
+system-wide directories, as explained in @ref{Macro Search Path}.
+
+Custom macros should be distributed for the same reason that
+ at file{configure.ac} is: so that other people have all the sources of
+your package if they want to work on it. Actually, this distribution
+happens automatically because all @code{m4_include}d files are
+distributed.
+
+However there is no consensus on the distribution of third-party
+macros that your package may use. Many libraries install their own
+macro in the system-wide @command{aclocal} directory (@pxref{Extending
+aclocal}). For instance, Guile ships with a file called
+ at file{guile.m4} that contains the macro @code{GUILE_FLAGS} that can
+be used to define setup compiler and linker flags appropriate for
+using Guile. Using @code{GUILE_FLAGS} in @file{configure.ac} will
+cause @command{aclocal} to copy @file{guile.m4} into
+ at file{aclocal.m4}, but as @file{guile.m4} is not part of the project,
+it will not be distributed. Technically, that means a user who
+needs to rebuild @file{aclocal.m4} will have to install Guile first.
+This is probably OK, if Guile already is a requirement to build the
+package. However, if Guile is only an optional feature, or if your
+package might run on architectures where Guile cannot be installed,
+this requirement will hinder development. An easy solution is to copy
+such third-party macros in your local @file{m4/} directory so they get
+distributed.
+
+Since Automake 1.10, @command{aclocal} offers an option to copy these
+system-wide third-party macros in your local macro directory, solving
+the above problem. Simply use:
+
+ at example
+ACLOCAL_AMFLAGS = -I m4 --install
+ at end example
+
+ at noindent
+With this setup, system-wide macros will be copied to @file{m4/}
+the first time you run @command{autoreconf}. Then the locally
+installed macros will have precedence over the system-wide installed
+macros each time @command{aclocal} is run again.
+
+One reason why you should keep @option{--install} in the flags even
+after the first run is that when you later edit @file{configure.ac}
+and depend on a new macro, this macro will be installed in your
+ at file{m4/} automatically. Another one is that serial numbers
+(@pxref{Serials}) can be used to update the macros in your source tree
+automatically when new system-wide versions are installed. A serial
+number should be a single line of the form
+
+ at example
+#serial @var{nnn}
+ at end example
+
+ at noindent
+where @var{nnn} contains only digits and dots. It should appear in
+the M4 file before any macro definition. It is a good practice to
+maintain a serial number for each macro you distribute, even if you do
+not use the @option{--install} option of @command{aclocal}: this allows
+other people to use it.
+
+
+ at node Serials
+ at subsection Serial Numbers
+ at cindex serial numbers in macros
+ at cindex macro serial numbers
+ at cindex @code{#serial} syntax
+ at cindex @command{aclocal} and serial numbers
+
+Because third-party macros defined in @file{*.m4} files are naturally
+shared between multiple projects, some people like to version them.
+This makes it easier to tell which of two M4 files is newer. Since at
+least 1996, the tradition is to use a @samp{#serial} line for this.
+
+A serial number should be a single line of the form
+
+ at example
+# serial @var{version}
+ at end example
+
+ at noindent
+where @var{version} is a version number containing only digits and
+dots. Usually people use a single integer, and they increment it each
+time they change the macro (hence the name of ``serial''). Such a
+line should appear in the M4 file before any macro definition.
+
+The @samp{#} must be the first character on the line,
+and it is OK to have extra words after the version, as in
+
+ at example
+#serial @var{version} @var{garbage}
+ at end example
+
+Normally these serial numbers are completely ignored by
+ at command{aclocal} and @command{autoconf}, like any genuine comment.
+However when using @command{aclocal}'s @option{--install} feature, these
+serial numbers will modify the way @command{aclocal} selects the
+macros to install in the package: if two files with the same basename
+exist in your search path, and if at least one of them uses a
+ at samp{#serial} line, @command{aclocal} will ignore the file that has
+the older @samp{#serial} line (or the file that has none).
+
+Note that a serial number applies to a whole M4 file, not to any macro
+it contains. A file can contains multiple macros, but only one
+serial.
+
+Here is a use case that illustrates the use of @option{--install} and
+its interaction with serial numbers. Let's assume we maintain a
+package called MyPackage, the @file{configure.ac} of which requires a
+third-party macro @code{AX_THIRD_PARTY} defined in
+ at file{/usr/share/aclocal/thirdparty.m4} as follows:
+
+ at example
+# serial 1
+AC_DEFUN([AX_THIRD_PARTY], [...])
+ at end example
+
+MyPackage uses an @file{m4/} directory to store local macros as
+explained in @ref{Local Macros}, and has
+
+ at example
+ACLOCAL_AMFLAGS = -I m4 --install
+ at end example
+
+ at noindent
+in its top-level @file{Makefile.am}.
+
+Initially the @file{m4/} directory is empty. The first time we run
+ at command{autoreconf}, it will fetch the options to pass to
+ at command{aclocal} in @file{Makefile.am}, and run @samp{aclocal -I m4
+--install}. @command{aclocal} will notice that
+
+ at itemize @bullet
+ at item
+ at file{configure.ac} uses @code{AX_THIRD_PARTY}
+ at item
+No local macros define @code{AX_THIRD_PARTY}
+ at item
+ at file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
+with serial 1.
+ at end itemize
+
+ at noindent
+Because @file{/usr/share/aclocal/thirdparty.m4} is a system-wide macro
+and @command{aclocal} was given the @option{--install} option, it will
+copy this file in @file{m4/thirdparty.m4}, and output an
+ at file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
+
+The next time @samp{aclocal -I m4 --install} is run (either via
+ at command{autoreconf}, by hand, or from the @file{Makefile} rebuild
+rules) something different happens. @command{aclocal} notices that
+
+ at itemize @bullet
+ at item
+ at file{configure.ac} uses @code{AX_THIRD_PARTY}
+ at item
+ at file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
+with serial 1.
+ at item
+ at file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
+with serial 1.
+ at end itemize
+
+ at noindent
+Because both files have the same serial number, @command{aclocal} uses
+the first it found in its search path order (@pxref{Macro Search
+Path}). @command{aclocal} therefore ignores
+ at file{/usr/share/aclocal/thirdparty.m4} and outputs an
+ at file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
+
+Local directories specified with @option{-I} are always searched before
+system-wide directories, so a local file will always be preferred to
+the system-wide file in case of equal serial numbers.
+
+Now suppose the system-wide third-party macro is changed. This can
+happen if the package installing this macro is updated. Let's suppose
+the new macro has serial number 2. The next time @samp{aclocal -I m4
+--install} is run the situation is the following:
+
+ at itemize @bullet
+ at item
+ at file{configure.ac} uses @code{AX_THIRD_PARTY}
+ at item
+ at file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
+with serial 1.
+ at item
+ at file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
+with serial 2.
+ at end itemize
+
+ at noindent
+When @command{aclocal} sees a greater serial number, it immediately
+forgets anything it knows from files that have the same basename and a
+smaller serial number. So after it has found
+ at file{/usr/share/aclocal/thirdparty.m4} with serial 2,
+ at command{aclocal} will proceed as if it had never seen
+ at file{m4/thirdparty.m4}. This brings us back to a situation similar
+to that at the beginning of our example, where no local file defined
+the macro. @command{aclocal} will install the new version of the
+macro in @file{m4/thirdparty.m4}, in this case overriding the old
+version. MyPackage just had its macro updated as a side effect of
+running @command{aclocal}.
+
+If you are leery of letting @command{aclocal} update your local macro,
+you can run @samp{aclocal -I m4 --diff} to review the changes
+ at samp{aclocal -I m4 --install} would perform on these macros.
+
+Finally, note that the @option{--force} option of @command{aclocal} has
+absolutely no effect on the files installed by @option{--install}. For
+instance, if you have modified your local macros, do not expect
+ at option{--install --force} to replace the local macros by their
+system-wide versions. If you want to do so, simply erase the local
+macros you want to revert, and run @samp{aclocal -I m4 --install}.
+
+
+ at node Future of aclocal
+ at subsection The Future of @command{aclocal}
+ at cindex @command{aclocal}'s scheduled death
+
+ at command{aclocal} is expected to disappear. This feature really
+should not be offered by Automake. Automake should focus on
+generating @file{Makefile}s; dealing with M4 macros really is
+Autoconf's job. The fact that some people install Automake just to use
+ at command{aclocal}, but do not use @command{automake} otherwise is an
+indication of how that feature is misplaced.
+
+The new implementation will probably be done slightly differently.
+For instance, it could enforce the @file{m4/}-style layout discussed in
+ at ref{Local Macros}.
+
+We have no idea when and how this will happen. This has been
+discussed several times in the past, but someone still has to commit
+to that non-trivial task.
+
+From the user point of view, @command{aclocal}'s removal might turn
+out to be painful. There is a simple precaution that you may take to
+make that switch more seamless: never call @command{aclocal} yourself.
+Keep this guy under the exclusive control of @command{autoreconf} and
+Automake's rebuild rules. Hopefully you won't need to worry about
+things breaking, when @command{aclocal} disappears, because everything
+will have been taken care of. If otherwise you used to call
+ at command{aclocal} directly yourself or from some script, you will
+quickly notice the change.
+
+Many packages come with a script called @file{bootstrap.sh} or
+ at file{autogen.sh}, that will just call @command{aclocal},
+ at command{libtoolize}, @command{gettextize} or @command{autopoint},
+ at command{autoconf}, @command{autoheader}, and @command{automake} in
+the right order. Actually this is precisely what @command{autoreconf}
+can do for you. If your package has such a @file{bootstrap.sh} or
+ at file{autogen.sh} script, consider using @command{autoreconf}. That
+should simplify its logic a lot (less things to maintain, yum!), it's
+even likely you will not need the script anymore, and more to the point
+you will not call @command{aclocal} directly anymore.
+
+For the time being, third-party packages should continue to install
+public macros into @file{/usr/share/aclocal/}. If @command{aclocal}
+is replaced by another tool it might make sense to rename the
+directory, but supporting @file{/usr/share/aclocal/} for backward
+compatibility should be really easy provided all macros are properly
+written (@pxref{Extending aclocal}).
+
+
+
+ at node Macros
+ at section Autoconf macros supplied with Automake
+
+Automake ships with several Autoconf macros that you can use from your
+ at file{configure.ac}. When you use one of them it will be included by
+ at command{aclocal} in @file{aclocal.m4}.
+
+ at menu
+* Public Macros:: Macros that you can use.
+* Obsolete Macros:: Macros that you should stop using.
+* Private Macros:: Macros that you should not use.
+ at end menu
+
+ at c consider generating the following subsections automatically from m4 files.
+
+ at node Public Macros
+ at subsection Public Macros
+
+ at table @code
+
+ at item AM_ENABLE_MULTILIB
+ at acindex AM_ENABLE_MULTILIB
+
+This is used when a ``multilib'' library is being built. Please be
+aware that multilib support @emph{will be removed} from the Automake
+core in the next major release, and then @emph{this macro will go away
+as well} (even if a ``frozen'' version of will remain available in the
+ at file{contrib/} directory of the Automake distribution).
+
+The first optional argument is the name of the @file{Makefile} being
+generated; it defaults to @samp{Makefile}. The second optional argument
+is used to find the top source directory; it defaults to the empty
+string (generally this should not be used unless you are familiar with
+the internals). @xref{Multilibs}.
+
+ at item AM_INIT_AUTOMAKE([OPTIONS])
+ at itemx AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])
+ at acindex AM_INIT_AUTOMAKE
+Runs many macros required for proper operation of the generated Makefiles.
+
+ at vindex AUTOMAKE_OPTIONS
+This macro has two forms, the first of which is preferred.
+In this form, @code{AM_INIT_AUTOMAKE} is called with a
+single argument: a space-separated list of Automake options that should
+be applied to every @file{Makefile.am} in the tree. The effect is as if
+each option were listed in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
+
+ at acindex AC_INIT
+The second, deprecated, form of @code{AM_INIT_AUTOMAKE} has two required
+arguments: the package and the version number. This form is
+obsolete because the @var{package} and @var{version} can be obtained
+from Autoconf's @code{AC_INIT} macro (which itself has an old and a new
+form).
+
+If your @file{configure.ac} has:
+
+ at example
+AC_INIT([src/foo.c])
+AM_INIT_AUTOMAKE([mumble], [1.5])
+ at end example
+
+ at noindent
+you can modernize it as follows:
+
+ at example
+AC_INIT([mumble], [1.5])
+AC_CONFIG_SRCDIR([src/foo.c])
+AM_INIT_AUTOMAKE
+ at end example
+
+Note that if you're upgrading your @file{configure.ac} from an earlier
+version of Automake, it is not always correct to simply move the
+package and version arguments from @code{AM_INIT_AUTOMAKE} directly to
+ at code{AC_INIT}, as in the example above. The first argument to
+ at code{AC_INIT} should be the name of your package (e.g., @samp{GNU
+Automake}), not the tarball name (e.g., @samp{automake}) that you used
+to pass to @code{AM_INIT_AUTOMAKE}. Autoconf tries to derive a
+tarball name from the package name, which should work for most but not
+all package names. (If it doesn't work for yours, you can use the
+four-argument form of @code{AC_INIT} to provide the tarball name
+explicitly).
+
+ at cindex @code{PACKAGE}, prevent definition
+ at cindex @code{VERSION}, prevent definition
+ at opindex no-define
+By default this macro @code{AC_DEFINE}'s @code{PACKAGE} and
+ at code{VERSION}. This can be avoided by passing the @option{no-define}
+option, as in:
+ at example
+AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2])
+ at end example
+or by passing a third non-empty argument to the obsolete form.
+
+ at item AM_PATH_LISPDIR
+ at acindex AM_PATH_LISPDIR
+ at vindex EMACS
+ at vindex lispdir
+Searches for the program @command{emacs}, and, if found, sets the
+output variable @code{lispdir} to the full path to Emacs' site-lisp
+directory.
+
+Note that this test assumes the @command{emacs} found to be a version
+that supports Emacs Lisp (such as GNU Emacs or XEmacs). Other
+emacsen can cause this test to hang (some, like old versions of
+MicroEmacs, start up in interactive mode, requiring @kbd{C-x C-c} to
+exit, which is hardly obvious for a non-emacs user). In most cases,
+however, you should be able to use @kbd{C-c} to kill the test. In
+order to avoid problems, you can set @env{EMACS} to ``no'' in the
+environment, or use the @option{--with-lispdir} option to
+ at command{configure} to explicitly set the correct path (if you're sure
+you have an @command{emacs} that supports Emacs Lisp).
+
+ at item AM_PROG_AR(@ovar{act-if-fail})
+ at acindex AM_PROG_AR
+ at vindex AR
+You must use this macro when you use the archiver in your project, if
+you want support for unusual archivers such as Microsoft @command{lib}.
+The content of the optional argument is executed if the archiver
+interface is not recognized; the default action is to abort configure
+with an error message.
+
+ at item AM_PROG_AS
+ at acindex AM_PROG_AS
+ at vindex CCAS
+ at vindex CCASFLAGS
+Use this macro when you have assembly code in your project. This will
+choose the assembler for you (by default the C compiler) and set
+ at code{CCAS}, and will also set @code{CCASFLAGS} if required.
+
+ at item AM_PROG_CC_C_O
+ at acindex AM_PROG_CC_C_O
+ at acindex AC_PROG_CC_C_O
+This is like @code{AC_PROG_CC_C_O}, but it generates its results in
+the manner required by Automake. You must use this instead of
+ at code{AC_PROG_CC_C_O} when you need this functionality, that is, when
+using per-target flags or subdir-objects with C sources.
+
+ at item AM_PROG_LEX
+ at acindex AM_PROG_LEX
+ at acindex AC_PROG_LEX
+ at cindex HP-UX 10, @command{lex} problems
+ at cindex @command{lex} problems with HP-UX 10
+Like @code{AC_PROG_LEX} (@pxref{Particular Programs, , Particular
+Program Checks, autoconf, The Autoconf Manual}), but uses the
+ at command{missing} script on systems that do not have @command{lex}.
+HP-UX 10 is one such system.
+
+ at item AM_PROG_GCJ
+ at acindex AM_PROG_GCJ
+ at vindex GCJ
+ at vindex GCJFLAGS
+This macro finds the @command{gcj} program or causes an error. It sets
+ at code{GCJ} and @code{GCJFLAGS}. @command{gcj} is the Java front-end to the
+GNU Compiler Collection.
+
+ at item AM_PROG_UPC([@var{compiler-search-list}])
+ at acindex AM_PROG_UPC
+ at vindex UPC
+Find a compiler for Unified Parallel C and define the @code{UPC}
+variable. The default @var{compiler-search-list} is @samp{upcc upc}.
+This macro will abort @command{configure} if no Unified Parallel C
+compiler is found.
+
+ at item AM_SILENT_RULES
+ at acindex AM_SILENT_RULES
+Enable the machinery for less verbose build output (@pxref{Options}).
+
+ at item AM_WITH_DMALLOC
+ at acindex AM_WITH_DMALLOC
+ at cindex @command{dmalloc}, support for
+ at vindex WITH_DMALLOC
+ at opindex --with-dmalloc
+Add support for the @uref{http://dmalloc.com/, Dmalloc package}. If
+the user runs @command{configure} with @option{--with-dmalloc}, then
+define @code{WITH_DMALLOC} and add @option{-ldmalloc} to @code{LIBS}.
+
+ at end table
+
+
+ at node Obsolete Macros
+ at subsection Obsolete Macros
+ at cindex obsolete macros
+ at cindex autoupdate
+
+Although using some of the following macros was required in past
+releases, you should not use any of them in new code. Running
+ at command{autoupdate} should adjust your @file{configure.ac}
+automatically (@pxref{autoupdate Invocation, , Using
+ at command{autoupdate} to Modernize @file{configure.ac}, autoconf, The
+Autoconf Manual}).
+
+ at table @code
+ at item AM_C_PROTOTYPES
+ at acindex AM_C_PROTOTYPES
+ at vindex ANSI2KNR
+ at vindex U
+Check to see if function prototypes are understood by the compiler. If
+so, define @samp{PROTOTYPES} and set the output variables @code{U} and
+ at code{ANSI2KNR} to the empty string. Otherwise, set @code{U} to
+ at samp{_} and @code{ANSI2KNR} to @samp{./ansi2knr}. Automake used these
+values to implement the deprecated de-ANSI-fication feature; however,
+support for @emph{that feature will be removed} in the next major Automake
+release, and then @emph{these macros and variables will go away as well}.
+
+ at item AM_CONFIG_HEADER
+ at acindex AM_CONFIG_HEADER
+Automake will generate rules to automatically regenerate the config
+header. This obsolete macro is a synonym of @code{AC_CONFIG_HEADERS}
+today (@pxref{Optional}).
+
+ at item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
+ at acindex AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
+If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
+define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
+found in @file{<termios.h>}. This macro is obsolete, you should
+use Autoconf's @code{AC_HEADER_TIOCGWINSZ} instead.
+
+ at item AM_PROG_MKDIR_P
+ at acindex AM_PROG_MKDIR_P
+ at cindex @code{mkdir -p}, macro check
+ at vindex MKDIR_P
+ at vindex mkdir_p
+
+From Automake 1.8 to 1.9.6 this macro used to define the output
+variable @code{mkdir_p} to one of @code{mkdir -p}, @code{install-sh
+-d}, or @code{mkinstalldirs}.
+
+Nowadays Autoconf provides a similar functionality with
+ at code{AC_PROG_MKDIR_P} (@pxref{Particular Programs, , Particular
+Program Checks, autoconf, The Autoconf Manual}), however this defines
+the output variable @code{MKDIR_P} instead. Therefore
+ at code{AM_PROG_MKDIR_P} has been rewritten as a thin wrapper around
+ at code{AC_PROG_MKDIR_P} to define @code{mkdir_p} to the same value as
+ at code{MKDIR_P} for backward compatibility.
+
+If you are using Automake, there is normally no reason to call this
+macro, because @code{AM_INIT_AUTOMAKE} already does so. However, make
+sure that the custom rules in your @file{Makefile}s use
+ at code{$(MKDIR_P)} and not @code{$(mkdir_p)}. Even if both variables
+still work, the latter should be considered obsolete.
+
+If you are not using Automake, please call @code{AC_PROG_MKDIR_P}
+instead of @code{AM_PROG_MKDIR_P}.
+
+ at item AM_SYS_POSIX_TERMIOS
+ at acindex AM_SYS_POSIX_TERMIOS
+ at cindex POSIX termios headers
+ at cindex termios POSIX headers
+Check to see if POSIX termios headers and functions are available on the
+system. If so, set the shell variable @code{am_cv_sys_posix_termios} to
+ at samp{yes}. If not, set the variable to @samp{no}. This macro is obsolete,
+you should use Autoconf's @code{AC_SYS_POSIX_TERMIOS} instead.
+
+ at item AM_WITH_REGEX
+ at acindex AM_WITH_REGEX
+ at vindex WITH_REGEX
+ at opindex --with-regex
+ at cindex regex package
+ at cindex rx package
+Adds @option{--with-regex} to the @command{configure} command line. If
+specified (the default), then the @samp{regex} regular expression
+library is used, @file{regex.o} is put into @code{LIBOBJS}, and
+ at code{WITH_REGEX} is defined. If @option{--without-regex} is given, then
+the @samp{rx} regular expression library is used, and @file{rx.o} is put
+into @code{LIBOBJS}. This macro is obsolete now (since @samp{rx} doesn't
+seem to be maintained), and @emph{will be removed the next major version
+of Automake}. Consider using gnulib if you need regex functionality.
+
+ at end table
+
+
+ at node Private Macros
+ at subsection Private Macros
+
+The following macros are private macros you should not call directly.
+They are called by the other public macros when appropriate. Do not
+rely on them, as they might be changed in a future version. Consider
+them as implementation details; or better, do not consider them at all:
+skip this section!
+
+ at ftable @code
+ at item _AM_DEPENDENCIES
+ at itemx AM_SET_DEPDIR
+ at itemx AM_DEP_TRACK
+ at itemx AM_OUTPUT_DEPENDENCY_COMMANDS
+These macros are used to implement Automake's automatic dependency
+tracking scheme. They are called automatically by Automake when
+required, and there should be no need to invoke them manually.
+
+ at item AM_MAKE_INCLUDE
+This macro is used to discover how the user's @command{make} handles
+ at code{include} statements. This macro is automatically invoked when
+needed; there should be no need to invoke it manually.
+
+ at item AM_PROG_INSTALL_STRIP
+This is used to find a version of @code{install} that can be used to
+strip a program at installation time. This macro is automatically
+included when required.
+
+ at item AM_SANITY_CHECK
+This checks to make sure that a file created in the build directory is
+newer than a file in the source directory. This can fail on systems
+where the clock is set incorrectly. This macro is automatically run
+from @code{AM_INIT_AUTOMAKE}.
+
+ at end ftable
+
+
+ at node Directories
+ at chapter Directories
+
+For simple projects that distribute all files in the same directory
+it is enough to have a single @file{Makefile.am} that builds
+everything in place.
+
+In larger projects it is common to organize files in different
+directories, in a tree. For instance one directory per program, per
+library or per module. The traditional approach is to build these
+subdirectories recursively: each directory contains its @file{Makefile}
+(generated from @file{Makefile.am}), and when @command{make} is run
+from the top level directory it enters each subdirectory in turn to
+build its contents.
+
+ at menu
+* Subdirectories:: Building subdirectories recursively
+* Conditional Subdirectories:: Conditionally not building directories
+* Alternative:: Subdirectories without recursion
+* Subpackages:: Nesting packages
+ at end menu
+
+ at node Subdirectories
+ at section Recursing subdirectories
+
+ at cindex @code{SUBDIRS}, explained
+
+In packages with subdirectories, the top level @file{Makefile.am} must
+tell Automake which subdirectories are to be built. This is done via
+the @code{SUBDIRS} variable.
+ at vindex SUBDIRS
+
+The @code{SUBDIRS} variable holds a list of subdirectories in which
+building of various sorts can occur. The rules for many targets
+(e.g., @code{all}) in the generated @file{Makefile} will run commands
+both locally and in all specified subdirectories. Note that the
+directories listed in @code{SUBDIRS} are not required to contain
+ at file{Makefile.am}s; only @file{Makefile}s (after configuration).
+This allows inclusion of libraries from packages that do not use
+Automake (such as @code{gettext}; see also @ref{Third-Party
+Makefiles}).
+
+In packages that use subdirectories, the top-level @file{Makefile.am} is
+often very short. For instance, here is the @file{Makefile.am} from the
+GNU Hello distribution:
+
+ at example
+EXTRA_DIST = BUGS ChangeLog.O README-alpha
+SUBDIRS = doc intl po src tests
+ at end example
+
+When Automake invokes @command{make} in a subdirectory, it uses the value
+of the @code{MAKE} variable. It passes the value of the variable
+ at code{AM_MAKEFLAGS} to the @command{make} invocation; this can be set in
+ at file{Makefile.am} if there are flags you must always pass to
+ at command{make}.
+ at vindex MAKE
+ at vindex AM_MAKEFLAGS
+
+The directories mentioned in @code{SUBDIRS} are usually direct
+children of the current directory, each subdirectory containing its
+own @file{Makefile.am} with a @code{SUBDIRS} pointing to deeper
+subdirectories. Automake can be used to construct packages of
+arbitrary depth this way.
+
+By default, Automake generates @file{Makefiles} that work depth-first
+in postfix order: the subdirectories are built before the current
+directory. However, it is possible to change this ordering. You can
+do this by putting @samp{.} into @code{SUBDIRS}. For instance,
+putting @samp{.} first will cause a prefix ordering of
+directories.
+
+Using
+
+ at example
+SUBDIRS = lib src . test
+ at end example
+
+ at noindent
+will cause @file{lib/} to be built before @file{src/}, then the
+current directory will be built, finally the @file{test/} directory
+will be built. It is customary to arrange test directories to be
+built after everything else since they are meant to test what has
+been constructed.
+
+All @code{clean} rules are run in reverse order of build rules.
+
+ at node Conditional Subdirectories
+ at section Conditional Subdirectories
+ at cindex Subdirectories, building conditionally
+ at cindex Conditional subdirectories
+ at cindex @code{SUBDIRS}, conditional
+ at cindex Conditional @code{SUBDIRS}
+
+It is possible to define the @code{SUBDIRS} variable conditionally if,
+like in the case of GNU Inetutils, you want to only build a subset of
+the entire package.
+
+To illustrate how this works, let's assume we have two directories
+ at file{src/} and @file{opt/}. @file{src/} should always be built, but we
+want to decide in @command{configure} whether @file{opt/} will be built
+or not. (For this example we will assume that @file{opt/} should be
+built when the variable @samp{$want_opt} was set to @samp{yes}.)
+
+Running @command{make} should thus recurse into @file{src/} always, and
+then maybe in @file{opt/}.
+
+However @samp{make dist} should always recurse into both @file{src/}
+and @file{opt/}. Because @file{opt/} should be distributed even if it
+is not needed in the current configuration. This means
+ at file{opt/Makefile} should be created @emph{unconditionally}.
+
+There are two ways to setup a project like this. You can use Automake
+conditionals (@pxref{Conditionals}) or use Autoconf @code{AC_SUBST}
+variables (@pxref{Setting Output Variables, , Setting Output
+Variables, autoconf, The Autoconf Manual}). Using Automake
+conditionals is the preferred solution. Before we illustrate these
+two possibilities, let's introduce @code{DIST_SUBDIRS}.
+
+ at menu
+* SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
+* Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
+* Subdirectories with AC_SUBST:: Another way for conditional recursion
+* Unconfigured Subdirectories:: Not even creating a @samp{Makefile}
+ at end menu
+
+ at node SUBDIRS vs DIST_SUBDIRS
+ at subsection @code{SUBDIRS} vs.@: @code{DIST_SUBDIRS}
+ at cindex @code{DIST_SUBDIRS}, explained
+
+Automake considers two sets of directories, defined by the variables
+ at code{SUBDIRS} and @code{DIST_SUBDIRS}.
+
+ at code{SUBDIRS} contains the subdirectories of the current directory
+that must be built (@pxref{Subdirectories}). It must be defined
+manually; Automake will never guess a directory is to be built. As we
+will see in the next two sections, it is possible to define it
+conditionally so that some directory will be omitted from the build.
+
+ at code{DIST_SUBDIRS} is used in rules that need to recurse in all
+directories, even those that have been conditionally left out of the
+build. Recall our example where we may not want to build subdirectory
+ at file{opt/}, but yet we want to distribute it? This is where
+ at code{DIST_SUBDIRS} comes into play: @samp{opt} may not appear in
+ at code{SUBDIRS}, but it must appear in @code{DIST_SUBDIRS}.
+
+Precisely, @code{DIST_SUBDIRS} is used by @samp{make
+maintainer-clean}, @samp{make distclean} and @samp{make dist}. All
+other recursive rules use @code{SUBDIRS}.
+
+If @code{SUBDIRS} is defined conditionally using Automake
+conditionals, Automake will define @code{DIST_SUBDIRS} automatically
+from the possible values of @code{SUBDIRS} in all conditions.
+
+If @code{SUBDIRS} contains @code{AC_SUBST} variables,
+ at code{DIST_SUBDIRS} will not be defined correctly because Automake
+does not know the possible values of these variables. In this case
+ at code{DIST_SUBDIRS} needs to be defined manually.
+
+ at node Subdirectories with AM_CONDITIONAL
+ at subsection Subdirectories with @code{AM_CONDITIONAL}
+ at cindex @code{SUBDIRS} and @code{AM_CONDITIONAL}
+ at cindex @code{AM_CONDITIONAL} and @code{SUBDIRS}
+
+ at c Keep in sync with subcond2.test.
+
+ at file{configure} should output the @file{Makefile} for each directory
+and define a condition into which @file{opt/} should be built.
+
+ at example
+ at dots{}
+AM_CONDITIONAL([COND_OPT], [test "$want_opt" = yes])
+AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
+ at dots{}
+ at end example
+
+Then @code{SUBDIRS} can be defined in the top-level @file{Makefile.am}
+as follows.
+
+ at example
+if COND_OPT
+ MAYBE_OPT = opt
+endif
+SUBDIRS = src $(MAYBE_OPT)
+ at end example
+
+As you can see, running @command{make} will rightly recurse into
+ at file{src/} and maybe @file{opt/}.
+
+ at vindex DIST_SUBDIRS
+As you can't see, running @samp{make dist} will recurse into both
+ at file{src/} and @file{opt/} directories because @samp{make dist}, unlike
+ at samp{make all}, doesn't use the @code{SUBDIRS} variable. It uses the
+ at code{DIST_SUBDIRS} variable.
+
+In this case Automake will define @samp{DIST_SUBDIRS = src opt}
+automatically because it knows that @code{MAYBE_OPT} can contain
+ at samp{opt} in some condition.
+
+ at node Subdirectories with AC_SUBST
+ at subsection Subdirectories with @code{AC_SUBST}
+ at cindex @code{SUBDIRS} and @code{AC_SUBST}
+ at cindex @code{AC_SUBST} and @code{SUBDIRS}
+
+ at c Keep in sync with subcond3.test.
+
+Another possibility is to define @code{MAYBE_OPT} from
+ at file{./configure} using @code{AC_SUBST}:
+
+ at example
+ at dots{}
+if test "$want_opt" = yes; then
+ MAYBE_OPT=opt
+else
+ MAYBE_OPT=
+fi
+AC_SUBST([MAYBE_OPT])
+AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
+ at dots{}
+ at end example
+
+In this case the top-level @file{Makefile.am} should look as follows.
+
+ at example
+SUBDIRS = src $(MAYBE_OPT)
+DIST_SUBDIRS = src opt
+ at end example
+
+The drawback is that since Automake cannot guess what the possible
+values of @code{MAYBE_OPT} are, it is necessary to define
+ at code{DIST_SUBDIRS}.
+
+ at node Unconfigured Subdirectories
+ at subsection Unconfigured Subdirectories
+ at cindex Subdirectories, configured conditionally
+
+The semantics of @code{DIST_SUBDIRS} are often misunderstood by some
+users that try to @emph{configure and build} subdirectories
+conditionally. Here by configuring we mean creating the
+ at file{Makefile} (it might also involve running a nested
+ at command{configure} script: this is a costly operation that explains
+why people want to do it conditionally, but only the @file{Makefile}
+is relevant to the discussion).
+
+The above examples all assume that every @file{Makefile} is created,
+even in directories that are not going to be built. The simple reason
+is that we want @samp{make dist} to distribute even the directories
+that are not being built (e.g., platform-dependent code), hence
+ at file{make dist} must recurse into the subdirectory, hence this
+directory must be configured and appear in @code{DIST_SUBDIRS}.
+
+Building packages that do not configure every subdirectory is a tricky
+business, and we do not recommend it to the novice as it is easy to
+produce an incomplete tarball by mistake. We will not discuss this
+topic in depth here, yet for the adventurous here are a few rules to
+remember.
+
+ at cartouche
+ at itemize
+ at item @code{SUBDIRS} should always be a subset of @code{DIST_SUBDIRS}.
+
+It makes little sense to have a directory in @code{SUBDIRS} that
+is not in @code{DIST_SUBDIRS}. Think of the former as a way to tell
+which directories listed in the latter should be built.
+ at item Any directory listed in @code{DIST_SUBDIRS} and @code{SUBDIRS}
+must be configured.
+
+I.e., the @file{Makefile} must exists or the recursive @command{make}
+rules will not be able to process the directory.
+ at item Any configured directory must be listed in @code{DIST_SUBDIRS}.
+
+So that the cleaning rules remove the generated @file{Makefile}s.
+It would be correct to see @code{DIST_SUBDIRS} as a variable that
+lists all the directories that have been configured.
+ at end itemize
+ at end cartouche
+
+In order to prevent recursion in some unconfigured directory you
+must therefore ensure that this directory does not appear in
+ at code{DIST_SUBDIRS} (and @code{SUBDIRS}). For instance, if you define
+ at code{SUBDIRS} conditionally using @code{AC_SUBST} and do not define
+ at code{DIST_SUBDIRS} explicitly, it will be default to
+ at samp{$(SUBDIRS)}; another possibility is to force @code{DIST_SUBDIRS
+= $(SUBDIRS)}.
+
+Of course, directories that are omitted from @code{DIST_SUBDIRS} will
+not be distributed unless you make other arrangements for this to
+happen (for instance, always running @samp{make dist} in a
+configuration where all directories are known to appear in
+ at code{DIST_SUBDIRS}; or writing a @code{dist-hook} target to
+distribute these directories).
+
+ at cindex Subdirectories, not distributed
+In few packages, unconfigured directories are not even expected to
+be distributed. Although these packages do not require the
+aforementioned extra arrangements, there is another pitfall. If the
+name of a directory appears in @code{SUBDIRS} or @code{DIST_SUBDIRS},
+ at command{automake} will make sure the directory exists. Consequently
+ at command{automake} cannot be run on such a distribution when one
+directory has been omitted. One way to avoid this check is to use the
+ at code{AC_SUBST} method to declare conditional directories; since
+ at command{automake} does not know the values of @code{AC_SUBST}
+variables it cannot ensure the corresponding directory exists.
+
+ at node Alternative
+ at section An Alternative Approach to Subdirectories
+
+If you've ever read Peter Miller's excellent paper,
+ at uref{http://miller.emu.id.au/pmiller/books/rmch/,
+Recursive Make Considered Harmful}, the preceding sections on the use of
+subdirectories will probably come as unwelcome advice. For those who
+haven't read the paper, Miller's main thesis is that recursive
+ at command{make} invocations are both slow and error-prone.
+
+Automake provides sufficient cross-directory support @footnote{We
+believe. This work is new and there are probably warts.
+ at xref{Introduction}, for information on reporting bugs.} to enable you
+to write a single @file{Makefile.am} for a complex multi-directory
+package.
+
+
+By default an installable file specified in a subdirectory will have its
+directory name stripped before installation. For instance, in this
+example, the header file will be installed as
+ at file{$(includedir)/stdio.h}:
+
+ at example
+include_HEADERS = inc/stdio.h
+ at end example
+
+ at vindex nobase_
+ at cindex @code{nobase_} prefix
+ at cindex Path stripping, avoiding
+ at cindex Avoiding path stripping
+
+However, the @samp{nobase_} prefix can be used to circumvent this path
+stripping. In this example, the header file will be installed as
+ at file{$(includedir)/sys/types.h}:
+
+ at example
+nobase_include_HEADERS = sys/types.h
+ at end example
+
+ at cindex @code{nobase_} and @code{dist_} or @code{nodist_}
+ at cindex @code{dist_} and @code{nobase_}
+ at cindex @code{nodist_} and @code{nobase_}
+ at vindex dist_
+ at vindex nodist_
+
+ at samp{nobase_} should be specified first when used in conjunction with
+either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
+Control}). For instance:
+
+ at example
+nobase_dist_pkgdata_DATA = images/vortex.pgm sounds/whirl.ogg
+ at end example
+
+Finally, note that a variable using the @samp{nobase_} prefix can
+often be replaced by several variables, one for each destination
+directory (@pxref{Uniform}). For instance, the last example could be
+rewritten as follows:
+
+ at c Keep in sync with primary-prefix-couples-documented-valid.test.
+ at example
+imagesdir = $(pkgdatadir)/images
+soundsdir = $(pkgdatadir)/sounds
+dist_images_DATA = images/vortex.pgm
+dist_sounds_DATA = sounds/whirl.ogg
+ at end example
+
+ at noindent
+This latter syntax makes it possible to change one destination
+directory without changing the layout of the source tree.
+
+Currently, @samp{nobase_*_LTLIBRARIES} are the only exception to this
+rule, in that there is no particular installation order guarantee for
+an otherwise equivalent set of variables without @samp{nobase_} prefix.
+
+ at node Subpackages
+ at section Nesting Packages
+ at cindex Nesting packages
+ at cindex Subpackages
+ at acindex AC_CONFIG_SUBDIRS
+ at acindex AC_CONFIG_AUX_DIR
+
+
+In the GNU Build System, packages can be nested to arbitrary depth.
+This means that a package can embed other packages with their own
+ at file{configure}, @file{Makefile}s, etc.
+
+These other packages should just appear as subdirectories of their
+parent package. They must be listed in @code{SUBDIRS} like other
+ordinary directories. However the subpackage's @file{Makefile}s
+should be output by its own @file{configure} script, not by the
+parent's @file{configure}. This is achieved using the
+ at code{AC_CONFIG_SUBDIRS} Autoconf macro (@pxref{Subdirectories,
+AC_CONFIG_SUBDIRS, Configuring Other Packages in Subdirectories,
+autoconf, The Autoconf Manual}).
+
+Here is an example package for an @code{arm} program that links with
+a @code{hand} library that is a nested package in subdirectory
+ at file{hand/}.
+
+ at code{arm}'s @file{configure.ac}:
+
+ at example
+AC_INIT([arm], [1.0])
+AC_CONFIG_AUX_DIR([.])
+AM_INIT_AUTOMAKE
+AC_PROG_CC
+AC_CONFIG_FILES([Makefile])
+# Call hand's ./configure script recursively.
+AC_CONFIG_SUBDIRS([hand])
+AC_OUTPUT
+ at end example
+
+ at code{arm}'s @file{Makefile.am}:
+
+ at example
+# Build the library in the hand subdirectory first.
+SUBDIRS = hand
+
+# Include hand's header when compiling this directory.
+AM_CPPFLAGS = -I$(srcdir)/hand
+
+bin_PROGRAMS = arm
+arm_SOURCES = arm.c
+# link with the hand library.
+arm_LDADD = hand/libhand.a
+ at end example
+
+Now here is @code{hand}'s @file{hand/configure.ac}:
+
+ at example
+AC_INIT([hand], [1.2])
+AC_CONFIG_AUX_DIR([.])
+AM_INIT_AUTOMAKE
+AC_PROG_CC
+AM_PROG_AR
+AC_PROG_RANLIB
+AC_CONFIG_FILES([Makefile])
+AC_OUTPUT
+ at end example
+
+ at noindent
+and its @file{hand/Makefile.am}:
+
+ at example
+lib_LIBRARIES = libhand.a
+libhand_a_SOURCES = hand.c
+ at end example
+
+When @samp{make dist} is run from the top-level directory it will
+create an archive @file{arm-1.0.tar.gz} that contains the @code{arm}
+code as well as the @file{hand} subdirectory. This package can be
+built and installed like any ordinary package, with the usual
+ at samp{./configure && make && make install} sequence (the @code{hand}
+subpackage will be built and installed by the process).
+
+When @samp{make dist} is run from the hand directory, it will create a
+self-contained @file{hand-1.2.tar.gz} archive. So although it appears
+to be embedded in another package, it can still be used separately.
+
+The purpose of the @samp{AC_CONFIG_AUX_DIR([.])} instruction is to
+force Automake and Autoconf to search for auxiliary scripts in the
+current directory. For instance, this means that there will be two
+copies of @file{install-sh}: one in the top-level of the @code{arm}
+package, and another one in the @file{hand/} subdirectory for the
+ at code{hand} package.
+
+The historical default is to search for these auxiliary scripts in
+the parent directory and the grandparent directory. So if the
+ at samp{AC_CONFIG_AUX_DIR([.])} line was removed from
+ at file{hand/configure.ac}, that subpackage would share the auxiliary
+script of the @code{arm} package. This may looks like a gain in size
+(a few kilobytes), but it is actually a loss of modularity as the
+ at code{hand} subpackage is no longer self-contained (@samp{make dist}
+in the subdirectory will not work anymore).
+
+Packages that do not use Automake need more work to be integrated this
+way. @xref{Third-Party Makefiles}.
+
+ at node Programs
+ at chapter Building Programs and Libraries
+
+A large part of Automake's functionality is dedicated to making it easy
+to build programs and libraries.
+
+ at menu
+* A Program:: Building a program
+* A Library:: Building a library
+* A Shared Library:: Building a Libtool library
+* Program and Library Variables:: Variables controlling program and
+ library builds
+* Default _SOURCES:: Default source files
+* LIBOBJS:: Special handling for LIBOBJS and ALLOCA
+* Program Variables:: Variables used when building a program
+* Yacc and Lex:: Yacc and Lex support
+* C++ Support:: Compiling C++ sources
+* Objective C Support:: Compiling Objective C sources
+* Unified Parallel C Support:: Compiling Unified Parallel C sources
+* Assembly Support:: Compiling assembly sources
+* Fortran 77 Support:: Compiling Fortran 77 sources
+* Fortran 9x Support:: Compiling Fortran 9x sources
+* Java Support with gcj:: Compiling Java sources using gcj
+* Vala Support:: Compiling Vala sources
+* Support for Other Languages:: Compiling other languages
+* ANSI:: Automatic de-ANSI-fication (deprecated, soon to be removed)
+* Dependencies:: Automatic dependency tracking
+* EXEEXT:: Support for executable extensions
+ at end menu
+
+
+ at node A Program
+ at section Building a program
+
+In order to build a program, you need to tell Automake which sources
+are part of it, and which libraries it should be linked with.
+
+This section also covers conditional compilation of sources or
+programs. Most of the comments about these also apply to libraries
+(@pxref{A Library}) and libtool libraries (@pxref{A Shared Library}).
+
+ at menu
+* Program Sources:: Defining program sources
+* Linking:: Linking with libraries or extra objects
+* Conditional Sources:: Handling conditional sources
+* Conditional Programs:: Building a program conditionally
+ at end menu
+
+ at node Program Sources
+ at subsection Defining program sources
+
+ at cindex @code{PROGRAMS}, @code{bindir}
+ at vindex _PROGRAMS
+ at vindex bin_PROGRAMS
+ at vindex sbin_PROGRAMS
+ at vindex libexec_PROGRAMS
+ at vindex pkglibexec_PROGRAMS
+ at vindex noinst_PROGRAMS
+ at vindex check_PROGRAMS
+
+In a directory containing source that gets built into a program (as
+opposed to a library or a script), the @code{PROGRAMS} primary is used.
+Programs can be installed in @code{bindir}, @code{sbindir},
+ at code{libexecdir}, @code{pkglibexecdir}, or not at all
+(@code{noinst_}). They can also be built only for @samp{make check}, in
+which case the prefix is @samp{check_}.
+
+For instance:
+
+ at example
+bin_PROGRAMS = hello
+ at end example
+
+In this simple case, the resulting @file{Makefile.in} will contain code
+to generate a program named @code{hello}.
+
+Associated with each program are several assisting variables that are
+named after the program. These variables are all optional, and have
+reasonable defaults. Each variable, its use, and default is spelled out
+below; we use the ``hello'' example throughout.
+
+The variable @code{hello_SOURCES} is used to specify which source files
+get built into an executable:
+
+ at example
+hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
+ at end example
+
+This causes each mentioned @file{.c} file to be compiled into the
+corresponding @file{.o}. Then all are linked to produce @file{hello}.
+
+ at cindex @code{_SOURCES} primary, defined
+ at cindex @code{SOURCES} primary, defined
+ at cindex Primary variable, @code{SOURCES}
+ at vindex _SOURCES
+
+If @code{hello_SOURCES} is not specified, then it defaults to the single
+file @file{hello.c} (@pxref{Default _SOURCES}).
+ at vindex _SOURCES
+ at vindex SOURCES
+
+Multiple programs can be built in a single directory. Multiple programs
+can share a single source file, which must be listed in each
+ at code{_SOURCES} definition.
+
+ at cindex Header files in @code{_SOURCES}
+ at cindex @code{_SOURCES} and header files
+
+Header files listed in a @code{_SOURCES} definition will be included in
+the distribution but otherwise ignored. In case it isn't obvious, you
+should not include the header file generated by @file{configure} in a
+ at code{_SOURCES} variable; this file should not be distributed. Lex
+(@file{.l}) and Yacc (@file{.y}) files can also be listed; see @ref{Yacc
+and Lex}.
+
+
+ at node Linking
+ at subsection Linking the program
+
+If you need to link against libraries that are not found by
+ at command{configure}, you can use @code{LDADD} to do so. This variable is
+used to specify additional objects or libraries to link with; it is
+inappropriate for specifying specific linker flags, you should use
+ at code{AM_LDFLAGS} for this purpose.
+ at vindex LDADD
+ at vindex AM_LDFLAGS
+
+ at cindex @code{prog_LDADD}, defined
+
+Sometimes, multiple programs are built in one directory but do not share
+the same link-time requirements. In this case, you can use the
+ at code{@var{prog}_LDADD} variable (where @var{prog} is the name of the
+program as it appears in some @code{_PROGRAMS} variable, and usually
+written in lowercase) to override @code{LDADD}. If this variable exists
+for a given program, then that program is not linked using @code{LDADD}.
+ at vindex maude_LDADD
+
+For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
+linked against the library @file{libcpio.a}. However, @code{rmt} is
+built in the same directory, and has no such link requirement. Also,
+ at code{mt} and @code{rmt} are only built on certain architectures. Here
+is what cpio's @file{src/Makefile.am} looks like (abridged):
+
+ at example
+bin_PROGRAMS = cpio pax $(MT)
+libexec_PROGRAMS = $(RMT)
+EXTRA_PROGRAMS = mt rmt
+
+LDADD = ../lib/libcpio.a $(INTLLIBS)
+rmt_LDADD =
+
+cpio_SOURCES = @dots{}
+pax_SOURCES = @dots{}
+mt_SOURCES = @dots{}
+rmt_SOURCES = @dots{}
+ at end example
+
+ at cindex @code{_LDFLAGS}, defined
+ at vindex maude_LDFLAGS
+ at code{@var{prog}_LDADD} is inappropriate for passing program-specific
+linker flags (except for @option{-l}, @option{-L}, @option{-dlopen} and
+ at option{-dlpreopen}). So, use the @code{@var{prog}_LDFLAGS} variable for
+this purpose.
+
+ at cindex @code{_DEPENDENCIES}, defined
+ at vindex maude_DEPENDENCIES
+ at vindex EXTRA_maude_DEPENDENCIES
+It is also occasionally useful to have a program depend on some other
+target that is not actually part of that program. This can be done
+using either the @code{@var{prog}_DEPENDENCIES} or the
+ at code{EXTRA_ at var{prog}_DEPENDENCIES} variable. Each program depends on
+the contents both variables, but no further interpretation is done.
+
+Since these dependencies are associated to the link rule used to
+create the programs they should normally list files used by the link
+command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la}
+files. In rare cases you may need to add other kinds of files such as
+linker scripts, but @emph{listing a source file in
+ at code{_DEPENDENCIES} is wrong}. If some source file needs to be built
+before all the components of a program are built, consider using the
+ at code{BUILT_SOURCES} variable instead (@pxref{Sources}).
+
+If @code{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
+Automake. The automatically-assigned value is the contents of
+ at code{@var{prog}_LDADD}, with most configure substitutions, @option{-l},
+ at option{-L}, @option{-dlopen} and @option{-dlpreopen} options removed. The
+configure substitutions that are left in are only @samp{$(LIBOBJS)} and
+ at samp{$(ALLOCA)}; these are left because it is known that they will not
+cause an invalid value for @code{@var{prog}_DEPENDENCIES} to be
+generated.
+
+ at ref{Conditional Sources} shows a situation where @code{_DEPENDENCIES}
+may be used.
+
+The @code{EXTRA_ at var{prog}_DEPENDENCIES} may be useful for cases where
+you merely want to augment the @command{automake}-generated
+ at code{@var{prog}_DEPENDENCIES} rather than replacing it.
+
+ at cindex @code{LDADD} and @option{-l}
+ at cindex @option{-l} and @code{LDADD}
+We recommend that you avoid using @option{-l} options in @code{LDADD}
+or @code{@var{prog}_LDADD} when referring to libraries built by your
+package. Instead, write the file name of the library explicitly as in
+the above @code{cpio} example. Use @option{-l} only to list
+third-party libraries. If you follow this rule, the default value of
+ at code{@var{prog}_DEPENDENCIES} will list all your local libraries and
+omit the other ones.
+
+
+ at node Conditional Sources
+ at subsection Conditional compilation of sources
+
+You can't put a configure substitution (e.g., @samp{@@FOO@@} or
+ at samp{$(FOO)} where @code{FOO} is defined via @code{AC_SUBST}) into a
+ at code{_SOURCES} variable. The reason for this is a bit hard to
+explain, but suffice to say that it simply won't work. Automake will
+give an error if you try to do this.
+
+Fortunately there are two other ways to achieve the same result. One is
+to use configure substitutions in @code{_LDADD} variables, the other is
+to use an Automake conditional.
+
+ at subsubheading Conditional Compilation using @code{_LDADD} Substitutions
+
+ at cindex @code{EXTRA_prog_SOURCES}, defined
+
+Automake must know all the source files that could possibly go into a
+program, even if not all the files are built in every circumstance. Any
+files that are only conditionally built should be listed in the
+appropriate @code{EXTRA_} variable. For instance, if
+ at file{hello-linux.c} or @file{hello-generic.c} were conditionally included
+in @code{hello}, the @file{Makefile.am} would contain:
+
+ at example
+bin_PROGRAMS = hello
+hello_SOURCES = hello-common.c
+EXTRA_hello_SOURCES = hello-linux.c hello-generic.c
+hello_LDADD = $(HELLO_SYSTEM)
+hello_DEPENDENCIES = $(HELLO_SYSTEM)
+ at end example
+
+ at noindent
+You can then setup the @samp{$(HELLO_SYSTEM)} substitution from
+ at file{configure.ac}:
+
+ at example
+ at dots{}
+case $host in
+ *linux*) HELLO_SYSTEM='hello-linux.$(OBJEXT)' ;;
+ *) HELLO_SYSTEM='hello-generic.$(OBJEXT)' ;;
+esac
+AC_SUBST([HELLO_SYSTEM])
+ at dots{}
+ at end example
+
+In this case, the variable @code{HELLO_SYSTEM} should be replaced by
+either @file{hello-linux.o} or @file{hello-generic.o}, and added to
+both @code{hello_DEPENDENCIES} and @code{hello_LDADD} in order to be
+built and linked in.
+
+ at subsubheading Conditional Compilation using Automake Conditionals
+
+An often simpler way to compile source files conditionally is to use
+Automake conditionals. For instance, you could use this
+ at file{Makefile.am} construct to build the same @file{hello} example:
+
+ at example
+bin_PROGRAMS = hello
+if LINUX
+hello_SOURCES = hello-linux.c hello-common.c
+else
+hello_SOURCES = hello-generic.c hello-common.c
+endif
+ at end example
+
+In this case, @file{configure.ac} should setup the @code{LINUX}
+conditional using @code{AM_CONDITIONAL} (@pxref{Conditionals}).
+
+When using conditionals like this you don't need to use the
+ at code{EXTRA_} variable, because Automake will examine the contents of
+each variable to construct the complete list of source files.
+
+If your program uses a lot of files, you will probably prefer a
+conditional @samp{+=}.
+
+ at example
+bin_PROGRAMS = hello
+hello_SOURCES = hello-common.c
+if LINUX
+hello_SOURCES += hello-linux.c
+else
+hello_SOURCES += hello-generic.c
+endif
+ at end example
+
+ at node Conditional Programs
+ at subsection Conditional compilation of programs
+ at cindex Conditional programs
+ at cindex Programs, conditional
+
+Sometimes it is useful to determine the programs that are to be built
+at configure time. For instance, GNU @code{cpio} only builds
+ at code{mt} and @code{rmt} under special circumstances. The means to
+achieve conditional compilation of programs are the same you can use
+to compile source files conditionally: substitutions or conditionals.
+
+ at subsubheading Conditional Programs using @command{configure} Substitutions
+
+ at vindex EXTRA_PROGRAMS
+ at cindex @code{EXTRA_PROGRAMS}, defined
+In this case, you must notify Automake of all the programs that can
+possibly be built, but at the same time cause the generated
+ at file{Makefile.in} to use the programs specified by @command{configure}.
+This is done by having @command{configure} substitute values into each
+ at code{_PROGRAMS} definition, while listing all optionally built programs
+in @code{EXTRA_PROGRAMS}.
+
+ at example
+bin_PROGRAMS = cpio pax $(MT)
+libexec_PROGRAMS = $(RMT)
+EXTRA_PROGRAMS = mt rmt
+ at end example
+
+As explained in @ref{EXEEXT}, Automake will rewrite
+ at code{bin_PROGRAMS}, @code{libexec_PROGRAMS}, and
+ at code{EXTRA_PROGRAMS}, appending @samp{$(EXEEXT)} to each binary.
+Obviously it cannot rewrite values obtained at run-time through
+ at command{configure} substitutions, therefore you should take care of
+appending @samp{$(EXEEXT)} yourself, as in @samp{AC_SUBST([MT],
+['mt$@{EXEEXT@}'])}.
+
+ at subsubheading Conditional Programs using Automake Conditionals
+
+You can also use Automake conditionals (@pxref{Conditionals}) to
+select programs to be built. In this case you don't have to worry
+about @samp{$(EXEEXT)} or @code{EXTRA_PROGRAMS}.
+
+ at c Keep in sync with exeext.test.
+ at example
+bin_PROGRAMS = cpio pax
+if WANT_MT
+ bin_PROGRAMS += mt
+endif
+if WANT_RMT
+ libexec_PROGRAMS = rmt
+endif
+ at end example
+
+
+ at node A Library
+ at section Building a library
+
+ at cindex @code{_LIBRARIES} primary, defined
+ at cindex @code{LIBRARIES} primary, defined
+ at cindex Primary variable, @code{LIBRARIES}
+ at vindex _LIBRARIES
+
+ at vindex lib_LIBRARIES
+ at vindex pkglib_LIBRARIES
+ at vindex noinst_LIBRARIES
+
+Building a library is much like building a program. In this case, the
+name of the primary is @code{LIBRARIES}. Libraries can be installed in
+ at code{libdir} or @code{pkglibdir}.
+
+ at xref{A Shared Library}, for information on how to build shared
+libraries using libtool and the @code{LTLIBRARIES} primary.
+
+Each @code{_LIBRARIES} variable is a list of the libraries to be built.
+For instance, to create a library named @file{libcpio.a}, but not install
+it, you would write:
+
+ at example
+noinst_LIBRARIES = libcpio.a
+libcpio_a_SOURCES = @dots{}
+ at end example
+
+The sources that go into a library are determined exactly as they are
+for programs, via the @code{_SOURCES} variables. Note that the library
+name is canonicalized (@pxref{Canonicalization}), so the @code{_SOURCES}
+variable corresponding to @file{libcpio.a} is @samp{libcpio_a_SOURCES},
+not @samp{libcpio.a_SOURCES}.
+
+ at vindex maude_LIBADD
+Extra objects can be added to a library using the
+ at code{@var{library}_LIBADD} variable. This should be used for objects
+determined by @command{configure}. Again from @code{cpio}:
+
+ at c Keep in sync with pr401c.test.
+ at example
+libcpio_a_LIBADD = $(LIBOBJS) $(ALLOCA)
+ at end example
+
+In addition, sources for extra objects that will not exist until
+configure-time must be added to the @code{BUILT_SOURCES} variable
+(@pxref{Sources}).
+
+Building a static library is done by compiling all object files, then
+by invoking @samp{$(AR) $(ARFLAGS)} followed by the name of the
+library and the list of objects, and finally by calling
+ at samp{$(RANLIB)} on that library. You should call
+ at code{AC_PROG_RANLIB} from your @file{configure.ac} to define
+ at code{RANLIB} (Automake will complain otherwise). You should also
+call @code{AM_PROG_AR} to define @code{AR}, in order to support unusual
+archivers such as Microsoft lib. @code{ARFLAGS} will default to
+ at code{cru}; you can override this variable by setting it in your
+ at file{Makefile.am} or by @code{AC_SUBST}ing it from your
+ at file{configure.ac}. You can override the @code{AR} variable by
+defining a per-library @code{maude_AR} variable (@pxref{Program and
+Library Variables}).
+
+ at cindex Empty libraries
+Be careful when selecting library components conditionally. Because
+building an empty library is not portable, you should ensure that any
+library always contains at least one object.
+
+To use a static library when building a program, add it to
+ at code{LDADD} for this program. In the following example, the program
+ at file{cpio} is statically linked with the library @file{libcpio.a}.
+
+ at example
+noinst_LIBRARIES = libcpio.a
+libcpio_a_SOURCES = @dots{}
+
+bin_PROGRAMS = cpio
+cpio_SOURCES = cpio.c @dots{}
+cpio_LDADD = libcpio.a
+ at end example
+
+
+ at node A Shared Library
+ at section Building a Shared Library
+
+ at cindex Shared libraries, support for
+
+Building shared libraries portably is a relatively complex matter.
+For this reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
+Libtool Manual}) was created to help build shared libraries in a
+platform-independent way.
+
+ at menu
+* Libtool Concept:: Introducing Libtool
+* Libtool Libraries:: Declaring Libtool Libraries
+* Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
+* Conditional Libtool Sources:: Choosing Library Sources Conditionally
+* Libtool Convenience Libraries:: Building Convenience Libtool Libraries
+* Libtool Modules:: Building Libtool Modules
+* Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
+* LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
+* Libtool Issues:: Common Issues Related to Libtool's Use
+ at end menu
+
+ at node Libtool Concept
+ at subsection The Libtool Concept
+
+ at cindex @command{libtool}, introduction
+ at cindex libtool library, definition
+ at cindex suffix @file{.la}, defined
+ at cindex @file{.la} suffix, defined
+
+Libtool abstracts shared and static libraries into a unified concept
+henceforth called @dfn{libtool libraries}. Libtool libraries are
+files using the @file{.la} suffix, and can designate a static library,
+a shared library, or maybe both. Their exact nature cannot be
+determined until @file{./configure} is run: not all platforms support
+all kinds of libraries, and users can explicitly select which
+libraries should be built. (However the package's maintainers can
+tune the default, @pxref{AC_PROG_LIBTOOL, , The @code{AC_PROG_LIBTOOL}
+macro, libtool, The Libtool Manual}.)
+
+ at cindex suffix @file{.lo}, defined
+Because object files for shared and static libraries must be compiled
+differently, libtool is also used during compilation. Object files
+built by libtool are called @dfn{libtool objects}: these are files
+using the @file{.lo} suffix. Libtool libraries are built from these
+libtool objects.
+
+You should not assume anything about the structure of @file{.la} or
+ at file{.lo} files and how libtool constructs them: this is libtool's
+concern, and the last thing one wants is to learn about libtool's
+guts. However the existence of these files matters, because they are
+used as targets and dependencies in @file{Makefile}s rules when
+building libtool libraries. There are situations where you may have
+to refer to these, for instance when expressing dependencies for
+building source files conditionally (@pxref{Conditional Libtool
+Sources}).
+
+ at cindex @file{libltdl}, introduction
+
+People considering writing a plug-in system, with dynamically loaded
+modules, should look into @file{libltdl}: libtool's dlopening library
+(@pxref{Using libltdl, , Using libltdl, libtool, The Libtool Manual}).
+This offers a portable dlopening facility to load libtool libraries
+dynamically, and can also achieve static linking where unavoidable.
+
+Before we discuss how to use libtool with Automake in details, it
+should be noted that the libtool manual also has a section about how
+to use Automake with libtool (@pxref{Using Automake, , Using Automake
+with Libtool, libtool, The Libtool Manual}).
+
+ at node Libtool Libraries
+ at subsection Building Libtool Libraries
+
+ at cindex @code{_LTLIBRARIES} primary, defined
+ at cindex @code{LTLIBRARIES} primary, defined
+ at cindex Primary variable, @code{LTLIBRARIES}
+ at cindex Example of shared libraries
+ at vindex lib_LTLIBRARIES
+ at vindex pkglib_LTLIBRARIES
+ at vindex _LTLIBRARIES
+
+Automake uses libtool to build libraries declared with the
+ at code{LTLIBRARIES} primary. Each @code{_LTLIBRARIES} variable is a
+list of libtool libraries to build. For instance, to create a libtool
+library named @file{libgettext.la}, and install it in @code{libdir},
+write:
+
+ at example
+lib_LTLIBRARIES = libgettext.la
+libgettext_la_SOURCES = gettext.c gettext.h @dots{}
+ at end example
+
+Automake predefines the variable @code{pkglibdir}, so you can use
+ at code{pkglib_LTLIBRARIES} to install libraries in
+ at samp{$(libdir)/@@PACKAGE@@/}.
+
+If @file{gettext.h} is a public header file that needs to be installed
+in order for people to use the library, it should be declared using a
+ at code{_HEADERS} variable, not in @code{libgettext_la_SOURCES}.
+Headers listed in the latter should be internal headers that are not
+part of the public interface.
+
+ at example
+lib_LTLIBRARIES = libgettext.la
+libgettext_la_SOURCES = gettext.c @dots{}
+include_HEADERS = gettext.h @dots{}
+ at end example
+
+A package can build and install such a library along with other
+programs that use it. This dependency should be specified using
+ at code{LDADD}. The following example builds a program named
+ at file{hello} that is linked with @file{libgettext.la}.
+
+ at example
+lib_LTLIBRARIES = libgettext.la
+libgettext_la_SOURCES = gettext.c @dots{}
+
+bin_PROGRAMS = hello
+hello_SOURCES = hello.c @dots{}
+hello_LDADD = libgettext.la
+ at end example
+
+ at noindent
+Whether @file{hello} is statically or dynamically linked with
+ at file{libgettext.la} is not yet known: this will depend on the
+configuration of libtool and the capabilities of the host.
+
+
+ at node Conditional Libtool Libraries
+ at subsection Building Libtool Libraries Conditionally
+ at cindex libtool libraries, conditional
+ at cindex conditional libtool libraries
+
+Like conditional programs (@pxref{Conditional Programs}), there are
+two main ways to build conditional libraries: using Automake
+conditionals or using Autoconf @code{AC_SUBST}itutions.
+
+The important implementation detail you have to be aware of is that
+the place where a library will be installed matters to libtool: it
+needs to be indicated @emph{at link-time} using the @option{-rpath}
+option.
+
+For libraries whose destination directory is known when Automake runs,
+Automake will automatically supply the appropriate @option{-rpath}
+option to libtool. This is the case for libraries listed explicitly in
+some installable @code{_LTLIBRARIES} variables such as
+ at code{lib_LTLIBRARIES}.
+
+However, for libraries determined at configure time (and thus
+mentioned in @code{EXTRA_LTLIBRARIES}), Automake does not know the
+final installation directory. For such libraries you must add the
+ at option{-rpath} option to the appropriate @code{_LDFLAGS} variable by
+hand.
+
+The examples below illustrate the differences between these two methods.
+
+Here is an example where @code{WANTEDLIBS} is an @code{AC_SUBST}ed
+variable set at @file{./configure}-time to either @file{libfoo.la},
+ at file{libbar.la}, both, or none. Although @samp{$(WANTEDLIBS)}
+appears in the @code{lib_LTLIBRARIES}, Automake cannot guess it
+relates to @file{libfoo.la} or @file{libbar.la} at the time it creates
+the link rule for these two libraries. Therefore the @option{-rpath}
+argument must be explicitly supplied.
+
+ at c Keep in sync with ltcond.test.
+ at example
+EXTRA_LTLIBRARIES = libfoo.la libbar.la
+lib_LTLIBRARIES = $(WANTEDLIBS)
+libfoo_la_SOURCES = foo.c @dots{}
+libfoo_la_LDFLAGS = -rpath '$(libdir)'
+libbar_la_SOURCES = bar.c @dots{}
+libbar_la_LDFLAGS = -rpath '$(libdir)'
+ at end example
+
+Here is how the same @file{Makefile.am} would look using Automake
+conditionals named @code{WANT_LIBFOO} and @code{WANT_LIBBAR}. Now
+Automake is able to compute the @option{-rpath} setting itself, because
+it's clear that both libraries will end up in @samp{$(libdir)} if they
+are installed.
+
+ at c Keep in sync with ltcond.test.
+ at example
+lib_LTLIBRARIES =
+if WANT_LIBFOO
+lib_LTLIBRARIES += libfoo.la
+endif
+if WANT_LIBBAR
+lib_LTLIBRARIES += libbar.la
+endif
+libfoo_la_SOURCES = foo.c @dots{}
+libbar_la_SOURCES = bar.c @dots{}
+ at end example
+
+ at node Conditional Libtool Sources
+ at subsection Libtool Libraries with Conditional Sources
+
+Conditional compilation of sources in a library can be achieved in the
+same way as conditional compilation of sources in a program
+(@pxref{Conditional Sources}). The only difference is that
+ at code{_LIBADD} should be used instead of @code{_LDADD} and that it
+should mention libtool objects (@file{.lo} files).
+
+So, to mimic the @file{hello} example from @ref{Conditional Sources},
+we could build a @file{libhello.la} library using either
+ at file{hello-linux.c} or @file{hello-generic.c} with the following
+ at file{Makefile.am}.
+
+ at c Keep in sync with ltcond2.test.
+ at example
+lib_LTLIBRARIES = libhello.la
+libhello_la_SOURCES = hello-common.c
+EXTRA_libhello_la_SOURCES = hello-linux.c hello-generic.c
+libhello_la_LIBADD = $(HELLO_SYSTEM)
+libhello_la_DEPENDENCIES = $(HELLO_SYSTEM)
+ at end example
+
+ at noindent
+And make sure @command{configure} defines @code{HELLO_SYSTEM} as
+either @file{hello-linux.lo} or @file{hello- at -generic.lo}.
+
+Or we could simply use an Automake conditional as follows.
+
+ at c Keep in sync with ltcond2.test.
+ at example
+lib_LTLIBRARIES = libhello.la
+libhello_la_SOURCES = hello-common.c
+if LINUX
+libhello_la_SOURCES += hello-linux.c
+else
+libhello_la_SOURCES += hello-generic.c
+endif
+ at end example
+
+ at node Libtool Convenience Libraries
+ at subsection Libtool Convenience Libraries
+ at cindex convenience libraries, libtool
+ at cindex libtool convenience libraries
+ at vindex noinst_LTLIBRARIES
+ at vindex check_LTLIBRARIES
+
+Sometimes you want to build libtool libraries that should not be
+installed. These are called @dfn{libtool convenience libraries} and
+are typically used to encapsulate many sublibraries, later gathered
+into one big installed library.
+
+Libtool convenience libraries are declared by directory-less variables
+such as @code{noinst_LTLIBRARIES}, @code{check_LTLIBRARIES}, or even
+ at code{EXTRA_LTLIBRARIES}. Unlike installed libtool libraries they do
+not need an @option{-rpath} flag at link time (actually this is the only
+difference).
+
+Convenience libraries listed in @code{noinst_LTLIBRARIES} are always
+built. Those listed in @code{check_LTLIBRARIES} are built only upon
+ at samp{make check}. Finally, libraries listed in
+ at code{EXTRA_LTLIBRARIES} are never built explicitly: Automake outputs
+rules to build them, but if the library does not appear as a Makefile
+dependency anywhere it won't be built (this is why
+ at code{EXTRA_LTLIBRARIES} is used for conditional compilation).
+
+Here is a sample setup merging libtool convenience libraries from
+subdirectories into one main @file{libtop.la} library.
+
+ at c Keep in sync with ltconv.test.
+ at example
+# -- Top-level Makefile.am --
+SUBDIRS = sub1 sub2 @dots{}
+lib_LTLIBRARIES = libtop.la
+libtop_la_SOURCES =
+libtop_la_LIBADD = \
+ sub1/libsub1.la \
+ sub2/libsub2.la \
+ @dots{}
+
+# -- sub1/Makefile.am --
+noinst_LTLIBRARIES = libsub1.la
+libsub1_la_SOURCES = @dots{}
+
+# -- sub2/Makefile.am --
+# showing nested convenience libraries
+SUBDIRS = sub2.1 sub2.2 @dots{}
+noinst_LTLIBRARIES = libsub2.la
+libsub2_la_SOURCES =
+libsub2_la_LIBADD = \
+ sub21/libsub21.la \
+ sub22/libsub22.la \
+ @dots{}
+ at end example
+
+When using such setup, beware that @command{automake} will assume
+ at file{libtop.la} is to be linked with the C linker. This is because
+ at code{libtop_la_SOURCES} is empty, so @command{automake} picks C as
+default language. If @code{libtop_la_SOURCES} was not empty,
+ at command{automake} would select the linker as explained in @ref{How
+the Linker is Chosen}.
+
+If one of the sublibraries contains non-C source, it is important that
+the appropriate linker be chosen. One way to achieve this is to
+pretend that there is such a non-C file among the sources of the
+library, thus forcing @command{automake} to select the appropriate
+linker. Here is the top-level @file{Makefile} of our example updated
+to force C++ linking.
+
+ at example
+SUBDIRS = sub1 sub2 @dots{}
+lib_LTLIBRARIES = libtop.la
+libtop_la_SOURCES =
+# Dummy C++ source to cause C++ linking.
+nodist_EXTRA_libtop_la_SOURCES = dummy.cxx
+libtop_la_LIBADD = \
+ sub1/libsub1.la \
+ sub2/libsub2.la \
+ @dots{}
+ at end example
+
+ at samp{EXTRA_*_SOURCES} variables are used to keep track of source
+files that might be compiled (this is mostly useful when doing
+conditional compilation using @code{AC_SUBST}, @pxref{Conditional
+Libtool Sources}), and the @code{nodist_} prefix means the listed
+sources are not to be distributed (@pxref{Program and Library
+Variables}). In effect the file @file{dummy.cxx} does not need to
+exist in the source tree. Of course if you have some real source file
+to list in @code{libtop_la_SOURCES} there is no point in cheating with
+ at code{nodist_EXTRA_libtop_la_SOURCES}.
+
+
+ at node Libtool Modules
+ at subsection Libtool Modules
+ at cindex modules, libtool
+ at cindex libtool modules
+ at cindex @option{-module}, libtool
+
+These are libtool libraries meant to be dlopened. They are
+indicated to libtool by passing @option{-module} at link-time.
+
+ at example
+pkglib_LTLIBRARIES = mymodule.la
+mymodule_la_SOURCES = doit.c
+mymodule_la_LDFLAGS = -module
+ at end example
+
+Ordinarily, Automake requires that a library's name start with
+ at code{lib}. However, when building a dynamically loadable module you
+might wish to use a "nonstandard" name. Automake will not complain
+about such nonstandard names if it knows the library being built is a
+libtool module, i.e., if @option{-module} explicitly appears in the
+library's @code{_LDFLAGS} variable (or in the common @code{AM_LDFLAGS}
+variable when no per-library @code{_LDFLAGS} variable is defined).
+
+As always, @code{AC_SUBST} variables are black boxes to Automake since
+their values are not yet known when @command{automake} is run.
+Therefore if @option{-module} is set via such a variable, Automake
+cannot notice it and will proceed as if the library was an ordinary
+libtool library, with strict naming.
+
+If @code{mymodule_la_SOURCES} is not specified, then it defaults to
+the single file @file{mymodule.c} (@pxref{Default _SOURCES}).
+
+ at node Libtool Flags
+ at subsection @code{_LIBADD}, @code{_LDFLAGS}, and @code{_LIBTOOLFLAGS}
+ at cindex @code{_LIBADD}, libtool
+ at cindex @code{_LDFLAGS}, libtool
+ at cindex @code{_LIBTOOLFLAGS}, libtool
+ at vindex AM_LIBTOOLFLAGS
+ at vindex LIBTOOLFLAGS
+ at vindex maude_LIBTOOLFLAGS
+
+As shown in previous sections, the @samp{@var{library}_LIBADD}
+variable should be used to list extra libtool objects (@file{.lo}
+files) or libtool libraries (@file{.la}) to add to @var{library}.
+
+The @samp{@var{library}_LDFLAGS} variable is the place to list
+additional libtool linking flags, such as @option{-version-info},
+ at option{-static}, and a lot more. @xref{Link mode, , Link mode,
+libtool, The Libtool Manual}.
+
+The @command{libtool} command has two kinds of options: mode-specific
+options and generic options. Mode-specific options such as the
+aforementioned linking flags should be lumped with the other flags
+passed to the tool invoked by @command{libtool} (hence the use of
+ at samp{@var{library}_LDFLAGS} for libtool linking flags). Generic
+options include @option{--tag=@var{tag}} and @option{--silent}
+(@pxref{Invoking libtool, , Invoking @command{libtool}, libtool, The
+Libtool Manual} for more options) should appear before the mode
+selection on the command line; in @file{Makefile.am}s they should
+be listed in the @samp{@var{library}_LIBTOOLFLAGS} variable.
+
+If @samp{@var{library}_LIBTOOLFLAGS} is not defined, then the variable
+ at code{AM_LIBTOOLFLAGS} is used instead.
+
+These flags are passed to libtool after the @option{--tag=@var{tag}}
+option computed by Automake (if any), so
+ at samp{@var{library}_LIBTOOLFLAGS} (or @code{AM_LIBTOOLFLAGS}) is a
+good place to override or supplement the @option{--tag=@var{tag}}
+setting.
+
+The libtool rules also use a @code{LIBTOOLFLAGS} variable that should
+not be set in @file{Makefile.am}: this is a user variable (@pxref{Flag
+Variables Ordering}. It allows users to run @samp{make
+LIBTOOLFLAGS=--silent}, for instance. Note that the verbosity of
+ at command{libtool} can also be influenced with the Automake
+ at option{silent-rules} option (@pxref{Options}).
+
+
+ at node LTLIBOBJS, Libtool Issues, Libtool Flags, A Shared Library
+ at subsection @code{LTLIBOBJS} and @code{LTALLOCA}
+ at cindex @code{LTLIBOBJS}, special handling
+ at cindex @code{LIBOBJS}, and Libtool
+ at cindex @code{LTALLOCA}, special handling
+ at cindex @code{ALLOCA}, and Libtool
+ at vindex LTLIBOBJS
+ at vindex LIBOBJS
+ at vindex LTALLOCA
+ at vindex ALLOCA
+ at acindex AC_LIBOBJ
+
+Where an ordinary library might include @samp{$(LIBOBJS)} or
+ at samp{$(ALLOCA)} (@pxref{LIBOBJS}), a libtool library must use
+ at samp{$(LTLIBOBJS)} or @samp{$(LTALLOCA)}. This is required because
+the object files that libtool operates on do not necessarily end in
+ at file{.o}.
+
+Nowadays, the computation of @code{LTLIBOBJS} from @code{LIBOBJS} is
+performed automatically by Autoconf (@pxref{AC_LIBOBJ vs LIBOBJS, ,
+ at code{AC_LIBOBJ} vs.@: @code{LIBOBJS}, autoconf, The Autoconf Manual}).
+
+ at node Libtool Issues
+ at subsection Common Issues Related to Libtool's Use
+
+ at menu
+* Error required file ltmain.sh not found:: The need to run libtoolize
+* Objects created both with libtool and without:: Avoid a specific build race
+ at end menu
+
+ at node Error required file ltmain.sh not found
+ at subsubsection Error: @samp{required file `./ltmain.sh' not found}
+ at cindex @file{ltmain.sh} not found
+ at cindex @command{libtoolize}, no longer run by @command{automake}
+ at cindex @command{libtoolize} and @command{autoreconf}
+ at cindex @command{autoreconf} and @command{libtoolize}
+ at cindex @file{bootstrap.sh} and @command{autoreconf}
+ at cindex @file{autogen.sh} and @command{autoreconf}
+
+Libtool comes with a tool called @command{libtoolize} that will
+install libtool's supporting files into a package. Running this
+command will install @file{ltmain.sh}. You should execute it before
+ at command{aclocal} and @command{automake}.
+
+People upgrading old packages to newer autotools are likely to face
+this issue because older Automake versions used to call
+ at command{libtoolize}. Therefore old build scripts do not call
+ at command{libtoolize}.
+
+Since Automake 1.6, it has been decided that running
+ at command{libtoolize} was none of Automake's business. Instead, that
+functionality has been moved into the @command{autoreconf} command
+(@pxref{autoreconf Invocation, , Using @command{autoreconf}, autoconf,
+The Autoconf Manual}). If you do not want to remember what to run and
+when, just learn the @command{autoreconf} command. Hopefully,
+replacing existing @file{bootstrap.sh} or @file{autogen.sh} scripts by
+a call to @command{autoreconf} should also free you from any similar
+incompatible change in the future.
+
+ at node Objects created both with libtool and without
+ at subsubsection Objects @samp{created with both libtool and without}
+
+Sometimes, the same source file is used both to build a libtool
+library and to build another non-libtool target (be it a program or
+another library).
+
+Let's consider the following @file{Makefile.am}.
+
+ at example
+bin_PROGRAMS = prog
+prog_SOURCES = prog.c foo.c @dots{}
+
+lib_LTLIBRARIES = libfoo.la
+libfoo_la_SOURCES = foo.c @dots{}
+ at end example
+
+ at noindent
+(In this trivial case the issue could be avoided by linking
+ at file{libfoo.la} with @file{prog} instead of listing @file{foo.c} in
+ at code{prog_SOURCES}. But let's assume we really want to keep
+ at file{prog} and @file{libfoo.la} separate.)
+
+Technically, it means that we should build @file{foo.$(OBJEXT)} for
+ at file{prog}, and @file{foo.lo} for @file{libfoo.la}. The problem is
+that in the course of creating @file{foo.lo}, libtool may erase (or
+replace) @file{foo.$(OBJEXT)}, and this cannot be avoided.
+
+Therefore, when Automake detects this situation it will complain
+with a message such as
+ at example
+object `foo.$(OBJEXT)' created both with libtool and without
+ at end example
+
+A workaround for this issue is to ensure that these two objects get
+different basenames. As explained in @ref{Renamed Objects}, this
+happens automatically when per-targets flags are used.
+
+ at example
+bin_PROGRAMS = prog
+prog_SOURCES = prog.c foo.c @dots{}
+prog_CFLAGS = $(AM_CFLAGS)
+
+lib_LTLIBRARIES = libfoo.la
+libfoo_la_SOURCES = foo.c @dots{}
+ at end example
+
+ at noindent
+Adding @samp{prog_CFLAGS = $(AM_CFLAGS)} is almost a no-op, because
+when the @code{prog_CFLAGS} is defined, it is used instead of
+ at code{AM_CFLAGS}. However as a side effect it will cause
+ at file{prog.c} and @file{foo.c} to be compiled as
+ at file{prog-prog.$(OBJEXT)} and @file{prog-foo.$(OBJEXT)}, which solves
+the issue.
+
+ at node Program and Library Variables
+ at section Program and Library Variables
+
+Associated with each program is a collection of variables that can be
+used to modify how that program is built. There is a similar list of
+such variables for each library. The canonical name of the program (or
+library) is used as a base for naming these variables.
+
+In the list below, we use the name ``maude'' to refer to the program or
+library. In your @file{Makefile.am} you would replace this with the
+canonical name of your program. This list also refers to ``maude'' as a
+program, but in general the same rules apply for both static and dynamic
+libraries; the documentation below notes situations where programs and
+libraries differ.
+
+ at vtable @code
+ at item maude_SOURCES
+This variable, if it exists, lists all the source files that are
+compiled to build the program. These files are added to the
+distribution by default. When building the program, Automake will cause
+each source file to be compiled to a single @file{.o} file (or
+ at file{.lo} when using libtool). Normally these object files are named
+after the source file, but other factors can change this. If a file in
+the @code{_SOURCES} variable has an unrecognized extension, Automake
+will do one of two things with it. If a suffix rule exists for turning
+files with the unrecognized extension into @file{.o} files, then
+ at command{automake} will treat this file as it will any other source file
+(@pxref{Support for Other Languages}). Otherwise, the file will be
+ignored as though it were a header file.
+
+The prefixes @code{dist_} and @code{nodist_} can be used to control
+whether files listed in a @code{_SOURCES} variable are distributed.
+ at code{dist_} is redundant, as sources are distributed by default, but it
+can be specified for clarity if desired.
+
+It is possible to have both @code{dist_} and @code{nodist_} variants of
+a given @code{_SOURCES} variable at once; this lets you easily
+distribute some files and not others, for instance:
+
+ at example
+nodist_maude_SOURCES = nodist.c
+dist_maude_SOURCES = dist-me.c
+ at end example
+
+By default the output file (on Unix systems, the @file{.o} file) will
+be put into the current build directory. However, if the option
+ at option{subdir-objects} is in effect in the current directory then the
+ at file{.o} file will be put into the subdirectory named after the
+source file. For instance, with @option{subdir-objects} enabled,
+ at file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}. Some
+people prefer this mode of operation. You can specify
+ at option{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
+ at cindex Subdirectory, objects in
+ at cindex Objects in subdirectory
+
+
+ at item EXTRA_maude_SOURCES
+Automake needs to know the list of files you intend to compile
+ at emph{statically}. For one thing, this is the only way Automake has of
+knowing what sort of language support a given @file{Makefile.in}
+requires. @footnote{There are other, more obscure reasons for
+this limitation as well.} This means that, for example, you can't put a
+configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
+variable. If you intend to conditionally compile source files and use
+ at file{configure} to substitute the appropriate object names into, e.g.,
+ at code{_LDADD} (see below), then you should list the corresponding source
+files in the @code{EXTRA_} variable.
+
+This variable also supports @code{dist_} and @code{nodist_} prefixes.
+For instance, @code{nodist_EXTRA_maude_SOURCES} would list extra
+sources that may need to be built, but should not be distributed.
+
+ at item maude_AR
+A static library is created by default by invoking @samp{$(AR)
+$(ARFLAGS)} followed by the name of the library and then the objects
+being put into the library. You can override this by setting the
+ at code{_AR} variable. This is usually used with C++; some C++
+compilers require a special invocation in order to instantiate all the
+templates that should go into a library. For instance, the SGI C++
+compiler likes this variable set like so:
+ at example
+libmaude_a_AR = $(CXX) -ar -o
+ at end example
+
+ at item maude_LIBADD
+Extra objects can be added to a @emph{library} using the @code{_LIBADD}
+variable. For instance, this should be used for objects determined by
+ at command{configure} (@pxref{A Library}).
+
+In the case of libtool libraries, @code{maude_LIBADD} can also refer
+to other libtool libraries.
+
+ at item maude_LDADD
+Extra objects (@file{*.$(OBJEXT)}) and libraries (@file{*.a},
+ at file{*.la}) can be added to a @emph{program} by listing them in the
+ at code{_LDADD} variable. For instance, this should be used for objects
+determined by @command{configure} (@pxref{Linking}).
+
+ at code{_LDADD} and @code{_LIBADD} are inappropriate for passing
+program-specific linker flags (except for @option{-l}, @option{-L},
+ at option{-dlopen} and @option{-dlpreopen}). Use the @code{_LDFLAGS} variable
+for this purpose.
+
+For instance, if your @file{configure.ac} uses @code{AC_PATH_XTRA}, you
+could link your program against the X libraries like so:
+
+ at example
+maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
+ at end example
+
+We recommend that you use @option{-l} and @option{-L} only when
+referring to third-party libraries, and give the explicit file names
+of any library built by your package. Doing so will ensure that
+ at code{maude_DEPENDENCIES} (see below) is correctly defined by default.
+
+ at item maude_LDFLAGS
+This variable is used to pass extra flags to the link step of a program
+or a shared library. It overrides the @code{AM_LDFLAGS} variable.
+
+ at item maude_LIBTOOLFLAGS
+This variable is used to pass extra options to @command{libtool}.
+It overrides the @code{AM_LIBTOOLFLAGS} variable.
+These options are output before @command{libtool}'s @option{--mode=@var{mode}}
+option, so they should not be mode-specific options (those belong to
+the compiler or linker flags). @xref{Libtool Flags}.
+
+ at item maude_DEPENDENCIES
+ at itemx EXTRA_maude_DEPENDENCIES
+It is also occasionally useful to have a target (program or library)
+depend on some other file that is not actually part of that target.
+This can be done using the @code{_DEPENDENCIES} variable. Each
+target depends on the contents of such a variable, but no further
+interpretation is done.
+
+Since these dependencies are associated to the link rule used to
+create the programs they should normally list files used by the link
+command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la} files
+for programs; @file{*.lo} and @file{*.la} files for Libtool libraries;
+and @file{*.$(OBJEXT)} files for static libraries. In rare cases you
+may need to add other kinds of files such as linker scripts, but
+ at emph{listing a source file in @code{_DEPENDENCIES} is wrong}. If
+some source file needs to be built before all the components of a
+program are built, consider using the @code{BUILT_SOURCES} variable
+(@pxref{Sources}).
+
+If @code{_DEPENDENCIES} is not supplied, it is computed by Automake.
+The automatically-assigned value is the contents of @code{_LDADD} or
+ at code{_LIBADD}, with most configure substitutions, @option{-l}, @option{-L},
+ at option{-dlopen} and @option{-dlpreopen} options removed. The configure
+substitutions that are left in are only @samp{$(LIBOBJS)} and
+ at samp{$(ALLOCA)}; these are left because it is known that they will not
+cause an invalid value for @code{_DEPENDENCIES} to be generated.
+
+ at code{_DEPENDENCIES} is more likely used to perform conditional
+compilation using an @code{AC_SUBST} variable that contains a list of
+objects. @xref{Conditional Sources}, and @ref{Conditional Libtool
+Sources}.
+
+The @code{EXTRA_*_DEPENDENCIES} variable may be useful for cases where
+you merely want to augment the @command{automake}-generated
+ at code{_DEPENDENCIES} variable rather than replacing it.
+
+ at item maude_LINK
+You can override the linker on a per-program basis. By default the
+linker is chosen according to the languages used by the program. For
+instance, a program that includes C++ source code would use the C++
+compiler to link. The @code{_LINK} variable must hold the name of a
+command that can be passed all the @file{.o} file names and libraries
+to link against as arguments. Note that the name of the underlying
+program is @emph{not} passed to @code{_LINK}; typically one uses
+ at samp{$@@}:
+
+ at example
+maude_LINK = $(CCLD) -magic -o $@@
+ at end example
+
+If a @code{_LINK} variable is not supplied, it may still be generated
+and used by Automake due to the use of per-target link flags such as
+ at code{_CFLAGS}, @code{_LDFLAGS} or @code{_LIBTOOLFLAGS}, in cases where
+they apply.
+
+ at item maude_CCASFLAGS
+ at itemx maude_CFLAGS
+ at itemx maude_CPPFLAGS
+ at itemx maude_CXXFLAGS
+ at itemx maude_FFLAGS
+ at itemx maude_GCJFLAGS
+ at itemx maude_LFLAGS
+ at itemx maude_OBJCFLAGS
+ at itemx maude_RFLAGS
+ at itemx maude_UPCFLAGS
+ at itemx maude_YFLAGS
+ at cindex per-target compilation flags, defined
+Automake allows you to set compilation flags on a per-program (or
+per-library) basis. A single source file can be included in several
+programs, and it will potentially be compiled with different flags for
+each program. This works for any language directly supported by
+Automake. These @dfn{per-target compilation flags} are
+ at samp{_CCASFLAGS},
+ at samp{_CFLAGS},
+ at samp{_CPPFLAGS},
+ at samp{_CXXFLAGS},
+ at samp{_FFLAGS},
+ at samp{_GCJFLAGS},
+ at samp{_LFLAGS},
+ at samp{_OBJCFLAGS},
+ at samp{_RFLAGS},
+ at samp{_UPCFLAGS}, and
+ at samp{_YFLAGS}.
+
+When using a per-target compilation flag, Automake will choose a
+different name for the intermediate object files. Ordinarily a file
+like @file{sample.c} will be compiled to produce @file{sample.o}.
+However, if the program's @code{_CFLAGS} variable is set, then the
+object file will be named, for instance, @file{maude-sample.o}. (See
+also @ref{Renamed Objects}.) The use of per-target compilation flags
+with C sources requires that the macro @code{AM_PROG_CC_C_O} be called
+from @file{configure.ac}.
+
+In compilations with per-target flags, the ordinary @samp{AM_} form of
+the flags variable is @emph{not} automatically included in the
+compilation (however, the user form of the variable @emph{is} included).
+So for instance, if you want the hypothetical @file{maude} compilations
+to also use the value of @code{AM_CFLAGS}, you would need to write:
+
+ at example
+maude_CFLAGS = @dots{} your flags @dots{} $(AM_CFLAGS)
+ at end example
+
+ at xref{Flag Variables Ordering}, for more discussion about the
+interaction between user variables, @samp{AM_} shadow variables, and
+per-target variables.
+
+ at item maude_SHORTNAME
+On some platforms the allowable file names are very short. In order to
+support these systems and per-target compilation flags at the same
+time, Automake allows you to set a ``short name'' that will influence
+how intermediate object files are named. For instance, in the following
+example,
+
+ at example
+bin_PROGRAMS = maude
+maude_CPPFLAGS = -DSOMEFLAG
+maude_SHORTNAME = m
+maude_SOURCES = sample.c @dots{}
+ at end example
+
+ at noindent
+the object file would be named @file{m-sample.o} rather than
+ at file{maude-sample.o}.
+
+This facility is rarely needed in practice,
+and we recommend avoiding it until you find it is required.
+ at end vtable
+
+ at node Default _SOURCES
+ at section Default @code{_SOURCES}
+
+ at vindex _SOURCES
+ at vindex SOURCES
+ at cindex @code{_SOURCES}, default
+ at cindex default @code{_SOURCES}
+ at vindex AM_DEFAULT_SOURCE_EXT
+
+ at code{_SOURCES} variables are used to specify source files of programs
+(@pxref{A Program}), libraries (@pxref{A Library}), and Libtool
+libraries (@pxref{A Shared Library}).
+
+When no such variable is specified for a target, Automake will define
+one itself. The default is to compile a single C file whose base name
+is the name of the target itself, with any extension replaced by
+ at code{AM_DEFAULT_SOURCE_EXT}, which defaults to @file{.c}.
+
+For example if you have the following somewhere in your
+ at file{Makefile.am} with no corresponding @code{libfoo_a_SOURCES}:
+
+ at example
+lib_LIBRARIES = libfoo.a sub/libc++.a
+ at end example
+
+ at noindent
+ at file{libfoo.a} will be built using a default source file named
+ at file{libfoo.c}, and @file{sub/libc++.a} will be built from
+ at file{sub/libc++.c}. (In older versions @file{sub/libc++.a}
+would be built from @file{sub_libc___a.c}, i.e., the default source
+was the canonized name of the target, with @file{.c} appended.
+We believe the new behavior is more sensible, but for backward
+compatibility @command{automake} will use the old name if a file or a rule
+with that name exists and @code{AM_DEFAULT_SOURCE_EXT} is not used.)
+
+ at cindex @code{check_PROGRAMS} example
+ at vindex check_PROGRAMS
+Default sources are mainly useful in test suites, when building many
+test programs each from a single source. For instance, in
+
+ at example
+check_PROGRAMS = test1 test2 test3
+AM_DEFAULT_SOURCE_EXT = .cpp
+ at end example
+
+ at noindent
+ at file{test1}, @file{test2}, and @file{test3} will be built
+from @file{test1.cpp}, @file{test2.cpp}, and @file{test3.cpp}.
+Without the last line, they will be built from @file{test1.c},
+ at file{test2.c}, and @file{test3.c}.
+
+ at cindex Libtool modules, default source example
+ at cindex default source, Libtool modules example
+Another case where this is convenient is building many Libtool modules
+(@file{module at var{n}.la}), each defined in its own file
+(@file{module at var{n}.c}).
+
+ at example
+AM_LDFLAGS = -module
+lib_LTLIBRARIES = module1.la module2.la module3.la
+ at end example
+
+ at cindex empty @code{_SOURCES}
+ at cindex @code{_SOURCES}, empty
+Finally, there is one situation where this default source computation
+needs to be avoided: when a target should not be built from sources.
+We already saw such an example in @ref{true}; this happens when all
+the constituents of a target have already been compiled and just need
+to be combined using a @code{_LDADD} variable. Then it is necessary
+to define an empty @code{_SOURCES} variable, so that @command{automake}
+does not compute a default.
+
+ at example
+bin_PROGRAMS = target
+target_SOURCES =
+target_LDADD = libmain.a libmisc.a
+ at end example
+
+ at node LIBOBJS
+ at section Special handling for @code{LIBOBJS} and @code{ALLOCA}
+
+ at cindex @code{LIBOBJS}, example
+ at cindex @code{ALLOCA}, example
+ at cindex @code{LIBOBJS}, special handling
+ at cindex @code{ALLOCA}, special handling
+ at vindex LTLIBOBJS
+ at vindex LIBOBJS
+ at vindex LTALLOCA
+ at vindex ALLOCA
+
+The @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} variables list object
+files that should be compiled into the project to provide an
+implementation for functions that are missing or broken on the host
+system. They are substituted by @file{configure}.
+
+ at acindex AC_LIBOBJ
+
+These variables are defined by Autoconf macros such as
+ at code{AC_LIBOBJ}, @code{AC_REPLACE_FUNCS} (@pxref{Generic Functions, ,
+Generic Function Checks, autoconf, The Autoconf Manual}), or
+ at code{AC_FUNC_ALLOCA} (@pxref{Particular Functions, , Particular
+Function Checks, autoconf, The Autoconf Manual}). Many other Autoconf
+macros call @code{AC_LIBOBJ} or @code{AC_REPLACE_FUNCS} to
+populate @samp{$(LIBOBJS)}.
+
+ at acindex AC_LIBSOURCE
+
+Using these variables is very similar to doing conditional compilation
+using @code{AC_SUBST} variables, as described in @ref{Conditional
+Sources}. That is, when building a program, @samp{$(LIBOBJS)} and
+ at samp{$(ALLOCA)} should be added to the associated @samp{*_LDADD}
+variable, or to the @samp{*_LIBADD} variable when building a library.
+However there is no need to list the corresponding sources in
+ at samp{EXTRA_*_SOURCES} nor to define @samp{*_DEPENDENCIES}. Automake
+automatically adds @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} to the
+dependencies, and it will discover the list of corresponding source
+files automatically (by tracing the invocations of the
+ at code{AC_LIBSOURCE} Autoconf macros). If you have already defined
+ at samp{*_DEPENDENCIES} explicitly for an unrelated reason, then you
+either need to add these variables manually, or use
+ at samp{EXTRA_*_DEPENDENCIES} instead of @samp{*_DEPENDENCIES}.
+
+These variables are usually used to build a portability library that
+is linked with all the programs of the project. We now review a
+sample setup. First, @file{configure.ac} contains some checks that
+affect either @code{LIBOBJS} or @code{ALLOCA}.
+
+ at example
+# configure.ac
+ at dots{}
+AC_CONFIG_LIBOBJ_DIR([lib])
+ at dots{}
+AC_FUNC_MALLOC dnl May add malloc.$(OBJEXT) to LIBOBJS
+AC_FUNC_MEMCMP dnl May add memcmp.$(OBJEXT) to LIBOBJS
+AC_REPLACE_FUNCS([strdup]) dnl May add strdup.$(OBJEXT) to LIBOBJS
+AC_FUNC_ALLOCA dnl May add alloca.$(OBJEXT) to ALLOCA
+ at dots{}
+AC_CONFIG_FILES([
+ lib/Makefile
+ src/Makefile
+])
+AC_OUTPUT
+ at end example
+
+ at acindex AC_CONFIG_LIBOBJ_DIR
+
+The @code{AC_CONFIG_LIBOBJ_DIR} tells Autoconf that the source files
+of these object files are to be found in the @file{lib/} directory.
+Automake can also use this information, otherwise it expects the
+source files are to be in the directory where the @samp{$(LIBOBJS)}
+and @samp{$(ALLOCA)} variables are used.
+
+The @file{lib/} directory should therefore contain @file{malloc.c},
+ at file{memcmp.c}, @file{strdup.c}, @file{alloca.c}. Here is its
+ at file{Makefile.am}:
+
+ at example
+# lib/Makefile.am
+
+noinst_LIBRARIES = libcompat.a
+libcompat_a_SOURCES =
+libcompat_a_LIBADD = $(LIBOBJS) $(ALLOCA)
+ at end example
+
+The library can have any name, of course, and anyway it is not going
+to be installed: it just holds the replacement versions of the missing
+or broken functions so we can later link them in. Many projects
+also include extra functions, specific to the project, in that
+library: they are simply added on the @code{_SOURCES} line.
+
+ at cindex Empty libraries and @samp{$(LIBOBJS)}
+ at cindex @samp{$(LIBOBJS)} and empty libraries
+There is a small trap here, though: @samp{$(LIBOBJS)} and
+ at samp{$(ALLOCA)} might be empty, and building an empty library is not
+portable. You should ensure that there is always something to put in
+ at file{libcompat.a}. Most projects will also add some utility
+functions in that directory, and list them in
+ at code{libcompat_a_SOURCES}, so in practice @file{libcompat.a} cannot
+be empty.
+
+Finally here is how this library could be used from the @file{src/}
+directory.
+
+ at example
+# src/Makefile.am
+
+# Link all programs in this directory with libcompat.a
+LDADD = ../lib/libcompat.a
+
+bin_PROGRAMS = tool1 tool2 @dots{}
+tool1_SOURCES = @dots{}
+tool2_SOURCES = @dots{}
+ at end example
+
+When option @option{subdir-objects} is not used, as in the above
+example, the variables @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} can only
+be used in the directory where their sources lie. E.g., here it would
+be wrong to use @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} in
+ at file{src/Makefile.am}. However if both @option{subdir-objects} and
+ at code{AC_CONFIG_LIBOBJ_DIR} are used, it is OK to use these variables
+in other directories. For instance @file{src/Makefile.am} could be
+changed as follows.
+
+ at example
+# src/Makefile.am
+
+AUTOMAKE_OPTIONS = subdir-objects
+LDADD = $(LIBOBJS) $(ALLOCA)
+
+bin_PROGRAMS = tool1 tool2 @dots{}
+tool1_SOURCES = @dots{}
+tool2_SOURCES = @dots{}
+ at end example
+
+Because @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} contain object
+file names that end with @samp{.$(OBJEXT)}, they are not suitable for
+Libtool libraries (where the expected object extension is @file{.lo}):
+ at code{LTLIBOBJS} and @code{LTALLOCA} should be used instead.
+
+ at code{LTLIBOBJS} is defined automatically by Autoconf and should not
+be defined by hand (as in the past), however at the time of writing
+ at code{LTALLOCA} still needs to be defined from @code{ALLOCA} manually.
+ at xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
+autoconf, The Autoconf Manual}.
+
+
+ at node Program Variables
+ at section Variables used when building a program
+
+Occasionally it is useful to know which @file{Makefile} variables
+Automake uses for compilations, and in which order (@pxref{Flag
+Variables Ordering}); for instance, you might need to do your own
+compilation in some special cases.
+
+Some variables are inherited from Autoconf; these are @code{CC},
+ at code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
+ at code{LIBS}.
+ at vindex CC
+ at vindex CFLAGS
+ at vindex CPPFLAGS
+ at vindex DEFS
+ at vindex LDFLAGS
+ at vindex LIBS
+
+There are some additional variables that Automake defines on its own:
+
+ at vtable @code
+ at item AM_CPPFLAGS
+The contents of this variable are passed to every compilation that invokes
+the C preprocessor; it is a list of arguments to the preprocessor. For
+instance, @option{-I} and @option{-D} options should be listed here.
+
+Automake already provides some @option{-I} options automatically, in a
+separate variable that is also passed to every compilation that invokes
+the C preprocessor. In particular it generates @samp{-I.},
+ at samp{-I$(srcdir)}, and a @option{-I} pointing to the directory holding
+ at file{config.h} (if you've used @code{AC_CONFIG_HEADERS} or
+ at code{AM_CONFIG_HEADER}). You can disable the default @option{-I}
+options using the @option{nostdinc} option.
+
+When a file to be included is generated during the build and not part
+of a distribution tarball, its location is under @code{$(builddir)},
+not under @code{$(srcdir)}. This matters especially for packages that
+use header files placed in sub-directories and want to allow builds
+outside the source tree (@pxref{VPATH Builds}). In that case we
+recommend to use a pair of @option{-I} options, such as, e.g.,
+ at samp{-Isome/subdir -I$(srcdir)/some/subdir} or
+ at samp{-I$(top_builddir)/some/subdir -I$(top_srcdir)/some/subdir}.
+Note that the reference to the build tree should come before the
+reference to the source tree, so that accidentally leftover generated
+files in the source directory are ignored.
+
+ at code{AM_CPPFLAGS} is ignored in preference to a per-executable (or
+per-library) @code{_CPPFLAGS} variable if it is defined.
+
+ at item INCLUDES
+This does the same job as @code{AM_CPPFLAGS} (or any per-target
+ at code{_CPPFLAGS} variable if it is used). It is an older name for the
+same functionality. This variable is deprecated; we suggest using
+ at code{AM_CPPFLAGS} and per-target @code{_CPPFLAGS} instead.
+
+ at item AM_CFLAGS
+This is the variable the @file{Makefile.am} author can use to pass
+in additional C compiler flags. It is more fully documented elsewhere.
+In some situations, this is not used, in preference to the
+per-executable (or per-library) @code{_CFLAGS}.
+
+ at item COMPILE
+This is the command used to actually compile a C source file. The
+file name is appended to form the complete command line.
+
+ at item AM_LDFLAGS
+This is the variable the @file{Makefile.am} author can use to pass
+in additional linker flags. In some situations, this is not used, in
+preference to the per-executable (or per-library) @code{_LDFLAGS}.
+
+ at item LINK
+This is the command used to actually link a C program. It already
+includes @samp{-o $@@} and the usual variable references (for instance,
+ at code{CFLAGS}); it takes as ``arguments'' the names of the object files
+and libraries to link in. This variable is not used when the linker is
+overridden with a per-target @code{_LINK} variable or per-target flags
+cause Automake to define such a @code{_LINK} variable.
+ at end vtable
+
+
+ at node Yacc and Lex
+ at section Yacc and Lex support
+
+Automake has somewhat idiosyncratic support for Yacc and Lex.
+
+Automake assumes that the @file{.c} file generated by @command{yacc}
+(or @command{lex}) should be named using the basename of the input
+file. That is, for a yacc source file @file{foo.y}, Automake will
+cause the intermediate file to be named @file{foo.c} (as opposed to
+ at file{y.tab.c}, which is more traditional).
+
+The extension of a yacc source file is used to determine the extension
+of the resulting C or C++ file. Files with the extension @file{.y}
+will be turned into @file{.c} files; likewise, @file{.yy} will become
+ at file{.cc}; @file{.y++}, @file{c++}; @file{.yxx}, @file{.cxx}; and
+ at file{.ypp}, @file{.cpp}.
+
+Likewise, lex source files can be used to generate C or C++; the
+extensions @file{.l}, @file{.ll}, @file{.l++}, @file{.lxx}, and
+ at file{.lpp} are recognized.
+
+You should never explicitly mention the intermediate (C or C++) file
+in any @code{SOURCES} variable; only list the source file.
+
+The intermediate files generated by @command{yacc} (or @command{lex})
+will be included in any distribution that is made. That way the user
+doesn't need to have @command{yacc} or @command{lex}.
+
+If a @command{yacc} source file is seen, then your @file{configure.ac} must
+define the variable @code{YACC}. This is most easily done by invoking
+the macro @code{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
+Program Checks, autoconf, The Autoconf Manual}).
+
+ at vindex YFLAGS
+ at vindex AM_YFLAGS
+When @code{yacc} is invoked, it is passed @code{AM_YFLAGS} and
+ at code{YFLAGS}. The latter is a user variable and the former is
+intended for the @file{Makefile.am} author.
+
+ at code{AM_YFLAGS} is usually used to pass the @option{-d} option to
+ at command{yacc}. Automake knows what this means and will automatically
+adjust its rules to update and distribute the header file built by
+ at samp{yacc -d}@footnote{Please note that @command{automake} recognizes
+ at option{-d} in @code{AM_YFLAGS} only if it is not clustered with other
+options; for example, it won't be recognized if @code{AM_YFLAGS} is
+ at option{-dt}, but it will be if @code{AM_YFLAGS} is @option{-d -t} or
+ at option{-d -t}}.
+What Automake cannot guess, though, is where this
+header will be used: it is up to you to ensure the header gets built
+before it is first used. Typically this is necessary in order for
+dependency tracking to work when the header is included by another
+file. The common solution is listing the header file in
+ at code{BUILT_SOURCES} (@pxref{Sources}) as follows.
+
+ at example
+BUILT_SOURCES = parser.h
+AM_YFLAGS = -d
+bin_PROGRAMS = foo
+foo_SOURCES = @dots{} parser.y @dots{}
+ at end example
+
+If a @command{lex} source file is seen, then your @file{configure.ac}
+must define the variable @code{LEX}. You can use @code{AC_PROG_LEX}
+to do this (@pxref{Particular Programs, , Particular Program Checks,
+autoconf, The Autoconf Manual}), but using @code{AM_PROG_LEX} macro
+(@pxref{Macros}) is recommended.
+
+ at vindex LFLAGS
+ at vindex AM_LFLAGS
+When @command{lex} is invoked, it is passed @code{AM_LFLAGS} and
+ at code{LFLAGS}. The latter is a user variable and the former is
+intended for the @file{Makefile.am} author.
+
+When @code{AM_MAINTAINER_MODE} (@pxref{maintainer-mode}) is used, the
+rebuild rule for distributed Yacc and Lex sources are only used when
+ at code{maintainer-mode} is enabled, or when the files have been erased.
+
+ at cindex @command{ylwrap}
+ at cindex @command{yacc}, multiple parsers
+ at cindex Multiple @command{yacc} parsers
+ at cindex Multiple @command{lex} lexers
+ at cindex @command{lex}, multiple lexers
+
+When @command{lex} or @command{yacc} sources are used, @code{automake
+-i} automatically installs an auxiliary program called
+ at command{ylwrap} in your package (@pxref{Auxiliary Programs}). This
+program is used by the build rules to rename the output of these
+tools, and makes it possible to include multiple @command{yacc} (or
+ at command{lex}) source files in a single directory. (This is necessary
+because yacc's output file name is fixed, and a parallel make could
+conceivably invoke more than one instance of @command{yacc}
+simultaneously.)
+
+For @command{yacc}, simply managing locking is insufficient. The output of
+ at command{yacc} always uses the same symbol names internally, so it isn't
+possible to link two @command{yacc} parsers into the same executable.
+
+We recommend using the following renaming hack used in @command{gdb}:
+ at example
+#define yymaxdepth c_maxdepth
+#define yyparse c_parse
+#define yylex c_lex
+#define yyerror c_error
+#define yylval c_lval
+#define yychar c_char
+#define yydebug c_debug
+#define yypact c_pact
+#define yyr1 c_r1
+#define yyr2 c_r2
+#define yydef c_def
+#define yychk c_chk
+#define yypgo c_pgo
+#define yyact c_act
+#define yyexca c_exca
+#define yyerrflag c_errflag
+#define yynerrs c_nerrs
+#define yyps c_ps
+#define yypv c_pv
+#define yys c_s
+#define yy_yys c_yys
+#define yystate c_state
+#define yytmp c_tmp
+#define yyv c_v
+#define yy_yyv c_yyv
+#define yyval c_val
+#define yylloc c_lloc
+#define yyreds c_reds
+#define yytoks c_toks
+#define yylhs c_yylhs
+#define yylen c_yylen
+#define yydefred c_yydefred
+#define yydgoto c_yydgoto
+#define yysindex c_yysindex
+#define yyrindex c_yyrindex
+#define yygindex c_yygindex
+#define yytable c_yytable
+#define yycheck c_yycheck
+#define yyname c_yyname
+#define yyrule c_yyrule
+ at end example
+
+For each define, replace the @samp{c_} prefix with whatever you like.
+These defines work for @command{bison}, @command{byacc}, and
+traditional @code{yacc}s. If you find a parser generator that uses a
+symbol not covered here, please report the new name so it can be added
+to the list.
+
+
+ at node C++ Support
+ at section C++ Support
+
+ at cindex C++ support
+ at cindex Support for C++
+
+Automake includes full support for C++.
+
+Any package including C++ code must define the output variable
+ at code{CXX} in @file{configure.ac}; the simplest way to do this is to use
+the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
+Program Checks, autoconf, The Autoconf Manual}).
+
+A few additional variables are defined when a C++ source file is seen:
+
+ at vtable @code
+ at item CXX
+The name of the C++ compiler.
+
+ at item CXXFLAGS
+Any flags to pass to the C++ compiler.
+
+ at item AM_CXXFLAGS
+The maintainer's variant of @code{CXXFLAGS}.
+
+ at item CXXCOMPILE
+The command used to actually compile a C++ source file. The file name
+is appended to form the complete command line.
+
+ at item CXXLINK
+The command used to actually link a C++ program.
+ at end vtable
+
+
+ at node Objective C Support
+ at section Objective C Support
+
+ at cindex Objective C support
+ at cindex Support for Objective C
+
+Automake includes some support for Objective C.
+
+Any package including Objective C code must define the output variable
+ at code{OBJC} in @file{configure.ac}; the simplest way to do this is to use
+the @code{AC_PROG_OBJC} macro (@pxref{Particular Programs, , Particular
+Program Checks, autoconf, The Autoconf Manual}).
+
+A few additional variables are defined when an Objective C source file
+is seen:
+
+ at vtable @code
+ at item OBJC
+The name of the Objective C compiler.
+
+ at item OBJCFLAGS
+Any flags to pass to the Objective C compiler.
+
+ at item AM_OBJCFLAGS
+The maintainer's variant of @code{OBJCFLAGS}.
+
+ at item OBJCCOMPILE
+The command used to actually compile an Objective C source file. The
+file name is appended to form the complete command line.
+
+ at item OBJCLINK
+The command used to actually link an Objective C program.
+ at end vtable
+
+
+ at node Unified Parallel C Support
+ at section Unified Parallel C Support
+
+ at cindex Unified Parallel C support
+ at cindex Support for Unified Parallel C
+
+Automake includes some support for Unified Parallel C.
+
+Any package including Unified Parallel C code must define the output
+variable @code{UPC} in @file{configure.ac}; the simplest way to do
+this is to use the @code{AM_PROG_UPC} macro (@pxref{Public Macros}).
+
+A few additional variables are defined when a Unified Parallel C
+source file is seen:
+
+ at vtable @code
+ at item UPC
+The name of the Unified Parallel C compiler.
+
+ at item UPCFLAGS
+Any flags to pass to the Unified Parallel C compiler.
+
+ at item AM_UPCFLAGS
+The maintainer's variant of @code{UPCFLAGS}.
+
+ at item UPCCOMPILE
+The command used to actually compile a Unified Parallel C source file.
+The file name is appended to form the complete command line.
+
+ at item UPCLINK
+The command used to actually link a Unified Parallel C program.
+ at end vtable
+
+
+ at node Assembly Support
+ at section Assembly Support
+
+Automake includes some support for assembly code. There are two forms
+of assembler files: normal (@file{*.s}) and preprocessed by @code{CPP}
+(@file{*.S} or @file{*.sx}).
+
+ at vindex CCAS
+ at vindex CCASFLAGS
+ at vindex CPPFLAGS
+ at vindex AM_CCASFLAGS
+ at vindex AM_CPPFLAGS
+The variable @code{CCAS} holds the name of the compiler used to build
+assembly code. This compiler must work a bit like a C compiler; in
+particular it must accept @option{-c} and @option{-o}. The values of
+ at code{CCASFLAGS} and @code{AM_CCASFLAGS} (or its per-target
+definition) is passed to the compilation. For preprocessed files,
+ at code{DEFS}, @code{DEFAULT_INCLUDES}, @code{INCLUDES}, @code{CPPFLAGS}
+and @code{AM_CPPFLAGS} are also used.
+
+The autoconf macro @code{AM_PROG_AS} will define @code{CCAS} and
+ at code{CCASFLAGS} for you (unless they are already set, it simply sets
+ at code{CCAS} to the C compiler and @code{CCASFLAGS} to the C compiler
+flags), but you are free to define these variables by other means.
+
+Only the suffixes @file{.s}, @file{.S}, and @file{.sx} are recognized by
+ at command{automake} as being files containing assembly code.
+
+
+ at node Fortran 77 Support
+ at comment node-name, next, previous, up
+ at section Fortran 77 Support
+
+ at cindex Fortran 77 support
+ at cindex Support for Fortran 77
+
+Automake includes full support for Fortran 77.
+
+Any package including Fortran 77 code must define the output variable
+ at code{F77} in @file{configure.ac}; the simplest way to do this is to use
+the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
+Program Checks, autoconf, The Autoconf Manual}).
+
+A few additional variables are defined when a Fortran 77 source file is
+seen:
+
+ at vtable @code
+
+ at item F77
+The name of the Fortran 77 compiler.
+
+ at item FFLAGS
+Any flags to pass to the Fortran 77 compiler.
+
+ at item AM_FFLAGS
+The maintainer's variant of @code{FFLAGS}.
+
+ at item RFLAGS
+Any flags to pass to the Ratfor compiler.
+
+ at item AM_RFLAGS
+The maintainer's variant of @code{RFLAGS}.
+
+ at item F77COMPILE
+The command used to actually compile a Fortran 77 source file. The file
+name is appended to form the complete command line.
+
+ at item FLINK
+The command used to actually link a pure Fortran 77 program or shared
+library.
+
+ at end vtable
+
+Automake can handle preprocessing Fortran 77 and Ratfor source files in
+addition to compiling them at footnote{Much, if not most, of the
+information in the following sections pertaining to preprocessing
+Fortran 77 programs was taken almost verbatim from @ref{Catalogue of
+Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake
+also contains some support for creating programs and shared libraries
+that are a mixture of Fortran 77 and other languages (@pxref{Mixing
+Fortran 77 With C and C++}).
+
+These issues are covered in the following sections.
+
+ at menu
+* Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
+* Compiling Fortran 77 Files:: Compiling Fortran 77 sources
+* Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
+ at end menu
+
+
+ at node Preprocessing Fortran 77
+ at comment node-name, next, previous, up
+ at subsection Preprocessing Fortran 77
+
+ at cindex Preprocessing Fortran 77
+ at cindex Fortran 77, Preprocessing
+ at cindex Ratfor programs
+
+ at file{N.f} is made automatically from @file{N.F} or @file{N.r}. This
+rule runs just the preprocessor to convert a preprocessable Fortran 77
+or Ratfor source file into a strict Fortran 77 source file. The precise
+command used is as follows:
+
+ at table @file
+
+ at item .F
+ at code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
+$(AM_FFLAGS) $(FFLAGS)}
+
+ at item .r
+ at code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
+
+ at end table
+
+
+ at node Compiling Fortran 77 Files
+ at comment node-name, next, previous, up
+ at subsection Compiling Fortran 77 Files
+
+ at file{N.o} is made automatically from @file{N.f}, @file{N.F} or
+ at file{N.r} by running the Fortran 77 compiler. The precise command used
+is as follows:
+
+ at table @file
+
+ at item .f
+ at code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
+
+ at item .F
+ at code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
+$(AM_FFLAGS) $(FFLAGS)}
+
+ at item .r
+ at code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
+
+ at end table
+
+
+ at node Mixing Fortran 77 With C and C++
+ at comment node-name, next, previous, up
+ at subsection Mixing Fortran 77 With C and C++
+
+ at cindex Fortran 77, mixing with C and C++
+ at cindex Mixing Fortran 77 with C and C++
+ at cindex Linking Fortran 77 with C and C++
+ at cindex cfortran
+ at cindex Mixing Fortran 77 with C and/or C++
+
+Automake currently provides @emph{limited} support for creating programs
+and shared libraries that are a mixture of Fortran 77 and C and/or C++.
+However, there are many other issues related to mixing Fortran 77 with
+other languages that are @emph{not} (currently) handled by Automake, but
+that are handled by other packages at footnote{For example,
+ at uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
+addresses all of these inter-language issues, and runs under nearly all
+Fortran 77, C and C++ compilers on nearly all platforms. However,
+ at command{cfortran} is not yet Free Software, but it will be in the next
+major release.}.
+
+Automake can help in two ways:
+
+ at enumerate
+ at item
+Automatic selection of the linker depending on which combinations of
+source code.
+
+ at item
+Automatic selection of the appropriate linker flags (e.g., @option{-L} and
+ at option{-l}) to pass to the automatically selected linker in order to link
+in the appropriate Fortran 77 intrinsic and run-time libraries.
+
+ at cindex @code{FLIBS}, defined
+ at vindex FLIBS
+These extra Fortran 77 linker flags are supplied in the output variable
+ at code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro
+supplied with newer versions of Autoconf (Autoconf version 2.13 and
+later). @xref{Fortran Compiler, , Fortran Compiler Characteristics,
+autoconf, The Autoconf Manual}.
+ at end enumerate
+
+If Automake detects that a program or shared library (as mentioned in
+some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source
+code that is a mixture of Fortran 77 and C and/or C++, then it requires
+that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in
+ at file{configure.ac}, and that either @code{$(FLIBS)}
+appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
+(for shared libraries) variables. It is the responsibility of the
+person writing the @file{Makefile.am} to make sure that @samp{$(FLIBS)}
+appears in the appropriate @code{_LDADD} or
+ at code{_LIBADD} variable.
+
+ at cindex Mixed language example
+ at cindex Example, mixed language
+
+For example, consider the following @file{Makefile.am}:
+
+ at example
+bin_PROGRAMS = foo
+foo_SOURCES = main.cc foo.f
+foo_LDADD = libfoo.la $(FLIBS)
+
+pkglib_LTLIBRARIES = libfoo.la
+libfoo_la_SOURCES = bar.f baz.c zardoz.cc
+libfoo_la_LIBADD = $(FLIBS)
+ at end example
+
+In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
+is mentioned in @file{configure.ac}. Also, if @samp{$(FLIBS)} hadn't
+been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
+Automake would have issued a warning.
+
+ at menu
+* How the Linker is Chosen:: Automatic linker selection
+ at end menu
+
+ at node How the Linker is Chosen
+ at comment node-name, next, previous, up
+ at subsubsection How the Linker is Chosen
+
+ at cindex Automatic linker selection
+ at cindex Selecting the linker automatically
+
+When a program or library mixes several languages, Automake choose the
+linker according to the following priorities. (The names in
+parentheses are the variables containing the link command.)
+
+ at enumerate
+ at item
+ at vindex GCJLINK
+Native Java (@code{GCJLINK})
+ at item
+ at vindex CXXLINK
+C++ (@code{CXXLINK})
+ at item
+ at vindex F77LINK
+Fortran 77 (@code{F77LINK})
+ at item
+ at vindex FCLINK
+Fortran (@code{FCLINK})
+ at item
+ at vindex OBJCLINK
+Objective C (@code{OBJCLINK})
+ at item
+ at vindex UPCLINK
+Unified Parallel C (@code{UPCLINK})
+ at item
+ at vindex LINK
+C (@code{LINK})
+ at end enumerate
+
+For example, if Fortran 77, C and C++ source code is compiled
+into a program, then the C++ linker will be used. In this case, if the
+C or Fortran 77 linkers required any special libraries that weren't
+included by the C++ linker, then they must be manually added to an
+ at code{_LDADD} or @code{_LIBADD} variable by the user writing the
+ at file{Makefile.am}.
+
+Automake only looks at the file names listed in @file{_SOURCES}
+variables to choose the linker, and defaults to the C linker.
+Sometimes this is inconvenient because you are linking against a
+library written in another language and would like to set the linker
+more appropriately. @xref{Libtool Convenience Libraries}, for a
+trick with @code{nodist_EXTRA_ at dots{}_SOURCES}.
+
+A per-target @code{_LINK} variable will override the above selection.
+Per-target link flags will cause Automake to write a per-target
+ at code{_LINK} variable according to the language chosen as above.
+
+
+ at node Fortran 9x Support
+ at comment node-name, next, previous, up
+ at section Fortran 9x Support
+
+ at cindex Fortran 9x support
+ at cindex Support for Fortran 9x
+
+Automake includes support for Fortran 9x.
+
+Any package including Fortran 9x code must define the output variable
+ at code{FC} in @file{configure.ac}; the simplest way to do this is to use
+the @code{AC_PROG_FC} macro (@pxref{Particular Programs, , Particular
+Program Checks, autoconf, The Autoconf Manual}).
+
+A few additional variables are defined when a Fortran 9x source file is
+seen:
+
+ at vtable @code
+
+ at item FC
+The name of the Fortran 9x compiler.
+
+ at item FCFLAGS
+Any flags to pass to the Fortran 9x compiler.
+
+ at item AM_FCFLAGS
+The maintainer's variant of @code{FCFLAGS}.
+
+ at item FCCOMPILE
+The command used to actually compile a Fortran 9x source file. The file
+name is appended to form the complete command line.
+
+ at item FCLINK
+The command used to actually link a pure Fortran 9x program or shared
+library.
+
+ at end vtable
+
+ at menu
+* Compiling Fortran 9x Files:: Compiling Fortran 9x sources
+ at end menu
+
+ at node Compiling Fortran 9x Files
+ at comment node-name, next, previous, up
+ at subsection Compiling Fortran 9x Files
+
+ at file{@var{file}.o} is made automatically from @file{@var{file}.f90},
+ at file{@var{file}.f95}, @file{@var{file}.f03}, or @file{@var{file}.f08}
+by running the Fortran 9x compiler. The precise command used
+is as follows:
+
+ at table @file
+
+ at item .f90
+ at code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f90) $<}
+
+ at item .f95
+ at code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f95) $<}
+
+ at item .f03
+ at code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f03) $<}
+
+ at item .f08
+ at code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f08) $<}
+
+ at end table
+
+ at node Java Support with gcj
+ at comment node-name, next, previous, up
+ at section Compiling Java sources using gcj
+
+ at cindex Java support with gcj
+ at cindex Support for Java with gcj
+ at cindex Java to native code, compilation
+ at cindex Compilation of Java to native code
+
+Automake includes support for natively compiled Java, using @command{gcj},
+the Java front end to the GNU Compiler Collection (rudimentary support
+for compiling Java to bytecode using the @command{javac} compiler is
+also present, @emph{albeit deprecated}; @pxref{Java}).
+
+Any package including Java code to be compiled must define the output
+variable @code{GCJ} in @file{configure.ac}; the variable @code{GCJFLAGS}
+must also be defined somehow (either in @file{configure.ac} or
+ at file{Makefile.am}). The simplest way to do this is to use the
+ at code{AM_PROG_GCJ} macro.
+
+ at vindex GCJFLAGS
+
+By default, programs including Java source files are linked with
+ at command{gcj}.
+
+As always, the contents of @code{AM_GCJFLAGS} are passed to every
+compilation invoking @command{gcj} (in its role as an ahead-of-time
+compiler, when invoking it to create @file{.class} files,
+ at code{AM_JAVACFLAGS} is used instead). If it is necessary to pass
+options to @command{gcj} from @file{Makefile.am}, this variable, and not
+the user variable @code{GCJFLAGS}, should be used.
+
+ at vindex AM_GCJFLAGS
+
+ at command{gcj} can be used to compile @file{.java}, @file{.class},
+ at file{.zip}, or @file{.jar} files.
+
+When linking, @command{gcj} requires that the main class be specified
+using the @option{--main=} option. The easiest way to do this is to use
+the @code{_LDFLAGS} variable for the program.
+
+
+ at node Vala Support
+ at comment node-name, next, previous, up
+ at section Vala Support
+
+ at cindex Vala Support
+ at cindex Support for Vala
+
+Automake provides initial support for Vala
+(@uref{http://www.vala-project.org/}).
+This requires valac version 0.7.0 or later, and currently requires
+the user to use GNU @command{make}.
+
+ at example
+foo_SOURCES = foo.vala bar.vala zardoc.c
+ at end example
+
+Any @file{.vala} file listed in a @code{_SOURCES} variable will be
+compiled into C code by the Vala compiler. The generated @file{.c} files are
+distributed. The end user does not need to have a Vala compiler installed.
+
+Automake ships with an Autoconf macro called @code{AM_PROG_VALAC}
+that will locate the Vala compiler and optionally check its version
+number.
+
+ at defmac AM_PROG_VALAC (@ovar{minimum-version})
+Try to find a Vala compiler in @env{PATH}. If it is found, the variable
+ at code{VALAC} is set. Optionally a minimum release number of the compiler
+can be requested:
+
+ at example
+AM_PROG_VALAC([0.7.0])
+ at end example
+ at end defmac
+
+There are a few variables that are used when compiling Vala sources:
+
+ at vtable @code
+ at item VALAC
+Path to the Vala compiler.
+
+ at item VALAFLAGS
+Additional arguments for the Vala compiler.
+
+ at item AM_VALAFLAGS
+The maintainer's variant of @code{VALAFLAGS}.
+
+ at example
+lib_LTLIBRARIES = libfoo.la
+libfoo_la_SOURCES = foo.vala
+ at end example
+ at end vtable
+
+Note that currently, you cannot use per-target @code{*_VALAFLAGS}
+(@pxref{Renamed Objects}) to produce different C files from one Vala
+source file.
+
+
+ at node Support for Other Languages
+ at comment node-name, next, previous, up
+ at section Support for Other Languages
+
+Automake currently only includes full support for C, C++ (@pxref{C++
+Support}), Objective C (@pxref{Objective C Support}), Fortran 77
+(@pxref{Fortran 77 Support}), Fortran 9x (@pxref{Fortran 9x Support}),
+and Java (@pxref{Java Support with gcj}). There is only rudimentary
+support for other languages, support for which will be improved based
+on user demand.
+
+Some limited support for adding your own languages is available via the
+suffix rule handling (@pxref{Suffixes}).
+
+
+ at node ANSI
+ at section Automatic de-ANSI-fication (deprecated, soon to be removed)
+
+ at cindex de-ANSI-fication, defined
+
+ at emph{The features described in this section are deprecated; you must
+not use any of them in new code, and remove their use from older but
+still maintained code: they will be withdrawn in the next major
+Automake release.}
+
+When the C language was standardized in 1989, there was a long
+transition period where package developers needed to worry about
+porting to older systems that did not support ANSI C by default.
+These older systems are no longer in practical use and are no longer
+supported by their original suppliers, so developers need not worry
+about this problem any more.
+
+Automake allows you to write packages that are portable to K&R C by
+ at dfn{de-ANSI-fying} each source file before the actual compilation takes
+place.
+
+ at vindex AUTOMAKE_OPTIONS
+ at opindex ansi2knr
+
+If the @file{Makefile.am} variable @code{AUTOMAKE_OPTIONS}
+(@pxref{Options}) contains the option @option{ansi2knr} then code to
+handle de-ANSI-fication is inserted into the generated
+ at file{Makefile.in}.
+
+This causes each C source file in the directory to be treated as ANSI C at .
+If an ANSI C compiler is available, it is used. If no ANSI C compiler
+is available, the @command{ansi2knr} program is used to convert the source
+files into K&R C, which is then compiled.
+
+The @command{ansi2knr} program is simple-minded. It assumes the source
+code will be formatted in a particular way; see the @command{ansi2knr} man
+page for details.
+
+ at acindex AM_C_PROTOTYPES
+Support for the obsolete de-ANSI-fication feature
+requires the source files @file{ansi2knr.c}
+and @file{ansi2knr.1} to be in the same package as the ANSI C source;
+these files are distributed with Automake. Also, the package
+ at file{configure.ac} must call the macro @code{AM_C_PROTOTYPES}
+(@pxref{Macros}).
+
+Automake also handles finding the @command{ansi2knr} support files in some
+other directory in the current package. This is done by prepending the
+relative path to the appropriate directory to the @command{ansi2knr}
+option. For instance, suppose the package has ANSI C code in the
+ at file{src} and @file{lib} subdirectories. The files @file{ansi2knr.c} and
+ at file{ansi2knr.1} appear in @file{lib}. Then this could appear in
+ at file{src/Makefile.am}:
+
+ at example
+AUTOMAKE_OPTIONS = ../lib/ansi2knr
+ at end example
+
+If no directory prefix is given, the files are assumed to be in the
+current directory.
+
+Note that automatic de-ANSI-fication will not work when the package is
+being built for a different host architecture. That is because
+ at command{automake} currently has no way to build @command{ansi2knr}
+for the build machine.
+
+ at c FIXME: this paragraph might be better moved to an `upgrading' section.
+ at cindex @code{LTLIBOBJS} and @code{ansi2knr}
+ at cindex @code{LIBOBJS} and @code{ansi2knr}
+ at cindex @code{ansi2knr} and @code{LTLIBOBJS}
+ at cindex @code{ansi2knr} and @code{LIBOBJS}
+Using @code{LIBOBJS} with source de-ANSI-fication used to require
+hand-crafted code in @file{configure} to append @samp{$U} to basenames
+in @code{LIBOBJS}. This is no longer true today. Starting with version
+2.54, Autoconf takes care of rewriting @code{LIBOBJS} and
+ at code{LTLIBOBJS}. (@pxref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ}
+vs.@: @code{LIBOBJS}, autoconf, The Autoconf Manual})
+
+ at node Dependencies
+ at section Automatic dependency tracking
+
+As a developer it is often painful to continually update the
+ at file{Makefile.am} whenever the include-file dependencies change in a
+project. Automake supplies a way to automatically track dependency
+changes (@pxref{Dependency Tracking}).
+
+ at cindex Dependency tracking
+ at cindex Automatic dependency tracking
+
+Automake always uses complete dependencies for a compilation,
+including system headers. Automake's model is that dependency
+computation should be a side effect of the build. To this end,
+dependencies are computed by running all compilations through a
+special wrapper program called @command{depcomp}. @command{depcomp}
+understands how to coax many different C and C++ compilers into
+generating dependency information in the format it requires.
+ at samp{automake -a} will install @command{depcomp} into your source
+tree for you. If @command{depcomp} can't figure out how to properly
+invoke your compiler, dependency tracking will simply be disabled for
+your build.
+
+ at cindex @command{depcomp}
+
+Experience with earlier versions of Automake (@pxref{Dependency
+Tracking Evolution}) taught us that it is not reliable to generate
+dependencies only on the maintainer's system, as configurations vary
+too much. So instead Automake implements dependency tracking at build
+time.
+
+Automatic dependency tracking can be suppressed by putting
+ at option{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}, or
+passing @option{no-dependencies} as an argument to @code{AM_INIT_AUTOMAKE}
+(this should be the preferred way). Or, you can invoke @command{automake}
+with the @option{-i} option. Dependency tracking is enabled by default.
+
+ at vindex AUTOMAKE_OPTIONS
+ at opindex no-dependencies
+
+The person building your package also can choose to disable dependency
+tracking by configuring with @option{--disable-dependency-tracking}.
+
+ at cindex Disabling dependency tracking
+ at cindex Dependency tracking, disabling
+
+
+ at node EXEEXT
+ at section Support for executable extensions
+
+ at cindex Executable extension
+ at cindex Extension, executable
+ at cindex Windows
+
+On some platforms, such as Windows, executables are expected to have an
+extension such as @file{.exe}. On these platforms, some compilers (GCC
+among them) will automatically generate @file{foo.exe} when asked to
+generate @file{foo}.
+
+Automake provides mostly-transparent support for this. Unfortunately
+ at emph{mostly} doesn't yet mean @emph{fully}. Until the English
+dictionary is revised, you will have to assist Automake if your package
+must support those platforms.
+
+One thing you must be aware of is that, internally, Automake rewrites
+something like this:
+
+ at example
+bin_PROGRAMS = liver
+ at end example
+
+to this:
+
+ at example
+bin_PROGRAMS = liver$(EXEEXT)
+ at end example
+
+The targets Automake generates are likewise given the @samp{$(EXEEXT)}
+extension.
+
+The variables @code{TESTS} and @code{XFAIL_TESTS} (@pxref{Simple Tests})
+are also rewritten if they contain filenames that have been declared as
+programs in the same @file{Makefile}. (This is mostly useful when some
+programs from @code{check_PROGRAMS} are listed in @code{TESTS}.)
+
+However, Automake cannot apply this rewriting to @command{configure}
+substitutions. This means that if you are conditionally building a
+program using such a substitution, then your @file{configure.ac} must
+take care to add @samp{$(EXEEXT)} when constructing the output variable.
+
+With Autoconf 2.13 and earlier, you must explicitly use @code{AC_EXEEXT}
+to get this support. With Autoconf 2.50, @code{AC_EXEEXT} is run
+automatically if you configure a compiler (say, through
+ at code{AC_PROG_CC}).
+
+Sometimes maintainers like to write an explicit link rule for their
+program. Without executable extension support, this is easy---you
+simply write a rule whose target is the name of the program. However,
+when executable extension support is enabled, you must instead add the
+ at samp{$(EXEEXT)} suffix.
+
+Unfortunately, due to the change in Autoconf 2.50, this means you must
+always add this extension. However, this is a problem for maintainers
+who know their package will never run on a platform that has
+executable extensions. For those maintainers, the @option{no-exeext}
+option (@pxref{Options}) will disable this feature. This works in a
+fairly ugly way; if @option{no-exeext} is seen, then the presence of a
+rule for a target named @code{foo} in @file{Makefile.am} will override
+an @command{automake}-generated rule for @samp{foo$(EXEEXT)}. Without
+the @option{no-exeext} option, this use will give a diagnostic.
+
+
+ at node Other Objects
+ at chapter Other Derived Objects
+
+Automake can handle derived objects that are not C programs. Sometimes
+the support for actually building such objects must be explicitly
+supplied, but Automake will still automatically handle installation and
+distribution.
+
+ at menu
+* Scripts:: Executable scripts
+* Headers:: Header files
+* Data:: Architecture-independent data files
+* Sources:: Derived sources
+ at end menu
+
+
+ at node Scripts
+ at section Executable Scripts
+
+ at cindex @code{_SCRIPTS} primary, defined
+ at cindex @code{SCRIPTS} primary, defined
+ at cindex Primary variable, @code{SCRIPTS}
+ at vindex _SCRIPTS
+ at cindex Installing scripts
+
+It is possible to define and install programs that are scripts. Such
+programs are listed using the @code{SCRIPTS} primary name. When the
+script is distributed in its final, installable form, the
+ at file{Makefile} usually looks as follows:
+ at vindex SCRIPTS
+
+ at example
+# Install my_script in $(bindir) and distribute it.
+dist_bin_SCRIPTS = my_script
+ at end example
+
+Scripts are not distributed by default; as we have just seen, those
+that should be distributed can be specified using a @code{dist_}
+prefix as with other primaries.
+
+ at cindex @code{SCRIPTS}, installation directories
+ at vindex bin_SCRIPTS
+ at vindex sbin_SCRIPTS
+ at vindex libexec_SCRIPTS
+ at vindex pkgdata_SCRIPTS
+ at vindex pkglibexec_SCRIPTS
+ at vindex noinst_SCRIPTS
+ at vindex check_SCRIPTS
+
+Scripts can be installed in @code{bindir}, @code{sbindir},
+ at code{libexecdir}, @code{pkglibexecdir}, or @code{pkgdatadir}.
+
+Scripts that need not be installed can be listed in
+ at code{noinst_SCRIPTS}, and among them, those which are needed only by
+ at samp{make check} should go in @code{check_SCRIPTS}.
+
+When a script needs to be built, the @file{Makefile.am} should include
+the appropriate rules. For instance the @command{automake} program
+itself is a Perl script that is generated from @file{automake.in}.
+Here is how this is handled:
+
+ at example
+bin_SCRIPTS = automake
+CLEANFILES = $(bin_SCRIPTS)
+EXTRA_DIST = automake.in
+
+do_subst = sed -e 's,[@@]datadir[@@],$(datadir),g' \
+ -e 's,[@@]PERL[@@],$(PERL),g' \
+ -e 's,[@@]PACKAGE[@@],$(PACKAGE),g' \
+ -e 's,[@@]VERSION[@@],$(VERSION),g' \
+ @dots{}
+
+automake: automake.in Makefile
+ $(do_subst) < $(srcdir)/automake.in > automake
+ chmod +x automake
+ at end example
+
+Such scripts for which a build rule has been supplied need to be
+deleted explicitly using @code{CLEANFILES} (@pxref{Clean}), and their
+sources have to be distributed, usually with @code{EXTRA_DIST}
+(@pxref{Basics of Distribution}).
+
+Another common way to build scripts is to process them from
+ at file{configure} with @code{AC_CONFIG_FILES}. In this situation
+Automake knows which files should be cleaned and distributed, and what
+the rebuild rules should look like.
+
+For instance if @file{configure.ac} contains
+
+ at example
+AC_CONFIG_FILES([src/my_script], [chmod +x src/my_script])
+ at end example
+
+ at noindent
+to build @file{src/my_script} from @file{src/my_script.in}, then a
+ at file{src/Makefile.am} to install this script in @code{$(bindir)} can
+be as simple as
+
+ at example
+bin_SCRIPTS = my_script
+CLEANFILES = $(bin_SCRIPTS)
+ at end example
+
+ at noindent
+There is no need for @code{EXTRA_DIST} or any build rule: Automake
+infers them from @code{AC_CONFIG_FILES} (@pxref{Requirements}).
+ at code{CLEANFILES} is still useful, because by default Automake will
+clean targets of @code{AC_CONFIG_FILES} in @code{distclean}, not
+ at code{clean}.
+
+Although this looks simpler, building scripts this way has one
+drawback: directory variables such as @code{$(datadir)} are not fully
+expanded and may refer to other directory variables.
+
+ at node Headers
+ at section Header files
+
+ at cindex @code{_HEADERS} primary, defined
+ at cindex @code{HEADERS} primary, defined
+ at cindex Primary variable, @code{HEADERS}
+ at vindex _HEADERS
+ at vindex noinst_HEADERS
+ at cindex @code{HEADERS}, installation directories
+ at cindex Installing headers
+ at vindex include_HEADERS
+ at vindex oldinclude_HEADERS
+ at vindex pkginclude_HEADERS
+
+
+Header files that must be installed are specified by the
+ at code{HEADERS} family of variables. Headers can be installed in
+ at code{includedir}, @code{oldincludedir}, @code{pkgincludedir} or any
+other directory you may have defined (@pxref{Uniform}). For instance,
+
+ at example
+include_HEADERS = foo.h bar/bar.h
+ at end example
+
+ at noindent
+will install the two files as @file{$(includedir)/foo.h} and
+ at file{$(includedir)/bar.h}.
+
+The @code{nobase_} prefix is also supported,
+
+ at example
+nobase_include_HEADERS = foo.h bar/bar.h
+ at end example
+
+ at noindent
+will install the two files as @file{$(includedir)/foo.h} and
+ at file{$(includedir)/bar/bar.h} (@pxref{Alternative}).
+
+ at vindex noinst_HEADERS
+Usually, only header files that accompany installed libraries need to
+be installed. Headers used by programs or convenience libraries are
+not installed. The @code{noinst_HEADERS} variable can be used for
+such headers. However when the header actually belongs to a single
+convenience library or program, we recommend listing it in the
+program's or library's @code{_SOURCES} variable (@pxref{Program
+Sources}) instead of in @code{noinst_HEADERS}. This is clearer for
+the @file{Makefile.am} reader. @code{noinst_HEADERS} would be the
+right variable to use in a directory containing only headers and no
+associated library or program.
+
+All header files must be listed somewhere; in a @code{_SOURCES}
+variable or in a @code{_HEADERS} variable. Missing ones will not
+appear in the distribution.
+
+For header files that are built and must not be distributed, use the
+ at code{nodist_} prefix as in @code{nodist_include_HEADERS} or
+ at code{nodist_prog_SOURCES}. If these generated headers are needed
+during the build, you must also ensure they exist before they are
+used (@pxref{Sources}).
+
+
+ at node Data
+ at section Architecture-independent data files
+
+ at cindex @code{_DATA} primary, defined
+ at cindex @code{DATA} primary, defined
+ at cindex Primary variable, @code{DATA}
+ at vindex _DATA
+
+Automake supports the installation of miscellaneous data files using the
+ at code{DATA} family of variables.
+ at vindex DATA
+
+ at vindex data_DATA
+ at vindex sysconf_DATA
+ at vindex sharedstate_DATA
+ at vindex localstate_DATA
+ at vindex pkgdata_DATA
+
+Such data can be installed in the directories @code{datadir},
+ at code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
+ at code{pkgdatadir}.
+
+By default, data files are @emph{not} included in a distribution. Of
+course, you can use the @code{dist_} prefix to change this on a
+per-variable basis.
+
+Here is how Automake declares its auxiliary data files:
+
+ at example
+dist_pkgdata_DATA = clean-kr.am clean.am @dots{}
+ at end example
+
+
+ at node Sources
+ at section Built Sources
+
+Because Automake's automatic dependency tracking works as a side-effect
+of compilation (@pxref{Dependencies}) there is a bootstrap issue: a
+target should not be compiled before its dependencies are made, but
+these dependencies are unknown until the target is first compiled.
+
+Ordinarily this is not a problem, because dependencies are distributed
+sources: they preexist and do not need to be built. Suppose that
+ at file{foo.c} includes @file{foo.h}. When it first compiles
+ at file{foo.o}, @command{make} only knows that @file{foo.o} depends on
+ at file{foo.c}. As a side-effect of this compilation @command{depcomp}
+records the @file{foo.h} dependency so that following invocations of
+ at command{make} will honor it. In these conditions, it's clear there is
+no problem: either @file{foo.o} doesn't exist and has to be built
+(regardless of the dependencies), or accurate dependencies exist and
+they can be used to decide whether @file{foo.o} should be rebuilt.
+
+It's a different story if @file{foo.h} doesn't exist by the first
+ at command{make} run. For instance, there might be a rule to build
+ at file{foo.h}. This time @file{file.o}'s build will fail because the
+compiler can't find @file{foo.h}. @command{make} failed to trigger the
+rule to build @file{foo.h} first by lack of dependency information.
+
+ at vindex BUILT_SOURCES
+ at cindex @code{BUILT_SOURCES}, defined
+
+The @code{BUILT_SOURCES} variable is a workaround for this problem. A
+source file listed in @code{BUILT_SOURCES} is made on @samp{make all}
+or @samp{make check} (or even @samp{make install}) before other
+targets are processed. However, such a source file is not
+ at emph{compiled} unless explicitly requested by mentioning it in some
+other @code{_SOURCES} variable.
+
+So, to conclude our introductory example, we could use
+ at samp{BUILT_SOURCES = foo.h} to ensure @file{foo.h} gets built before
+any other target (including @file{foo.o}) during @samp{make all} or
+ at samp{make check}.
+
+ at code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
+must be created early in the build process can be listed in this
+variable. Moreover, all built sources do not necessarily have to be
+listed in @code{BUILT_SOURCES}. For instance, a generated @file{.c} file
+doesn't need to appear in @code{BUILT_SOURCES} (unless it is included by
+another source), because it's a known dependency of the associated
+object.
+
+It might be important to emphasize that @code{BUILT_SOURCES} is
+honored only by @samp{make all}, @samp{make check} and @samp{make
+install}. This means you cannot build a specific target (e.g.,
+ at samp{make foo}) in a clean tree if it depends on a built source.
+However it will succeed if you have run @samp{make all} earlier,
+because accurate dependencies are already available.
+
+The next section illustrates and discusses the handling of built sources
+on a toy example.
+
+ at menu
+* Built Sources Example:: Several ways to handle built sources.
+ at end menu
+
+ at node Built Sources Example
+ at subsection Built Sources Example
+
+Suppose that @file{foo.c} includes @file{bindir.h}, which is
+installation-dependent and not distributed: it needs to be built. Here
+ at file{bindir.h} defines the preprocessor macro @code{bindir} to the
+value of the @command{make} variable @code{bindir} (inherited from
+ at file{configure}).
+
+We suggest several implementations below. It's not meant to be an
+exhaustive listing of all ways to handle built sources, but it will give
+you a few ideas if you encounter this issue.
+
+ at subsubheading First Try
+
+This first implementation will illustrate the bootstrap issue mentioned
+in the previous section (@pxref{Sources}).
+
+Here is a tentative @file{Makefile.am}.
+
+ at example
+# This won't work.
+bin_PROGRAMS = foo
+foo_SOURCES = foo.c
+nodist_foo_SOURCES = bindir.h
+CLEANFILES = bindir.h
+bindir.h: Makefile
+ echo '#define bindir "$(bindir)"' >$@@
+ at end example
+
+This setup doesn't work, because Automake doesn't know that @file{foo.c}
+includes @file{bindir.h}. Remember, automatic dependency tracking works
+as a side-effect of compilation, so the dependencies of @file{foo.o} will
+be known only after @file{foo.o} has been compiled (@pxref{Dependencies}).
+The symptom is as follows.
+
+ at example
+% make
+source='foo.c' object='foo.o' libtool=no \
+depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
+depmode=gcc /bin/sh ./depcomp \
+gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
+foo.c:2: bindir.h: No such file or directory
+make: *** [foo.o] Error 1
+ at end example
+
+In this example @file{bindir.h} is not distributed nor installed, and
+it is not even being built on-time. One may wonder if the
+ at samp{nodist_foo_SOURCES = bindir.h} line has any use at all. This
+line simply states that @file{bindir.h} is a source of @code{foo}, so
+for instance, it should be inspected while generating tags
+(@pxref{Tags}). In other words, it does not help our present problem,
+and the build would fail identically without it.
+
+ at subsubheading Using @code{BUILT_SOURCES}
+
+A solution is to require @file{bindir.h} to be built before anything
+else. This is what @code{BUILT_SOURCES} is meant for (@pxref{Sources}).
+
+ at example
+bin_PROGRAMS = foo
+foo_SOURCES = foo.c
+nodist_foo_SOURCES = bindir.h
+BUILT_SOURCES = bindir.h
+CLEANFILES = bindir.h
+bindir.h: Makefile
+ echo '#define bindir "$(bindir)"' >$@@
+ at end example
+
+See how @file{bindir.h} gets built first:
+
+ at example
+% make
+echo '#define bindir "/usr/local/bin"' >bindir.h
+make all-am
+make[1]: Entering directory `/home/adl/tmp'
+source='foo.c' object='foo.o' libtool=no \
+depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
+depmode=gcc /bin/sh ./depcomp \
+gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
+gcc -g -O2 -o foo foo.o
+make[1]: Leaving directory `/home/adl/tmp'
+ at end example
+
+However, as said earlier, @code{BUILT_SOURCES} applies only to the
+ at code{all}, @code{check}, and @code{install} targets. It still fails
+if you try to run @samp{make foo} explicitly:
+
+ at example
+% make clean
+test -z "bindir.h" || rm -f bindir.h
+test -z "foo" || rm -f foo
+rm -f *.o
+% : > .deps/foo.Po # Suppress previously recorded dependencies
+% make foo
+source='foo.c' object='foo.o' libtool=no \
+depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
+depmode=gcc /bin/sh ./depcomp \
+gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
+foo.c:2: bindir.h: No such file or directory
+make: *** [foo.o] Error 1
+ at end example
+
+ at subsubheading Recording Dependencies manually
+
+Usually people are happy enough with @code{BUILT_SOURCES} because they
+never build targets such as @samp{make foo} before @samp{make all}, as
+in the previous example. However if this matters to you, you can
+avoid @code{BUILT_SOURCES} and record such dependencies explicitly in
+the @file{Makefile.am}.
+
+ at example
+bin_PROGRAMS = foo
+foo_SOURCES = foo.c
+nodist_foo_SOURCES = bindir.h
+foo.$(OBJEXT): bindir.h
+CLEANFILES = bindir.h
+bindir.h: Makefile
+ echo '#define bindir "$(bindir)"' >$@@
+ at end example
+
+You don't have to list @emph{all} the dependencies of @file{foo.o}
+explicitly, only those that might need to be built. If a dependency
+already exists, it will not hinder the first compilation and will be
+recorded by the normal dependency tracking code. (Note that after
+this first compilation the dependency tracking code will also have
+recorded the dependency between @file{foo.o} and
+ at file{bindir.h}; so our explicit dependency is really useful to
+the first build only.)
+
+Adding explicit dependencies like this can be a bit dangerous if you are
+not careful enough. This is due to the way Automake tries not to
+overwrite your rules (it assumes you know better than it).
+ at samp{foo.$(OBJEXT): bindir.h} supersedes any rule Automake may want to
+output to build @samp{foo.$(OBJEXT)}. It happens to work in this case
+because Automake doesn't have to output any @samp{foo.$(OBJEXT):}
+target: it relies on a suffix rule instead (i.e., @samp{.c.$(OBJEXT):}).
+Always check the generated @file{Makefile.in} if you do this.
+
+ at subsubheading Build @file{bindir.h} from @file{configure}
+
+It's possible to define this preprocessor macro from @file{configure},
+either in @file{config.h} (@pxref{Defining Directories, , Defining
+Directories, autoconf, The Autoconf Manual}), or by processing a
+ at file{bindir.h.in} file using @code{AC_CONFIG_FILES}
+(@pxref{Configuration Actions, ,Configuration Actions, autoconf, The
+Autoconf Manual}).
+
+At this point it should be clear that building @file{bindir.h} from
+ at file{configure} works well for this example. @file{bindir.h} will exist
+before you build any target, hence will not cause any dependency issue.
+
+The Makefile can be shrunk as follows. We do not even have to mention
+ at file{bindir.h}.
+
+ at example
+bin_PROGRAMS = foo
+foo_SOURCES = foo.c
+ at end example
+
+However, it's not always possible to build sources from
+ at file{configure}, especially when these sources are generated by a tool
+that needs to be built first.
+
+ at subsubheading Build @file{bindir.c}, not @file{bindir.h}.
+
+Another attractive idea is to define @code{bindir} as a variable or
+function exported from @file{bindir.o}, and build @file{bindir.c}
+instead of @file{bindir.h}.
+
+ at example
+noinst_PROGRAMS = foo
+foo_SOURCES = foo.c bindir.h
+nodist_foo_SOURCES = bindir.c
+CLEANFILES = bindir.c
+bindir.c: Makefile
+ echo 'const char bindir[] = "$(bindir)";' >$@@
+ at end example
+
+ at file{bindir.h} contains just the variable's declaration and doesn't
+need to be built, so it won't cause any trouble. @file{bindir.o} is
+always dependent on @file{bindir.c}, so @file{bindir.c} will get built
+first.
+
+ at subsubheading Which is best?
+
+There is no panacea, of course. Each solution has its merits and
+drawbacks.
+
+You cannot use @code{BUILT_SOURCES} if the ability to run @samp{make
+foo} on a clean tree is important to you.
+
+You won't add explicit dependencies if you are leery of overriding
+an Automake rule by mistake.
+
+Building files from @file{./configure} is not always possible, neither
+is converting @file{.h} files into @file{.c} files.
+
+
+ at node Other GNU Tools
+ at chapter Other GNU Tools
+
+Since Automake is primarily intended to generate @file{Makefile.in}s for
+use in GNU programs, it tries hard to interoperate with other GNU tools.
+
+ at menu
+* Emacs Lisp:: Emacs Lisp
+* gettext:: Gettext
+* Libtool:: Libtool
+* Java:: Java bytecode compilation (deprecated)
+* Python:: Python
+ at end menu
+
+
+ at node Emacs Lisp
+ at section Emacs Lisp
+
+ at cindex @code{_LISP} primary, defined
+ at cindex @code{LISP} primary, defined
+ at cindex Primary variable, @code{LISP}
+
+ at vindex _LISP
+ at vindex lisp_LISP
+ at vindex noinst_LISP
+
+Automake provides some support for Emacs Lisp. The @code{LISP} primary
+is used to hold a list of @file{.el} files. Possible prefixes for this
+primary are @code{lisp_} and @code{noinst_}. Note that if
+ at code{lisp_LISP} is defined, then @file{configure.ac} must run
+ at code{AM_PATH_LISPDIR} (@pxref{Macros}).
+
+ at vindex dist_lisp_LISP
+ at vindex dist_noinst_LISP
+Lisp sources are not distributed by default. You can prefix the
+ at code{LISP} primary with @code{dist_}, as in @code{dist_lisp_LISP} or
+ at code{dist_noinst_LISP}, to indicate that these files should be
+distributed.
+
+Automake will byte-compile all Emacs Lisp source files using the Emacs
+found by @code{AM_PATH_LISPDIR}, if any was found.
+
+Byte-compiled Emacs Lisp files are not portable among all versions of
+Emacs, so it makes sense to turn this off if you expect sites to have
+more than one version of Emacs installed. Furthermore, many packages
+don't actually benefit from byte-compilation. Still, we recommend
+that you byte-compile your Emacs Lisp sources. It is probably better
+for sites with strange setups to cope for themselves than to make the
+installation less nice for everybody else.
+
+There are two ways to avoid byte-compiling. Historically, we have
+recommended the following construct.
+
+ at example
+lisp_LISP = file1.el file2.el
+ELCFILES =
+ at end example
+
+ at noindent
+ at code{ELCFILES} is an internal Automake variable that normally lists
+all @file{.elc} files that must be byte-compiled. Automake defines
+ at code{ELCFILES} automatically from @code{lisp_LISP}. Emptying this
+variable explicitly prevents byte-compilation.
+
+Since Automake 1.8, we now recommend using @code{lisp_DATA} instead:
+
+ at c Keep in sync with primary-prefix-couples-documented-valid.test.
+ at example
+lisp_DATA = file1.el file2.el
+ at end example
+
+Note that these two constructs are not equivalent. @code{_LISP} will
+not install a file if Emacs is not installed, while @code{_DATA} will
+always install its files.
+
+ at node gettext
+ at section Gettext
+
+ at cindex GNU Gettext support
+ at cindex Gettext support
+ at cindex Support for GNU Gettext
+
+If @code{AM_GNU_GETTEXT} is seen in @file{configure.ac}, then Automake
+turns on support for GNU gettext, a message catalog system for
+internationalization
+(@pxref{Top, , Introduction, gettext, GNU gettext utilities}).
+
+The @code{gettext} support in Automake requires the addition of one or
+two subdirectories to the package: @file{po} and possibly also @file{intl}.
+The latter is needed if @code{AM_GNU_GETTEXT} is not invoked with the
+ at samp{external} argument, or if @code{AM_GNU_GETTEXT_INTL_SUBDIR} is used.
+Automake ensures that these directories exist and are mentioned in
+ at code{SUBDIRS}.
+
+ at node Libtool
+ at section Libtool
+
+Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
+libtool, The Libtool Manual}) with the @code{LTLIBRARIES} primary.
+ at xref{A Shared Library}.
+
+
+ at node Java
+ at section Java bytecode compilation (deprecated)
+
+ at cindex @code{_JAVA} primary, defined
+ at cindex @code{JAVA} primary, defined
+ at cindex Primary variable, @code{JAVA}
+ at cindex Java to bytecode, compilation
+ at cindex Compilation of Java to bytecode
+
+Automake provides some minimal support for Java bytecode compilation with
+the @code{JAVA} primary (in addition to the support for compiling Java to
+native machine code; @pxref{Java Support with gcj}). Note however that
+ at emph{the interface and most features described here are deprecated}; the
+next automake release will strive to provide a better and cleaner
+interface, which however @emph{won't be backward-compatible}; the present
+interface will probably be removed altogether in future automake releases
+(1.13 or later), so don't use it in new code.
+
+Any @file{.java} files listed in a @code{_JAVA} variable will be
+compiled with @code{JAVAC} at build time. By default, @file{.java}
+files are not included in the distribution, you should use the
+ at code{dist_} prefix to distribute them.
+
+Here is a typical setup for distributing @file{.java} files and
+installing the @file{.class} files resulting from their compilation.
+
+ at c Keep in sync with primary-prefix-couples-documented-valid.test.
+ at example
+javadir = $(datadir)/java
+dist_java_JAVA = a.java b.java @dots{}
+ at end example
+
+ at cindex @code{JAVA} restrictions
+ at cindex Restrictions for @code{JAVA}
+
+Currently Automake enforces the restriction that only one @code{_JAVA}
+primary can be used in a given @file{Makefile.am}. The reason for this
+restriction is that, in general, it isn't possible to know which
+ at file{.class} files were generated from which @file{.java} files, so
+it would be impossible to know which files to install where. For
+instance, a @file{.java} file can define multiple classes; the resulting
+ at file{.class} file names cannot be predicted without parsing the
+ at file{.java} file.
+
+There are a few variables that are used when compiling Java sources:
+
+ at vtable @code
+ at item JAVAC
+The name of the Java compiler. This defaults to @samp{javac}.
+
+ at item JAVACFLAGS
+The flags to pass to the compiler. This is considered to be a user
+variable (@pxref{User Variables}).
+
+ at item AM_JAVACFLAGS
+More flags to pass to the Java compiler. This, and not
+ at code{JAVACFLAGS}, should be used when it is necessary to put Java
+compiler flags into @file{Makefile.am}.
+
+ at item JAVAROOT
+The value of this variable is passed to the @option{-d} option to
+ at code{javac}. It defaults to @samp{$(top_builddir)}.
+
+ at item CLASSPATH_ENV
+This variable is a shell expression that is used to set the
+ at env{CLASSPATH} environment variable on the @code{javac} command line.
+(In the future we will probably handle class path setting differently.)
+ at end vtable
+
+
+ at node Python
+ at section Python
+
+ at cindex @code{_PYTHON} primary, defined
+ at cindex @code{PYTHON} primary, defined
+ at cindex Primary variable, @code{PYTHON}
+ at vindex _PYTHON
+
+Automake provides support for Python compilation with the
+ at code{PYTHON} primary. A typical setup is to call
+ at code{AM_PATH_PYTHON} in @file{configure.ac} and use a line like the
+following in @file{Makefile.am}:
+
+ at example
+python_PYTHON = tree.py leave.py
+ at end example
+
+Any files listed in a @code{_PYTHON} variable will be byte-compiled
+with @command{py-compile} at install time. @command{py-compile}
+actually creates both standard (@file{.pyc}) and optimized
+(@file{.pyo}) byte-compiled versions of the source files. Note that
+because byte-compilation occurs at install time, any files listed in
+ at code{noinst_PYTHON} will not be compiled. Python source files are
+included in the distribution by default, prepend @code{nodist_} (as in
+ at code{nodist_python_PYTHON}) to omit them.
+
+Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON}
+that will determine some Python-related directory variables (see
+below). If you have called @code{AM_PATH_PYTHON} from
+ at file{configure.ac}, then you may use the variables
+ at c Keep in sync with primary-prefix-couples-documented-valid.test.
+ at code{python_PYTHON} or @code{pkgpython_PYTHON} to list Python source
+files in your @file{Makefile.am}, depending on where you want your files
+installed (see the definitions of @code{pythondir} and
+ at code{pkgpythondir} below).
+
+ at defmac AM_PATH_PYTHON (@ovar{version}, @ovar{action-if-found},
+ @ovar{action-if-not-found})
+
+Search for a Python interpreter on the system. This macro takes three
+optional arguments. The first argument, if present, is the minimum
+version of Python required for this package: @code{AM_PATH_PYTHON}
+will skip any Python interpreter that is older than @var{version}.
+If an interpreter is found and satisfies @var{version}, then
+ at var{action-if-found} is run. Otherwise, @var{action-if-not-found} is
+run.
+
+If @var{action-if-not-found} is not specified, as in the following
+example, the default is to abort @command{configure}.
+
+ at example
+AM_PATH_PYTHON([2.2])
+ at end example
+
+ at noindent
+This is fine when Python is an absolute requirement for the package.
+If Python >= 2.5 was only @emph{optional} to the package,
+ at code{AM_PATH_PYTHON} could be called as follows.
+
+ at example
+AM_PATH_PYTHON([2.5],, [:])
+ at end example
+
+If the @env{PYTHON} variable is set when @code{AM_PATH_PYTHON} is
+called, then that will be the only Python interpreter that is tried.
+
+ at code{AM_PATH_PYTHON} creates the following output variables based on
+the Python installation found during configuration.
+ at end defmac
+
+ at vtable @code
+ at item PYTHON
+The name of the Python executable, or @samp{:} if no suitable
+interpreter could be found.
+
+Assuming @var{action-if-not-found} is used (otherwise @file{./configure}
+will abort if Python is absent), the value of @code{PYTHON} can be used
+to setup a conditional in order to disable the relevant part of a build
+as follows.
+
+ at example
+AM_PATH_PYTHON(,, [:])
+AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :])
+ at end example
+
+ at item PYTHON_VERSION
+The Python version number, in the form @var{major}. at var{minor}
+(e.g., @samp{2.5}). This is currently the value of
+ at samp{sys.version[:3]}.
+
+ at item PYTHON_PREFIX
+The string @samp{$@{prefix@}}. This term may be used in future work
+that needs the contents of Python's @samp{sys.prefix}, but general
+consensus is to always use the value from @command{configure}.
+
+ at item PYTHON_EXEC_PREFIX
+The string @samp{$@{exec_prefix@}}. This term may be used in future work
+that needs the contents of Python's @samp{sys.exec_prefix}, but general
+consensus is to always use the value from @command{configure}.
+
+ at item PYTHON_PLATFORM
+The canonical name used by Python to describe the operating system, as
+given by @samp{sys.platform}. This value is sometimes needed when
+building Python extensions.
+
+ at item pythondir
+The directory name for the @file{site-packages} subdirectory of the
+standard Python install tree.
+
+ at item pkgpythondir
+This is the directory under @code{pythondir} that is named after the
+package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided
+as a convenience.
+
+ at item pyexecdir
+This is the directory where Python extension modules (shared libraries)
+should be installed. An extension module written in C could be declared
+as follows to Automake:
+
+ at c Keep in sync with primary-prefix-couples-documented-valid.test.
+ at example
+pyexec_LTLIBRARIES = quaternion.la
+quaternion_la_SOURCES = quaternion.c support.c support.h
+quaternion_la_LDFLAGS = -avoid-version -module
+ at end example
+
+ at item pkgpyexecdir
+This is a convenience variable that is defined as
+ at samp{$(pyexecdir)/$(PACKAGE)}.
+ at end vtable
+
+All these directory variables have values that start with either
+ at samp{$@{prefix@}} or @samp{$@{exec_prefix@}} unexpanded. This works
+fine in @file{Makefiles}, but it makes these variables hard to use in
+ at file{configure}. This is mandated by the GNU coding standards, so
+that the user can run @samp{make prefix=/foo install}. The Autoconf
+manual has a section with more details on this topic
+(@pxref{Installation Directory Variables, , Installation Directory
+Variables, autoconf, The Autoconf Manual}). See also @ref{Hard-Coded
+Install Paths}.
+
+
+ at node Documentation
+ at chapter Building documentation
+
+Currently Automake provides support for Texinfo and man pages.
+
+ at menu
+* Texinfo:: Texinfo
+* Man Pages:: Man pages
+ at end menu
+
+
+ at node Texinfo
+ at section Texinfo
+
+ at cindex @code{_TEXINFOS} primary, defined
+ at cindex @code{TEXINFOS} primary, defined
+ at cindex Primary variable, @code{TEXINFOS}
+ at cindex HTML output using Texinfo
+ at cindex PDF output using Texinfo
+ at cindex PS output using Texinfo
+ at cindex DVI output using Texinfo
+ at vindex _TEXINFOS
+ at vindex info_TEXINFOS
+
+If the current directory contains Texinfo source, you must declare it
+with the @code{TEXINFOS} primary. Generally Texinfo files are converted
+into info, and thus the @code{info_TEXINFOS} variable is most commonly used
+here. Any Texinfo source file must end in the @file{.texi},
+ at file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi}
+for new manuals.
+
+Automake generates rules to build @file{.info}, @file{.dvi},
+ at file{.ps}, @file{.pdf} and @file{.html} files from your Texinfo
+sources. Following the GNU Coding Standards, only the @file{.info}
+files are built by @samp{make all} and installed by @samp{make
+install} (unless you use @option{no-installinfo}, see below).
+Furthermore, @file{.info} files are automatically distributed so that
+Texinfo is not a prerequisite for installing your package.
+
+ at trindex dvi
+ at trindex html
+ at trindex pdf
+ at trindex ps
+ at trindex install-dvi
+ at trindex install-html
+ at trindex install-pdf
+ at trindex install-ps
+Other documentation formats can be built on request by @samp{make
+dvi}, @samp{make ps}, @samp{make pdf} and @samp{make html}, and they
+can be installed with @samp{make install-dvi}, @samp{make install-ps},
+ at samp{make install-pdf} and @samp{make install-html} explicitly.
+ at samp{make uninstall} will remove everything: the Texinfo
+documentation installed by default as well as all the above optional
+formats.
+
+All these targets can be extended using @samp{-local} rules
+(@pxref{Extending}).
+
+ at cindex Texinfo flag, @code{VERSION}
+ at cindex Texinfo flag, @code{UPDATED}
+ at cindex Texinfo flag, @code{EDITION}
+ at cindex Texinfo flag, @code{UPDATED-MONTH}
+
+ at cindex @code{VERSION} Texinfo flag
+ at cindex @code{UPDATED} Texinfo flag
+ at cindex @code{EDITION} Texinfo flag
+ at cindex @code{UPDATED-MONTH} Texinfo flag
+
+ at cindex @file{mdate-sh}
+
+If the @file{.texi} file @code{@@include}s @file{version.texi}, then
+that file will be automatically generated. The file @file{version.texi}
+defines four Texinfo flag you can reference using
+ at code{@@value@{EDITION@}}, @code{@@value@{VERSION@}},
+ at code{@@value@{UPDATED@}}, and @code{@@value@{UPDATED-MONTH@}}.
+
+ at table @code
+ at item EDITION
+ at itemx VERSION
+Both of these flags hold the version number of your program. They are
+kept separate for clarity.
+
+ at item UPDATED
+This holds the date the primary @file{.texi} file was last modified.
+
+ at item UPDATED-MONTH
+This holds the name of the month in which the primary @file{.texi} file
+was last modified.
+ at end table
+
+The @file{version.texi} support requires the @command{mdate-sh}
+script; this script is supplied with Automake and automatically
+included when @command{automake} is invoked with the
+ at option{--add-missing} option.
+
+If you have multiple Texinfo files, and you want to use the
+ at file{version.texi} feature, then you have to have a separate version
+file for each Texinfo file. Automake will treat any include in a
+Texinfo file that matches @file{vers*.texi} just as an automatically
+generated version file.
+
+Sometimes an info file actually depends on more than one @file{.texi}
+file. For instance, in GNU Hello, @file{hello.texi} includes the file
+ at file{fdl.texi}. You can tell Automake about these dependencies using
+the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
+ at vindex TEXINFOS
+ at vindex _TEXINFOS
+
+ at example
+info_TEXINFOS = hello.texi
+hello_TEXINFOS = fdl.texi
+ at end example
+
+ at cindex @file{texinfo.tex}
+
+By default, Automake requires the file @file{texinfo.tex} to appear in
+the same directory as the @file{Makefile.am} file that lists the
+ at file{.texi} files. If you used @code{AC_CONFIG_AUX_DIR} in
+ at file{configure.ac} (@pxref{Input, , Finding `configure' Input,
+autoconf, The Autoconf Manual}), then @file{texinfo.tex} is looked for
+there. In both cases, @command{automake} then supplies @file{texinfo.tex} if
+ at option{--add-missing} is given, and takes care of its distribution.
+However, if you set the @code{TEXINFO_TEX} variable (see below),
+it overrides the location of the file and turns off its installation
+into the source as well as its distribution.
+
+The option @option{no-texinfo.tex} can be used to eliminate the
+requirement for the file @file{texinfo.tex}. Use of the variable
+ at code{TEXINFO_TEX} is preferable, however, because that allows the
+ at code{dvi}, @code{ps}, and @code{pdf} targets to still work.
+
+ at cindex Option, @code{no-installinfo}
+ at cindex Target, @code{install-info}
+ at cindex @code{install-info} target
+ at cindex @code{no-installinfo} option
+
+ at opindex no-installinfo
+ at trindex install-info
+
+Automake generates an @code{install-info} rule; some people apparently
+use this. By default, info pages are installed by @samp{make
+install}, so running @code{make install-info} is pointless. This can
+be prevented via the @code{no-installinfo} option. In this case,
+ at file{.info} files are not installed by default, and user must
+request this explicitly using @samp{make install-info}.
+
+ at vindex AM_UPDATE_INFO_DIR
+By default, @code{make install-info} and @code{make install-info}
+will try to run the @command{install-info} program (if available)
+to update (or create) the @file{@code{$@{infodir@}}/dir} index.
+If this is undesired, it can be prevented by exporting the
+ at code{AM_UPDATE_INFO_DIR} variable to "@code{no}".
+
+The following variables are used by the Texinfo build rules.
+
+ at vtable @code
+ at item MAKEINFO
+The name of the program invoked to build @file{.info} files. This
+variable is defined by Automake. If the @command{makeinfo} program is
+found on the system then it will be used by default; otherwise
+ at command{missing} will be used instead.
+
+ at item MAKEINFOHTML
+The command invoked to build @file{.html} files. Automake
+defines this to @samp{$(MAKEINFO) --html}.
+
+ at item MAKEINFOFLAGS
+User flags passed to each invocation of @samp{$(MAKEINFO)} and
+ at samp{$(MAKEINFOHTML)}. This user variable (@pxref{User Variables}) is
+not expected to be defined in any @file{Makefile}; it can be used by
+users to pass extra flags to suit their needs.
+
+ at item AM_MAKEINFOFLAGS
+ at itemx AM_MAKEINFOHTMLFLAGS
+Maintainer flags passed to each @command{makeinfo} invocation. Unlike
+ at code{MAKEINFOFLAGS}, these variables are meant to be defined by
+maintainers in @file{Makefile.am}. @samp{$(AM_MAKEINFOFLAGS)} is
+passed to @code{makeinfo} when building @file{.info} files; and
+ at samp{$(AM_MAKEINFOHTMLFLAGS)} is used when building @file{.html}
+files.
+
+ at c Keep in sync with txinfo21.test.
+For instance, the following setting can be used to obtain one single
+ at file{.html} file per manual, without node separators.
+ at example
+AM_MAKEINFOHTMLFLAGS = --no-headers --no-split
+ at end example
+
+ at code{AM_MAKEINFOHTMLFLAGS} defaults to @samp{$(AM_MAKEINFOFLAGS)}.
+This means that defining @code{AM_MAKEINFOFLAGS} without defining
+ at code{AM_MAKEINFOHTMLFLAGS} will impact builds of both @file{.info}
+and @file{.html} files.
+
+ at item TEXI2DVI
+The name of the command that converts a @file{.texi} file into a
+ at file{.dvi} file. This defaults to @samp{texi2dvi}, a script that ships
+with the Texinfo package.
+
+ at item TEXI2PDF
+The name of the command that translates a @file{.texi} file into a
+ at file{.pdf} file. This defaults to @samp{$(TEXI2DVI) --pdf --batch}.
+
+ at item DVIPS
+The name of the command that builds a @file{.ps} file out of a
+ at file{.dvi} file. This defaults to @samp{dvips}.
+
+ at item TEXINFO_TEX
+
+If your package has Texinfo files in many directories, you can use the
+variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
+ at file{texinfo.tex} for your package. The value of this variable should
+be the relative path from the current @file{Makefile.am} to
+ at file{texinfo.tex}:
+
+ at example
+TEXINFO_TEX = ../doc/texinfo.tex
+ at end example
+ at end vtable
+
+
+ at node Man Pages
+ at section Man Pages
+
+ at cindex @code{_MANS} primary, defined
+ at cindex @code{MANS} primary, defined
+ at cindex Primary variable, @code{MANS}
+
+ at vindex _MANS
+ at vindex man_MANS
+A package can also include man pages (but see the GNU standards on this
+matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
+pages are declared using the @code{MANS} primary. Generally the
+ at code{man_MANS} variable is used. Man pages are automatically installed in
+the correct subdirectory of @code{mandir}, based on the file extension.
+
+File extensions such as @file{.1c} are handled by looking for the valid
+part of the extension and using that to determine the correct
+subdirectory of @code{mandir}. Valid section names are the digits
+ at samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
+
+Sometimes developers prefer to name a man page something like
+ at file{foo.man} in the source, and then rename it to have the correct
+suffix, for example @file{foo.1}, when installing the file. Automake
+also supports this mode. For a valid section named @var{section},
+there is a corresponding directory named @samp{man at var{section}dir},
+and a corresponding @code{_MANS} variable. Files listed in such a
+variable are installed in the indicated section. If the file already
+has a valid suffix, then it is installed as-is; otherwise the file
+suffix is changed to match the section.
+
+For instance, consider this example:
+ at example
+man1_MANS = rename.man thesame.1 alsothesame.1c
+ at end example
+
+ at noindent
+In this case, @file{rename.man} will be renamed to @file{rename.1} when
+installed, but the other files will keep their names.
+
+ at cindex Target, @code{install-man}
+ at cindex Option, @option{no-installman}
+ at cindex @code{install-man} target
+ at cindex @option{no-installman} option
+ at opindex no-installman
+ at trindex install-man
+
+By default, man pages are installed by @samp{make install}. However,
+since the GNU project does not require man pages, many maintainers do
+not expend effort to keep the man pages up to date. In these cases, the
+ at option{no-installman} option will prevent the man pages from being
+installed by default. The user can still explicitly install them via
+ at samp{make install-man}.
+
+For fast installation, with many files it is preferable to use
+ at samp{man at var{section}_MANS} over @samp{man_MANS} as well as files that
+do not need to be renamed.
+
+Man pages are not currently considered to be source, because it is not
+uncommon for man pages to be automatically generated. Therefore they
+are not automatically included in the distribution. However, this can
+be changed by use of the @code{dist_} prefix. For instance here is
+how to distribute and install the two man pages of GNU @command{cpio}
+(which includes both Texinfo documentation and man pages):
+
+ at example
+dist_man_MANS = cpio.1 mt.1
+ at end example
+
+The @code{nobase_} prefix is meaningless for man pages and is
+disallowed.
+
+ at vindex notrans_
+ at cindex @code{notrans_} prefix
+ at cindex Man page renaming, avoiding
+ at cindex Avoiding man page renaming
+
+Executables and manpages may be renamed upon installation
+(@pxref{Renaming}). For manpages this can be avoided by use of the
+ at code{notrans_} prefix. For instance, suppose an executable @samp{foo}
+allowing to access a library function @samp{foo} from the command line.
+The way to avoid renaming of the @file{foo.3} manpage is:
+
+ at example
+man_MANS = foo.1
+notrans_man_MANS = foo.3
+ at end example
+
+ at cindex @code{notrans_} and @code{dist_} or @code{nodist_}
+ at cindex @code{dist_} and @code{notrans_}
+ at cindex @code{nodist_} and @code{notrans_}
+
+ at samp{notrans_} must be specified first when used in conjunction with
+either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
+Control}). For instance:
+
+ at example
+notrans_dist_man3_MANS = bar.3
+ at end example
+
+ at node Install
+ at chapter What Gets Installed
+
+ at cindex Installation support
+ at cindex @samp{make install} support
+
+Naturally, Automake handles the details of actually installing your
+program once it has been built. All files named by the various
+primaries are automatically installed in the appropriate places when the
+user runs @samp{make install}.
+
+ at menu
+* Basics of Installation:: What gets installed where
+* The Two Parts of Install:: Installing data and programs separately
+* Extending Installation:: Adding your own rules for installation
+* Staged Installs:: Installation in a temporary location
+* Install Rules for the User:: Useful additional rules
+ at end menu
+
+ at node Basics of Installation
+ at section Basics of Installation
+
+A file named in a primary is installed by copying the built file into
+the appropriate directory. The base name of the file is used when
+installing.
+
+ at example
+bin_PROGRAMS = hello subdir/goodbye
+ at end example
+
+In this example, both @samp{hello} and @samp{goodbye} will be installed
+in @samp{$(bindir)}.
+
+Sometimes it is useful to avoid the basename step at install time. For
+instance, you might have a number of header files in subdirectories of
+the source tree that are laid out precisely how you want to install
+them. In this situation you can use the @code{nobase_} prefix to
+suppress the base name step. For example:
+
+ at example
+nobase_include_HEADERS = stdio.h sys/types.h
+ at end example
+
+ at noindent
+will install @file{stdio.h} in @samp{$(includedir)} and @file{types.h}
+in @samp{$(includedir)/sys}.
+
+For most file types, Automake will install multiple files at once, while
+avoiding command line length issues (@pxref{Length Limitations}). Since
+some @command{install} programs will not install the same file twice in
+one invocation, you may need to ensure that file lists are unique within
+one variable such as @samp{nobase_include_HEADERS} above.
+
+You should not rely on the order in which files listed in one variable
+are installed. Likewise, to cater for parallel make, you should not
+rely on any particular file installation order even among different
+file types (library dependencies are an exception here).
+
+
+ at node The Two Parts of Install
+ at section The Two Parts of Install
+
+Automake generates separate @code{install-data} and @code{install-exec}
+rules, in case the installer is installing on multiple machines that
+share directory structure---these targets allow the machine-independent
+parts to be installed only once. @code{install-exec} installs
+platform-dependent files, and @code{install-data} installs
+platform-independent files. The @code{install} target depends on both
+of these targets. While Automake tries to automatically segregate
+objects into the correct category, the @file{Makefile.am} author is, in
+the end, responsible for making sure this is done correctly.
+ at trindex install-data
+ at trindex install-exec
+ at trindex install
+ at cindex Install, two parts of
+
+Variables using the standard directory prefixes @samp{data},
+ at samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
+ at samp{pkgdata}, or @samp{pkginclude} are installed by
+ at code{install-data}.
+
+Variables using the standard directory prefixes @samp{bin},
+ at samp{sbin}, @samp{libexec}, @samp{sysconf}, @samp{localstate},
+ at samp{lib}, or @samp{pkglib} are installed by @code{install-exec}.
+
+For instance, @code{data_DATA} files are installed by @code{install-data},
+while @code{bin_PROGRAMS} files are installed by @code{install-exec}.
+
+Any variable using a user-defined directory prefix with
+ at samp{exec} in the name (e.g.,
+ at c Keep in sync with primary-prefix-couples-documented-valid.test.
+ at code{myexecbin_PROGRAMS}) is installed by @code{install-exec}. All
+other user-defined prefixes are installed by @code{install-data}.
+
+ at node Extending Installation
+ at section Extending Installation
+
+It is possible to extend this mechanism by defining an
+ at code{install-exec-local} or @code{install-data-local} rule. If these
+rules exist, they will be run at @samp{make install} time. These
+rules can do almost anything; care is required.
+ at trindex install-exec-local
+ at trindex install-data-local
+
+Automake also supports two install hooks, @code{install-exec-hook} and
+ at code{install-data-hook}. These hooks are run after all other install
+rules of the appropriate type, exec or data, have completed. So, for
+instance, it is possible to perform post-installation modifications
+using an install hook. @xref{Extending}, for some examples.
+ at cindex Install hook
+
+ at node Staged Installs
+ at section Staged Installs
+
+ at vindex DESTDIR
+Automake generates support for the @code{DESTDIR} variable in all
+install rules. @code{DESTDIR} is used during the @samp{make install}
+step to relocate install objects into a staging area. Each object and
+path is prefixed with the value of @code{DESTDIR} before being copied
+into the install area. Here is an example of typical DESTDIR usage:
+
+ at example
+mkdir /tmp/staging &&
+make DESTDIR=/tmp/staging install
+ at end example
+
+The @command{mkdir} command avoids a security problem if the attacker
+creates a symbolic link from @file{/tmp/staging} to a victim area;
+then @command{make} places install objects in a directory tree built under
+ at file{/tmp/staging}. If @file{/gnu/bin/foo} and
+ at file{/gnu/share/aclocal/foo.m4} are to be installed, the above command
+would install @file{/tmp/staging/gnu/bin/foo} and
+ at file{/tmp/staging/gnu/share/aclocal/foo.m4}.
+
+This feature is commonly used to build install images and packages
+(@pxref{DESTDIR}).
+
+Support for @code{DESTDIR} is implemented by coding it directly into
+the install rules. If your @file{Makefile.am} uses a local install
+rule (e.g., @code{install-exec-local}) or an install hook, then you
+must write that code to respect @code{DESTDIR}.
+
+ at xref{Makefile Conventions, , , standards, The GNU Coding Standards},
+for another usage example.
+
+ at node Install Rules for the User
+ at section Install Rules for the User
+
+Automake also generates rules for targets @code{uninstall},
+ at code{installdirs}, and @code{install-strip}.
+ at trindex uninstall
+ at trindex installdirs
+ at trindex install-strip
+
+Automake supports @code{uninstall-local} and @code{uninstall-hook}.
+There is no notion of separate uninstalls for ``exec'' and ``data'', as
+these features would not provide additional functionality.
+
+Note that @code{uninstall} is not meant as a replacement for a real
+packaging tool.
+
+
+ at node Clean
+ at chapter What Gets Cleaned
+
+ at cindex @samp{make clean} support
+
+The GNU Makefile Standards specify a number of different clean rules.
+ at xref{Standard Targets, , Standard Targets for Users, standards,
+The GNU Coding Standards}.
+
+Generally the files that can be cleaned are determined automatically by
+Automake. Of course, Automake also recognizes some variables that can
+be defined to specify additional files to clean. These variables are
+ at code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
+ at code{MAINTAINERCLEANFILES}.
+ at vindex MOSTLYCLEANFILES
+ at vindex CLEANFILES
+ at vindex DISTCLEANFILES
+ at vindex MAINTAINERCLEANFILES
+
+ at trindex mostlyclean-local
+ at trindex clean-local
+ at trindex distclean-local
+ at trindex maintainer-clean-local
+When cleaning involves more than deleting some hard-coded list of
+files, it is also possible to supplement the cleaning rules with your
+own commands. Simply define a rule for any of the
+ at code{mostlyclean-local}, @code{clean-local}, @code{distclean-local},
+or @code{maintainer-clean-local} targets (@pxref{Extending}). A common
+case is deleting a directory, for instance, a directory created by the
+test suite:
+
+ at example
+clean-local:
+ -rm -rf testSubDir
+ at end example
+
+Since @command{make} allows only one set of rules for a given target,
+a more extensible way of writing this is to use a separate target
+listed as a dependency:
+
+ at example
+clean-local: clean-local-check
+.PHONY: clean-local-check
+clean-local-check:
+ -rm -rf testSubDir
+ at end example
+
+As the GNU Standards aren't always explicit as to which files should
+be removed by which rule, we've adopted a heuristic that we believe
+was first formulated by Fran@,{c}ois Pinard:
+
+ at itemize @bullet
+ at item
+If @command{make} built it, and it is commonly something that one would
+want to rebuild (for instance, a @file{.o} file), then
+ at code{mostlyclean} should delete it.
+
+ at item
+Otherwise, if @command{make} built it, then @code{clean} should delete it.
+
+ at item
+If @command{configure} built it, then @code{distclean} should delete it.
+
+ at item
+If the maintainer built it (for instance, a @file{.info} file), then
+ at code{maintainer-clean} should delete it. However
+ at code{maintainer-clean} should not delete anything that needs to exist
+in order to run @samp{./configure && make}.
+ at end itemize
+
+We recommend that you follow this same set of heuristics in your
+ at file{Makefile.am}.
+
+
+ at node Dist
+ at chapter What Goes in a Distribution
+
+ at menu
+* Basics of Distribution:: Files distributed by default
+* Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes
+* The dist Hook:: A target for last-minute distribution changes
+* Checking the Distribution:: @samp{make distcheck} explained
+* The Types of Distributions:: A variety of formats and compression methods
+ at end menu
+
+ at node Basics of Distribution
+ at section Basics of Distribution
+
+ at cindex @samp{make dist}
+
+ at vindex PACKAGE
+ at vindex VERSION
+ at trindex dist
+The @code{dist} rule in the generated @file{Makefile.in} can be used
+to generate a gzipped @code{tar} file and other flavors of archive for
+distribution. The file is named based on the @code{PACKAGE} and
+ at code{VERSION} variables defined by @code{AM_INIT_AUTOMAKE}
+(@pxref{Macros}); more precisely the gzipped @code{tar} file is named
+ at samp{@var{package}- at var{version}.tar.gz}.
+ at vindex GZIP_ENV
+You can use the @command{make} variable @code{GZIP_ENV} to control how gzip
+is run. The default setting is @option{--best}.
+
+ at cindex @code{m4_include}, distribution
+ at cindex @code{include}, distribution
+ at acindex m4_include
+ at cmindex include
+For the most part, the files to distribute are automatically found by
+Automake: all source files are automatically included in a distribution,
+as are all @file{Makefile.am} and @file{Makefile.in} files. Automake also
+has a built-in list of commonly used files that are automatically
+included if they are found in the current directory (either physically,
+or as the target of a @file{Makefile.am} rule); this list is printed by
+ at samp{automake --help}. Note that some files in this list are actually
+distributed only if other certain conditions hold (for example,
+ at c Keep in sync with autodist-config-headers.test.
+the @file{config.h.top} and @file{config.h.bot} files are automatically
+distributed only if, e.g., @samp{AC_CONFIG_HEADERS([config.h])} is used
+in @file{configure.ac}). Also, files that are read by @command{configure}
+(i.e.@: the source files corresponding to the files specified in various
+Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are
+automatically distributed. Files included in a @file{Makefile.am} (using
+ at code{include}) or in @file{configure.ac} (using @code{m4_include}), and
+helper scripts installed with @samp{automake --add-missing} are also
+distributed.
+
+ at vindex EXTRA_DIST
+Still, sometimes there are files that must be distributed, but which
+are not covered in the automatic rules. These files should be listed in
+the @code{EXTRA_DIST} variable. You can mention files from
+subdirectories in @code{EXTRA_DIST}.
+
+You can also mention a directory in @code{EXTRA_DIST}; in this case the
+entire directory will be recursively copied into the distribution.
+Please note that this will also copy @emph{everything} in the directory,
+including, e.g., Subversion's @file{.svn} private directories or CVS/RCS
+version control files. We recommend against using this feature.
+
+ at vindex SUBDIRS
+ at vindex DIST_SUBDIRS
+If you define @code{SUBDIRS}, Automake will recursively include the
+subdirectories in the distribution. If @code{SUBDIRS} is defined
+conditionally (@pxref{Conditionals}), Automake will normally include
+all directories that could possibly appear in @code{SUBDIRS} in the
+distribution. If you need to specify the set of directories
+conditionally, you can set the variable @code{DIST_SUBDIRS} to the
+exact list of subdirectories to include in the distribution
+(@pxref{Conditional Subdirectories}).
+
+
+ at node Fine-grained Distribution Control
+ at section Fine-grained Distribution Control
+
+ at vindex dist_
+ at vindex nodist_
+Sometimes you need tighter control over what does @emph{not} go into the
+distribution; for instance, you might have source files that are
+generated and that you do not want to distribute. In this case
+Automake gives fine-grained control using the @code{dist} and
+ at code{nodist} prefixes. Any primary or @code{_SOURCES} variable can be
+prefixed with @code{dist_} to add the listed files to the distribution.
+Similarly, @code{nodist_} can be used to omit the files from the
+distribution.
+
+As an example, here is how you would cause some data to be distributed
+while leaving some source code out of the distribution:
+
+ at example
+dist_data_DATA = distribute-this
+bin_PROGRAMS = foo
+nodist_foo_SOURCES = do-not-distribute.c
+ at end example
+
+ at node The dist Hook
+ at section The dist Hook
+
+ at trindex dist-hook
+
+Occasionally it is useful to be able to change the distribution before
+it is packaged up. If the @code{dist-hook} rule exists, it is run
+after the distribution directory is filled, but before the actual tar
+(or shar) file is created. One way to use this is for distributing
+files in subdirectories for which a new @file{Makefile.am} is overkill:
+
+ at example
+dist-hook:
+ mkdir $(distdir)/random
+ cp -p $(srcdir)/random/a1 $(srcdir)/random/a2 $(distdir)/random
+ at end example
+
+Another way to use this is for removing unnecessary files that get
+recursively included by specifying a directory in EXTRA_DIST:
+
+ at example
+EXTRA_DIST = doc
+
+dist-hook:
+ rm -rf `find $(distdir)/doc -type d -name .svn`
+ at end example
+
+ at vindex distdir
+ at vindex top_distdir
+Two variables that come handy when writing @code{dist-hook} rules are
+ at samp{$(distdir)} and @samp{$(top_distdir)}.
+
+ at samp{$(distdir)} points to the directory where the @code{dist} rule
+will copy files from the current directory before creating the
+tarball. If you are at the top-level directory, then @samp{distdir =
+$(PACKAGE)-$(VERSION)}. When used from subdirectory named
+ at file{foo/}, then @samp{distdir = ../$(PACKAGE)-$(VERSION)/foo}.
+ at samp{$(distdir)} can be a relative or absolute path, do not assume
+any form.
+
+ at samp{$(top_distdir)} always points to the root directory of the
+distributed tree. At the top-level it's equal to @samp{$(distdir)}.
+In the @file{foo/} subdirectory
+ at samp{top_distdir = ../$(PACKAGE)-$(VERSION)}.
+ at samp{$(top_distdir)} too can be a relative or absolute path.
+
+Note that when packages are nested using @code{AC_CONFIG_SUBDIRS}
+(@pxref{Subpackages}), then @samp{$(distdir)} and
+ at samp{$(top_distdir)} are relative to the package where @samp{make
+dist} was run, not to any sub-packages involved.
+
+ at node Checking the Distribution
+ at section Checking the Distribution
+
+ at cindex @samp{make distcheck}
+ at cindex @samp{make distcleancheck}
+ at vindex distcleancheck_listfiles
+ at cindex @samp{make distuninstallcheck}
+ at vindex distuninstallcheck_listfiles
+
+ at trindex distcheck
+Automake also generates a @code{distcheck} rule that can be of help to
+ensure that a given distribution will actually work. @code{distcheck}
+makes a distribution, then tries to do a @code{VPATH} build
+(@pxref{VPATH Builds}), run the test suite, and finally make another
+tarball to ensure the distribution is self-contained.
+
+ at vindex AM_DISTCHECK_CONFIGURE_FLAGS
+ at vindex DISTCHECK_CONFIGURE_FLAGS
+Building the package involves running @samp{./configure}. If you need
+to supply additional flags to @command{configure}, define them in the
+ at code{AM_DISTCHECK_CONFIGURE_FLAGS} variable in your top-level
+ at file{Makefile.am}. The user can still extend or override the flags
+provided there by defining the @code{DISTCHECK_CONFIGURE_FLAGS} variable,
+on the command line when invoking @command{make}.
+
+Still, developers are encouraged to strive to make their code buildable
+without requiring any special configure option; thus, in general, you
+shouldn't define @code{AM_DISTCHECK_CONFIGURE_FLAGS}. However, there
+might be few scenarios in which the use of this variable is justified.
+GNU @command{m4} offers an example. GNU @command{m4} configures by
+default with its experimental and seldom used "changeword" feature
+disabled; so in its case it is useful to have @command{make distcheck}
+run configure with the @option{--with-changeword} option, to ensure that
+the code for changeword support still compiles correctly.
+GNU @command{m4} also employs the @code{AM_DISTCHECK_CONFIGURE_FLAGS}
+variable to stress-test the use of @option{--program-prefix=g}, since at
+one point the @command{m4} build system had a bug where @command{make
+installcheck} was wrongly assuming it could blindly test "@command{m4}",
+rather than the just-installed "@command{gm4}".
+
+ at trindex distcheck-hook
+If the @code{distcheck-hook} rule is defined in your top-level
+ at file{Makefile.am}, then it will be invoked by @code{distcheck} after
+the new distribution has been unpacked, but before the unpacked copy
+is configured and built. Your @code{distcheck-hook} can do almost
+anything, though as always caution is advised. Generally this hook is
+used to check for potential distribution errors not caught by the
+standard mechanism. Note that @code{distcheck-hook} as well as
+ at code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS}
+are not honored in a subpackage @file{Makefile.am}, but the flags from
+ at code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS}
+are passed down to the @command{configure} script of the subpackage.
+
+ at trindex distcleancheck
+ at vindex DISTCLEANFILES
+ at vindex distcleancheck_listfiles
+Speaking of potential distribution errors, @code{distcheck} also
+ensures that the @code{distclean} rule actually removes all built
+files. This is done by running @samp{make distcleancheck} at the end of
+the @code{VPATH} build. By default, @code{distcleancheck} will run
+ at code{distclean} and then make sure the build tree has been emptied by
+running @samp{$(distcleancheck_listfiles)}. Usually this check will
+find generated files that you forgot to add to the @code{DISTCLEANFILES}
+variable (@pxref{Clean}).
+
+The @code{distcleancheck} behavior should be OK for most packages,
+otherwise you have the possibility to override the definition of
+either the @code{distcleancheck} rule, or the
+ at samp{$(distcleancheck_listfiles)} variable. For instance, to disable
+ at code{distcleancheck} completely, add the following rule to your
+top-level @file{Makefile.am}:
+
+ at example
+distcleancheck:
+ @@:
+ at end example
+
+If you want @code{distcleancheck} to ignore built files that have not
+been cleaned because they are also part of the distribution, add the
+following definition instead:
+
+ at c Keep in sync with distcleancheck.test.
+ at example
+distcleancheck_listfiles = \
+ find . -type f -exec sh -c 'test -f $(srcdir)/$$1 || echo $$1' \
+ sh '@{@}' ';'
+ at end example
+
+The above definition is not the default because it's usually an error if
+your Makefiles cause some distributed files to be rebuilt when the user
+build the package. (Think about the user missing the tool required to
+build the file; or if the required tool is built by your package,
+consider the cross-compilation case where it can't be run.) There is
+an entry in the FAQ about this (@pxref{distcleancheck}), make sure you
+read it before playing with @code{distcleancheck_listfiles}.
+
+ at code{distcheck} also checks that the @code{uninstall} rule works
+properly, both for ordinary and @code{DESTDIR} builds. It does this
+by invoking @samp{make uninstall}, and then it checks the install tree
+to see if any files are left over. This check will make sure that you
+correctly coded your @code{uninstall}-related rules.
+
+By default, the checking is done by the @code{distuninstallcheck} rule,
+and the list of files in the install tree is generated by
+ at samp{$(distuninstallcheck_listfiles)} (this is a variable whose value is
+a shell command to run that prints the list of files to stdout).
+
+Either of these can be overridden to modify the behavior of
+ at code{distcheck}. For instance, to disable this check completely, you
+would write:
+
+ at example
+distuninstallcheck:
+ @@:
+ at end example
+
+ at node The Types of Distributions
+ at section The Types of Distributions
+
+Automake generates rules to provide archives of the project for
+distributions in various formats. Their targets are:
+
+ at table @asis
+ at vindex BZIP2
+ at item @code{dist-bzip2}
+Generate a bzip2 tar archive of the distribution. bzip2 archives are
+frequently smaller than gzipped archives.
+By default, this rule makes @samp{bzip2} use a compression option of
+ at option{-9}. To make it use a different one, set the @env{BZIP2}
+environment variable. For example, @samp{make dist-bzip2 BZIP2=-7}.
+ at trindex dist-bzip2
+
+ at item @code{dist-gzip}
+Generate a gzip tar archive of the distribution.
+ at trindex dist-gzip
+
+ at item @code{dist-lzip}
+Generate a @samp{lzip} tar archive of the distribution. @command{lzip}
+archives are frequently smaller than @command{bzip2}-compressed archives.
+ at trindex dist-lzip
+
+ at item @code{dist-lzma}
+Generate an @samp{lzma} tar archive of the distribution.
+The @samp{lzma} format is obsolete, you should use the @samp{xz} format
+instead. @emph{Support for @samp{lzma}-compressed archives will be
+removed in the next major Automake release.}
+ at trindex dist-lzma
+
+ at item @code{dist-shar}
+Generate a shar archive of the distribution.
+ at trindex dist-shar
+
+ at vindex XZ_OPT
+ at item @code{dist-xz}
+Generate an @samp{xz} tar archive of the distribution. @command{xz}
+archives are frequently smaller than @command{bzip2}-compressed archives.
+The @samp{xz} format displaces the obsolete @samp{lzma} format.
+By default, this rule makes @samp{xz} use a compression option of
+ at option{-e}. To make it use a different one, set the @env{XZ_OPT}
+environment variable. For example, run this command to use the
+default compression ratio, but with a progress indicator:
+ at samp{make dist-xz XZ_OPT=-7e}.
+ at trindex dist-xz
+
+ at item @code{dist-zip}
+Generate a zip archive of the distribution.
+ at trindex dist-zip
+
+ at item @code{dist-tarZ}
+Generate a compressed tar archive of
+the distribution.
+ at trindex dist-tarZ
+ at end table
+
+The rule @code{dist} (and its historical synonym @code{dist-all}) will
+create archives in all the enabled formats, @ref{Options}. By
+default, only the @code{dist-gzip} target is hooked to @code{dist}.
+
+
+ at node Tests
+ at chapter Support for test suites
+
+ at cindex Test suites
+ at cindex @code{make check}
+ at trindex check
+
+Automake supports three forms of test suites, the first two of which
+are very similar.
+
+ at menu
+* Simple Tests:: Listing programs and scripts in @code{TESTS}
+* Simple Tests using parallel-tests:: More powerful test driver
+* DejaGnu Tests:: Interfacing with the external testing framework
+* Install Tests:: Running tests on installed packages
+ at end menu
+
+ at node Simple Tests
+ at section Simple Tests
+
+If the variable @code{TESTS} is defined, its value is taken to be a
+list of programs or scripts to run in order to do the testing.
+Programs needing data files should look for them in @code{srcdir}
+(which is both an environment variable and a make variable) so they
+work when building in a separate directory (@pxref{Build Directories,
+, Build Directories , autoconf, The Autoconf Manual}), and in
+particular for the @code{distcheck} rule (@pxref{Checking the
+Distribution}).
+
+For each of the @code{TESTS}, the result of execution is printed along
+with the test name, where @code{PASS} denotes a successful test,
+ at code{FAIL} denotes a failed test, @code{XFAIL} an expected failure,
+ at code{XPASS} an unexpected pass for a test that is supposed to fail,
+and @code{SKIP} denotes a skipped test.
+
+ at cindex Exit status 77, special interpretation
+
+The number of failures will be printed at the end of the run. If a
+given test program exits with a status of 77, then its result is ignored
+in the final count. This feature allows non-portable tests to be
+ignored in environments where they don't make sense.
+
+ at vindex AM_COLOR_TESTS
+If the Automake option @code{color-tests} is used (@pxref{Options})
+and standard output is connected to a capable terminal, then the test
+results and the summary are colored appropriately. The user can disable
+colored output by setting the @command{make} variable
+ at samp{AM_COLOR_TESTS=no}, or force colored output even without a connecting
+terminal with @samp{AM_COLOR_TESTS=always}.
+
+Note that the semantics of some @command{make} implementations when used
+in parallel mode (@pxref{Parallel make,,, autoconf, The Autoconf Manual})
+can cause the automatic detection of a connection to a capable terminal
+to fail. In that case, you can still resort to the use of
+ at samp{AM_COLOR_TESTS=always}.
+
+ at vindex TESTS
+ at vindex TESTS_ENVIRONMENT
+The variable @code{TESTS_ENVIRONMENT} can be used to set environment
+variables for the test run; the environment variable @env{srcdir} is
+set in the rule. If all your test programs are scripts, you can also
+set @code{TESTS_ENVIRONMENT} to an invocation of the shell (e.g.
+ at samp{$(SHELL) -x} can be useful for debugging the tests), or any other
+interpreter. For instance, the following setup may be used to run tests
+with Perl:
+
+ at c Keep in sync with tests-environment-backcompat.test.
+ at example
+TESTS_ENVIRONMENT = $(PERL) -Mstrict -w
+TESTS = foo.pl bar.pl baz.pl
+ at end example
+
+Note that the @option{parallel-tests} driver provides a more elegant
+way to achieve the same effect, freeing the @code{TESTS_ENVIRONMENT}
+variable for the user to override (@pxref{Simple Tests using
+parallel-tests}).
+
+
+ at cindex Tests, expected failure
+ at cindex Expected test failure
+
+ at vindex XFAIL_TESTS
+You may define the variable @code{XFAIL_TESTS} to a list of tests
+(usually a subset of @code{TESTS}) that are expected to fail. This will
+reverse the result of those tests.
+
+Automake ensures that each file listed in @code{TESTS} is built before
+any tests are run; you can list both source and derived programs (or
+scripts) in @code{TESTS}; the generated rule will look both in
+ at code{srcdir} and @file{.}. For instance, you might want to run a C
+program as a test. To do this you would list its name in @code{TESTS}
+and also in @code{check_PROGRAMS}, and then specify it as you would
+any other program.
+
+Programs listed in @code{check_PROGRAMS} (and @code{check_LIBRARIES},
+ at code{check_LTLIBRARIES}...) are only built during @code{make check},
+not during @code{make all}. You should list there any program needed
+by your tests that does not need to be built by @code{make all}. Note
+that @code{check_PROGRAMS} are @emph{not} automatically added to
+ at code{TESTS} because @code{check_PROGRAMS} usually lists programs used
+by the tests, not the tests themselves. Of course you can set
+ at code{TESTS = $(check_PROGRAMS)} if all your programs are test cases.
+
+
+ at node Simple Tests using parallel-tests
+ at section Simple Tests using @samp{parallel-tests}
+ at cindex @option{parallel-tests}, Using
+
+The option @option{parallel-tests} (@pxref{Options}) enables a test suite
+driver that is mostly compatible to the simple test driver described in
+the previous section, but provides a few more features and slightly
+different semantics. It features concurrent execution of tests with
+ at code{make -j} and automatic collection of the test scripts output and
+summary thereof in @file{.log} files, and allows to specify inter-test
+dependencies, lazy reruns of tests that have not completed in a prior
+run, and hard errors for exceptional failures. Similar to the simple
+test driver, @code{TESTS_ENVIRONMENT}, @code{AM_COLOR_TESTS},
+ at code{XFAIL_TESTS}, and the @code{check_*} variables are honored,
+and the environment variable @env{srcdir} is set during test execution.
+
+This test driver is still experimental and may undergo changes in order
+to satisfy additional portability requirements.
+
+ at vindex TEST_SUITE_LOG
+ at vindex TESTS
+The driver operates by defining a set of @command{make} rules to create
+a summary log file, @code{TEST_SUITE_LOG}, which defaults to
+ at file{test-suite.log} and requires a @file{.log} suffix. This file
+depends upon log files created for each single test program listed in
+ at code{TESTS}, which in turn contain all output produced by the
+corresponding tests.
+
+ at vindex TEST_EXTENSIONS
+ at vindex TEST_LOGS
+Each log file is created when the corresponding test has completed.
+The set of log files is listed in the read-only variable
+ at code{TEST_LOGS}, and defaults to @code{TESTS}, with the executable
+extension if any (@pxref{EXEEXT}), as well as any suffix listed in
+ at code{TEST_EXTENSIONS} removed, and @file{.log} appended. Results
+are undefined if a test file name ends in several concatenated suffixes.
+ at code{TEST_EXTENSIONS} defaults to @file{.test}; it can be overridden by
+the user, in which case any extension listed in it must be constituted
+by a dot, followed by a non-digit alphabetic character, followed by any
+number of alphabetic characters.
+ at c Keep in sync with test-extensions.test.
+For example, @samp{.sh}, @samp{.T} and @samp{.t1} are valid extensions,
+while @samp{.x-y}, @samp{.6c} and @samp{.t.1} are not.
+
+ at vindex _LOG_COMPILE
+ at vindex _LOG_COMPILER
+ at vindex _LOG_FLAGS
+ at vindex LOG_COMPILE
+ at vindex LOG_COMPILER
+ at vindex LOG_FLAGS
+ at vindex @var{ext}_LOG_COMPILE
+ at vindex @var{ext}_LOG_COMPILER
+ at vindex @var{ext}_LOG_FLAGS
+ at vindex AM_ at var{ext}_LOG_FLAGS
+ at vindex AM_LOG_FLAGS
+For tests that match an extension @code{. at var{ext}} listed in
+ at code{TEST_EXTENSIONS}, you can provide a test driver using the variable
+ at code{@var{ext}_LOG_COMPILER} (note the upper-case extension) and pass
+options in @code{AM_ at var{ext}_LOG_FLAGS} and allow the user to pass
+options in @code{@var{ext}_LOG_FLAGS}. It will cause all tests with
+this extension to be called with this driver. For all tests without a
+registered extension, the variables @code{LOG_COMPILER},
+ at code{AM_LOG_FLAGS}, and @code{LOG_FLAGS} may be used. For example,
+
+ at c Keep in sync with parallel-tests-log-compiler-example.test.
+ at example
+TESTS = foo.pl bar.py baz
+TEST_EXTENSIONS = .pl .py
+PL_LOG_COMPILER = $(PERL)
+AM_PL_LOG_FLAGS = -w
+PY_LOG_COMPILER = $(PYTHON)
+AM_PY_LOG_FLAGS = -v
+LOG_COMPILER = ./wrapper-script
+AM_LOG_FLAGS = -d
+ at end example
+
+ at noindent
+will invoke @samp{$(PERL) -w foo.pl}, @samp{$(PYTHON) -v bar.py},
+and @samp{./wrapper-script -d baz} to produce @file{foo.log},
+ at file{bar.log}, and @file{baz.log}, respectively. The
+ at samp{TESTS_ENVIRONMENT} variable is still expanded before the driver,
+but should be reserved for the user.
+
+ at vindex VERBOSE
+As with the simple driver above, by default one status line is printed
+per completed test, and a short summary after the suite has completed.
+However, standard output and standard error of the test are redirected
+to a per-test log file, so that parallel execution does not produce
+intermingled output. The output from failed tests is collected in the
+ at file{test-suite.log} file. If the variable @samp{VERBOSE} is set, this
+file is output after the summary. For best results, the tests should be
+verbose by default now.
+
+ at trindex check-html
+ at vindex RST2HTML
+ at vindex TEST_SUITE_HTML
+Previous versions of automake used to provide a @code{check-html} target
+to convert the log files to HTML. This feature is now deprecated, and
+ at emph{will be removed} in the next major Automake release, so don't rely
+on it anymore.
+
+ at vindex DISABLE_HARD_ERRORS
+ at cindex Exit status 99, special interpretation
+ at cindex hard error
+Even in the presence of expected failures (see @code{XFAIL_TESTS}), there
+may be conditions under which a test outcome needs attention. For
+example, with test-driven development, you may write tests for features
+that you have not implemented yet, and thus mark these tests as expected
+to fail. However, you may still be interested in exceptional conditions,
+for example, tests that fail due to a segmentation violation or another
+error that is independent of the feature awaiting implementation.
+Tests can exit with an exit status of 99 to signal such a @emph{hard
+error}. Unless the variable @code{DISABLE_HARD_ERRORS} is set to a
+nonempty value, such tests will be counted as failed.
+
+By default, the test suite driver will run all tests, but there are
+several ways to limit the set of tests that are run:
+
+ at itemize @bullet
+ at item
+You can set the @code{TESTS} variable, similarly to how you can with
+the simple test driver from the previous section. For example, you can
+use a command like this to run only a subset of the tests:
+
+ at example
+env TESTS="foo.test bar.test" make -e check
+ at end example
+
+Note however that the command above will unconditionally overwrite the
+ at file{test-suite.log} file, thus clobbering the recorded results
+of any previous testsuite run. This might be undesirable for packages
+whose testsuite takes long time to execute. Luckily, this problem can
+easily be avoided by overriding also @code{TEST_SUITE_LOG} at runtime;
+for example,
+
+ at c Keep in sync with parallel-tests-log-override-2.test.
+ at example
+env TEST_SUITE_LOG=partial.log TESTS="..." make -e check
+ at end example
+
+will write the result of the partial testsuite runs to the
+ at file{partial.log}, without touching @file{test-suite.log}.
+
+ at item
+You can set the @code{TEST_LOGS} variable. By default, this variable is
+computed at @command{make} run time from the value of @code{TESTS} as
+described above. For example, you can use the following:
+
+ at example
+set x subset*.log; shift
+env TEST_LOGS="foo.log $*" make -e check
+ at end example
+
+The comments made above about @code{TEST_SUITE_LOG} overriding applies
+here too.
+
+ at item
+ at vindex RECHECK_LOGS
+ at cindex lazy test execution
+By default, the test driver removes all old per-test log files before it
+starts running tests to regenerate them. The variable
+ at code{RECHECK_LOGS} contains the set of log files which are removed.
+ at code{RECHECK_LOGS} defaults to @code{TEST_LOGS}, which means all tests
+need to be rechecked. By overriding this variable, you can choose which
+tests need to be reconsidered. For example, you can lazily rerun only
+those tests which are outdated, i.e., older than their prerequisite test
+files, by setting this variable to the empty value:
+
+ at example
+env RECHECK_LOGS= make -e check
+ at end example
+
+ at item
+ at trindex recheck
+You can ensure that all tests are rerun which have failed or passed
+unexpectedly, by running @code{make recheck} in the test directory.
+This convenience target will set @code{RECHECK_LOGS} appropriately
+before invoking the main test driver.
+ at end itemize
+
+In order to guarantee an ordering between tests even with @code{make
+-j at var{N}}, dependencies between the corresponding log files may be
+specified through usual @command{make} dependencies. For example, the
+following snippet lets the test named @file{foo-execute.test} depend
+upon completion of the test @file{foo-compile.test}:
+
+ at example
+TESTS = foo-compile.test foo-execute.test
+foo-execute.log: foo-compile.log
+ at end example
+
+ at noindent
+Please note that this ordering ignores the @emph{results} of required
+tests, thus the test @file{foo-execute.test} is run even if the test
+ at file{foo-compile.test} failed or was skipped beforehand. Further,
+please note that specifying such dependencies currently works only for
+tests that end in one of the suffixes listed in @code{TEST_EXTENSIONS}.
+
+Tests without such specified dependencies may be run concurrently with
+parallel @command{make -j at var{N}}, so be sure they are prepared for
+concurrent execution.
+
+ at cindex Unit tests
+The combination of lazy test execution and correct dependencies between
+tests and their sources may be exploited for efficient unit testing
+during development. To further speed up the edit-compile-test cycle, it
+may even be useful to specify compiled programs in @code{EXTRA_PROGRAMS}
+instead of with @code{check_PROGRAMS}, as the former allows intertwined
+compilation and test execution (but note that @code{EXTRA_PROGRAMS} are
+not cleaned automatically, @pxref{Uniform}).
+
+The variables @code{TESTS} and @code{XFAIL_TESTS} may contain
+conditional parts as well as configure substitutions. In the latter
+case, however, certain restrictions apply: substituted test names
+must end with a nonempty test suffix like @file{.test}, so that one of
+the inference rules generated by @command{automake} can apply. For
+literal test names, @command{automake} can generate per-target rules
+to avoid this limitation.
+
+Please note that it is currently not possible to use @code{$(srcdir)/}
+or @code{$(top_srcdir)/} in the @code{TESTS} variable. This technical
+limitation is necessary to avoid generating test logs in the source tree
+and has the unfortunate consequence that it is not possible to specify
+distributed tests that are themselves generated by means of explicit
+rules, in a way that is portable to all @command{make} implementations
+(@pxref{Make Target Lookup,,, autoconf, The Autoconf Manual}, the
+semantics of FreeBSD and OpenBSD @command{make} conflict with this).
+In case of doubt you may want to require to use GNU @command{make},
+or work around the issue with inference rules to generate the tests.
+
+
+ at node DejaGnu Tests
+ at section DejaGnu Tests
+
+If @uref{ftp://ftp.gnu.org/gnu/dejagnu/, @command{dejagnu}} appears in
+ at code{AUTOMAKE_OPTIONS}, then a @command{dejagnu}-based test suite is
+assumed. The variable @code{DEJATOOL} is a list of names that are
+passed, one at a time, as the @option{--tool} argument to
+ at command{runtest} invocations; it defaults to the name of the package.
+
+The variable @code{RUNTESTDEFAULTFLAGS} holds the @option{--tool} and
+ at option{--srcdir} flags that are passed to dejagnu by default; this can be
+overridden if necessary.
+ at vindex RUNTESTDEFAULTFLAGS
+
+The variables @code{EXPECT} and @code{RUNTEST} can
+also be overridden to provide project-specific values. For instance,
+you will need to do this if you are testing a compiler toolchain,
+because the default values do not take into account host and target
+names.
+ at opindex dejagnu
+ at vindex DEJATOOL
+ at vindex EXPECT
+ at vindex RUNTEST
+
+The contents of the variable @code{RUNTESTFLAGS} are passed to the
+ at code{runtest} invocation. This is considered a ``user variable''
+(@pxref{User Variables}). If you need to set @command{runtest} flags in
+ at file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
+ at vindex RUNTESTFLAGS
+ at vindex AM_RUNTESTFLAGS
+
+ at cindex @file{site.exp}
+Automake will generate rules to create a local @file{site.exp} file,
+defining various variables detected by @command{configure}. This file
+is automatically read by DejaGnu. It is OK for the user of a package
+to edit this file in order to tune the test suite. However this is
+not the place where the test suite author should define new variables:
+this should be done elsewhere in the real test suite code.
+Especially, @file{site.exp} should not be distributed.
+
+Still, if the package author has legitimate reasons to extend
+ at file{site.exp} at @command{make} time, he can do so by defining
+the variable @code{EXTRA_DEJAGNU_SITE_CONFIG}; the files listed
+there will be considered @file{site.exp} prerequisites, and their
+content will be appended to it (in the same order in which they
+appear in @code{EXTRA_DEJAGNU_SITE_CONFIG}). Note that files are
+ at emph{not} distributed by default.
+
+For more information regarding DejaGnu test suites, see @ref{Top, , ,
+dejagnu, The DejaGnu Manual}.
+
+In either case, the testing is done via @samp{make check}.
+
+ at node Install Tests
+ at section Install Tests
+
+The @code{installcheck} target is available to the user as a way to
+run any tests after the package has been installed. You can add tests
+to this by writing an @code{installcheck-local} rule.
+
+
+ at node Rebuilding
+ at chapter Rebuilding Makefiles
+ at cindex rebuild rules
+
+Automake generates rules to automatically rebuild @file{Makefile}s,
+ at file{configure}, and other derived files like @file{Makefile.in}.
+
+ at acindex AM_MAINTAINER_MODE
+If you are using @code{AM_MAINTAINER_MODE} in @file{configure.ac}, then
+these automatic rebuilding rules are only enabled in maintainer mode.
+
+ at vindex ACLOCAL_AMFLAGS
+Sometimes you need to run @command{aclocal} with an argument like
+ at option{-I} to tell it where to find @file{.m4} files. Since
+sometimes @command{make} will automatically run @command{aclocal}, you
+need a way to specify these arguments. You can do this by defining
+ at code{ACLOCAL_AMFLAGS}; this holds arguments that are passed verbatim
+to @command{aclocal}. This variable is only useful in the top-level
+ at file{Makefile.am}.
+
+ at vindex CONFIG_STATUS_DEPENDENCIES
+ at vindex CONFIGURE_DEPENDENCIES
+ at cindex @file{version.sh}, example
+ at cindex @file{version.m4}, example
+
+Sometimes it is convenient to supplement the rebuild rules for
+ at file{configure} or @file{config.status} with additional dependencies.
+The variables @code{CONFIGURE_DEPENDENCIES} and
+ at code{CONFIG_STATUS_DEPENDENCIES} can be used to list these extra
+dependencies. These variables should be defined in all
+ at file{Makefile}s of the tree (because these two rebuild rules are
+output in all them), so it is safer and easier to @code{AC_SUBST} them
+from @file{configure.ac}. For instance, the following statement will
+cause @file{configure} to be rerun each time @file{version.sh} is
+changed.
+
+ at example
+AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh'])
+ at end example
+
+ at noindent
+Note the @samp{$(top_srcdir)/} in the file name. Since this variable
+is to be used in all @file{Makefile}s, its value must be sensible at
+any level in the build hierarchy.
+
+Beware not to mistake @code{CONFIGURE_DEPENDENCIES} for
+ at code{CONFIG_STATUS_DEPENDENCIES}.
+
+ at code{CONFIGURE_DEPENDENCIES} adds dependencies to the
+ at file{configure} rule, whose effect is to run @command{autoconf}. This
+variable should be seldom used, because @command{automake} already tracks
+ at code{m4_include}d files. However it can be useful when playing
+tricky games with @code{m4_esyscmd} or similar non-recommendable
+macros with side effects.
+
+ at code{CONFIG_STATUS_DEPENDENCIES} adds dependencies to the
+ at file{config.status} rule, whose effect is to run @file{configure}.
+This variable should therefore carry any non-standard source that may
+be read as a side effect of running @command{configure}, like @file{version.sh}
+in the example above.
+
+Speaking of @file{version.sh} scripts, we recommend against them
+today. They are mainly used when the version of a package is updated
+automatically by a script (e.g., in daily builds). Here is what some
+old-style @file{configure.ac}s may look like:
+
+ at example
+AC_INIT
+. $srcdir/version.sh
+AM_INIT_AUTOMAKE([name], $VERSION_NUMBER)
+ at dots{}
+ at end example
+
+ at noindent
+Here, @file{version.sh} is a shell fragment that sets
+ at code{VERSION_NUMBER}. The problem with this example is that
+ at command{automake} cannot track dependencies (listing @file{version.sh}
+in @command{CONFIG_STATUS_DEPENDENCIES}, and distributing this file is up
+to the user), and that it uses the obsolete form of @code{AC_INIT} and
+ at code{AM_INIT_AUTOMAKE}. Upgrading to the new syntax is not
+straightforward, because shell variables are not allowed in
+ at code{AC_INIT}'s arguments. We recommend that @file{version.sh} be
+replaced by an M4 file that is included by @file{configure.ac}:
+
+ at example
+m4_include([version.m4])
+AC_INIT([name], VERSION_NUMBER)
+AM_INIT_AUTOMAKE
+ at dots{}
+ at end example
+
+ at noindent
+Here @file{version.m4} could contain something like
+ at samp{m4_define([VERSION_NUMBER], [1.2])}. The advantage of this
+second form is that @command{automake} will take care of the
+dependencies when defining the rebuild rule, and will also distribute
+the file automatically. An inconvenience is that @command{autoconf}
+will now be rerun each time the version number is bumped, when only
+ at file{configure} had to be rerun in the previous setup.
+
+
+ at node Options
+ at chapter Changing Automake's Behavior
+
+Various features of Automake can be controlled by options. Except where
+noted otherwise, options can be specified in one of several ways: Most
+options can be applied on a per- at file{Makefile} basis when listed in a
+special @file{Makefile} variable named @code{AUTOMAKE_OPTIONS}. Some
+of these options only make sense when specified in the toplevel
+ at file{Makefile.am} file. Options are applied globally to all processed
+ at file{Makefile} files when listed in the first argument of
+ at code{AM_INIT_AUTOMAKE} in @file{configure.ac}, and some options which
+require changes to the @command{configure} script can only be specified
+there. These are annotated below.
+
+Currently understood options are:
+ at vindex AUTOMAKE_OPTIONS
+
+ at table @asis
+ at item @option{gnits}
+ at itemx @option{gnu}
+ at itemx @option{foreign}
+ at itemx @option{cygnus}
+ at cindex Option, @option{gnits}
+ at cindex Option, @option{gnu}
+ at cindex Option, @option{foreign}
+ at cindex Option, @option{cygnus}
+ at opindex gnits
+ at opindex gnu
+ at opindex foreign
+ at opindex cygnus
+
+Set the strictness as appropriate. The @option{gnits} option also
+implies options @option{readme-alpha} and @option{check-news}.
+
+ at item @option{ansi2knr}
+ at itemx @option{@var{path}/ansi2knr}
+ at cindex Option, @option{ansi2knr}
+ at opindex ansi2knr
+Turn on the deprecated de-ANSI-fication feature (@pxref{ANSI}). Note
+that that feature and this option @emph{will be removed} in the next
+major Automake release.
+
+If preceded by a
+path, the generated @file{Makefile.in} will look in the specified
+directory to find the @file{ansi2knr} program. The path should be a
+relative path to another directory in the same distribution (Automake
+does not check this).
+
+ at item @option{check-news}
+ at cindex Option, @option{check-news}
+ at opindex check-news
+Cause @samp{make dist} to fail unless the current version number appears
+in the first few lines of the @file{NEWS} file.
+
+ at item @option{color-tests}
+ at cindex Option, @option{color-tests}
+ at opindex color-tests
+Cause output of the simple test suite (@pxref{Simple Tests}) to be
+colorized on capable terminals.
+
+ at item @option{dejagnu}
+ at cindex Option, @option{dejagnu}
+ at opindex dejagnu
+Cause @command{dejagnu}-specific rules to be generated. @xref{DejaGnu Tests}.
+
+ at item @option{dist-bzip2}
+ at cindex Option, @option{dist-bzip2}
+ at opindex dist-bzip2
+Hook @code{dist-bzip2} to @code{dist}.
+ at trindex dist-bzip2
+
+ at item @option{dist-lzip}
+ at cindex Option, @option{dist-lzip}
+ at opindex dist-lzip
+Hook @code{dist-lzip} to @code{dist}.
+ at trindex dist-lzip
+
+ at item @option{dist-lzma}
+ at cindex Option, @option{dist-lzma}
+ at opindex dist-lzma
+Hook @code{dist-lzma} to @code{dist}. Obsoleted by @code{dist-xz}.
+ at trindex dist-lzma
+
+ at item @option{dist-shar}
+ at cindex Option, @option{dist-shar}
+ at opindex dist-shar
+Hook @code{dist-shar} to @code{dist}.
+ at trindex dist-shar
+
+ at item @option{dist-zip}
+ at cindex Option, @option{dist-zip}
+ at opindex dist-zip
+Hook @code{dist-zip} to @code{dist}.
+ at trindex dist-zip
+
+ at item @option{dist-tarZ}
+ at cindex Option, @option{dist-tarZ}
+ at opindex dist-tarZ
+Hook @code{dist-tarZ} to @code{dist}.
+ at trindex dist-tarZ
+
+ at item @option{filename-length-max=99}
+ at cindex Option, @option{filename-length-max=99}
+ at opindex filename-length-max=99
+Abort if file names longer than 99 characters are found during
+ at samp{make dist}. Such long file names are generally considered not to
+be portable in tarballs. See the @option{tar-v7} and @option{tar-ustar}
+options below. This option should be used in the top-level
+ at file{Makefile.am} or as an argument of @code{AM_INIT_AUTOMAKE} in
+ at file{configure.ac}, it will be ignored otherwise. It will also be
+ignored in sub-packages of nested packages (@pxref{Subpackages}).
+
+ at item @option{no-define}
+ at cindex Option, @option{no-define}
+ at opindex no-define
+This option is meaningful only when passed as an argument to
+ at code{AM_INIT_AUTOMAKE}. It will prevent the @code{PACKAGE} and
+ at code{VERSION} variables from being @code{AC_DEFINE}d.
+
+ at item @option{no-dependencies}
+ at cindex Option, @option{no-dependencies}
+ at opindex no-dependencies
+This is similar to using @option{--ignore-deps} on the command line,
+but is useful for those situations where you don't have the necessary
+bits to make automatic dependency tracking work
+(@pxref{Dependencies}). In this case the effect is to effectively
+disable automatic dependency tracking.
+
+ at item @option{no-dist}
+ at cindex Option, @option{no-dist}
+ at opindex no-dist
+Don't emit any code related to @code{dist} target. This is useful
+when a package has its own method for making distributions.
+
+ at item @option{no-dist-gzip}
+ at cindex Option, @option{no-dist-gzip}
+ at opindex no-dist-gzip
+Do not hook @code{dist-gzip} to @code{dist}.
+ at trindex no-dist-gzip
+
+ at item @option{no-exeext}
+ at cindex Option, @option{no-exeext}
+ at opindex no-exeext
+If your @file{Makefile.am} defines a rule for target @code{foo}, it
+will override a rule for a target named @samp{foo$(EXEEXT)}. This is
+necessary when @code{EXEEXT} is found to be empty. However, by
+default @command{automake} will generate an error for this use. The
+ at option{no-exeext} option will disable this error. This is intended for
+use only where it is known in advance that the package will not be
+ported to Windows, or any other operating system using extensions on
+executables.
+
+ at item @option{no-installinfo}
+ at cindex Option, @option{no-installinfo}
+ at opindex no-installinfo
+The generated @file{Makefile.in} will not cause info pages to be built
+or installed by default. However, @code{info} and @code{install-info}
+targets will still be available. This option is disallowed at
+ at option{gnu} strictness and above.
+ at trindex info
+ at trindex install-info
+
+ at item @option{no-installman}
+ at cindex Option, @option{no-installman}
+ at opindex no-installman
+The generated @file{Makefile.in} will not cause man pages to be
+installed by default. However, an @code{install-man} target will still
+be available for optional installation. This option is disallowed at
+ at option{gnu} strictness and above.
+ at trindex install-man
+
+ at item @option{nostdinc}
+ at cindex Option, @option{nostdinc}
+ at opindex nostdinc
+This option can be used to disable the standard @option{-I} options that
+are ordinarily automatically provided by Automake.
+
+ at item @option{no-texinfo.tex}
+ at cindex Option, @option{no-texinfo.tex}
+ at opindex no-texinfo.tex
+Don't require @file{texinfo.tex}, even if there are texinfo files in
+this directory.
+
+ at item @option{parallel-tests}
+ at cindex Option, @option{parallel-tests}
+ at opindex parallel-tests
+Enable test suite driver for @code{TESTS} that can run tests in parallel
+(@pxref{Simple Tests using parallel-tests}, for more information).
+
+ at item @option{readme-alpha}
+ at cindex Option, @option{readme-alpha}
+ at opindex readme-alpha
+If this release is an alpha release, and the file @file{README-alpha}
+exists, then it will be added to the distribution. If this option is
+given, version numbers are expected to follow one of two forms. The
+first form is @samp{@var{major}. at var{minor}. at var{alpha}}, where each
+element is a number; the final period and number should be left off for
+non-alpha releases. The second form is
+ at samp{@var{major}. at var{minor}@var{alpha}}, where @var{alpha} is a
+letter; it should be omitted for non-alpha releases.
+
+ at item @option{silent-rules}
+ at cindex Option, @option{silent-rules}
+ at opindex silent-rules
+Enable less verbose build rules. This can be used to let build rules
+output status lines of the form:
+ at example
+GEN @var{output-file}
+ CC @var{object-file}
+ at end example
+ at noindent
+instead of printing the command that will be executed to update
+ at var{output-file} or to compile @var{object-file}. It can also
+silence @command{libtool} output.
+
+For more information about how to use, enable, or disable silent
+rules, @pxref{Automake silent-rules Option}.
+
+ at item @option{std-options}
+ at cindex Options, @option{std-options}
+ at cindex @samp{make installcheck}, testing @option{--help} and @option{--version}
+ at cindex @option{--help} check
+ at cindex @option{--version} check
+ at opindex std-options
+
+Make the @code{installcheck} rule check that installed scripts and
+programs support the @option{--help} and @option{--version} options.
+This also provides a basic check that the program's
+run-time dependencies are satisfied after installation.
+
+ at vindex AM_INSTALLCHECK_STD_OPTIONS_EXEMPT
+In a few situations, programs (or scripts) have to be exempted from this
+test. For instance, @command{false} (from GNU coreutils) is never
+successful, even for @option{--help} or @option{--version}. You can list
+such programs in the variable @code{AM_INSTALLCHECK_STD_OPTIONS_EXEMPT}.
+Programs (not scripts) listed in this variable should be suffixed by
+ at samp{$(EXEEXT)} for the sake of Win32 or OS/2. For instance, suppose we
+build @file{false} as a program but @file{true.sh} as a script, and that
+neither of them support @option{--help} or @option{--version}:
+
+ at example
+AUTOMAKE_OPTIONS = std-options
+bin_PROGRAMS = false ...
+bin_SCRIPTS = true.sh ...
+AM_INSTALLCHECK_STD_OPTIONS_EXEMPT = false$(EXEEXT) true.sh
+ at end example
+
+ at item @option{subdir-objects}
+ at cindex Options, @option{subdir-objects}
+ at opindex subdir-objects
+If this option is specified, then objects are placed into the
+subdirectory of the build directory corresponding to the subdirectory of
+the source file. For instance, if the source file is
+ at file{subdir/file.cxx}, then the output file would be
+ at file{subdir/file.o}.
+
+In order to use this option with C sources, you should add
+ at code{AM_PROG_CC_C_O} to @file{configure.ac}.
+
+ at anchor{tar-formats}
+ at item @option{tar-v7}
+ at itemx @option{tar-ustar}
+ at itemx @option{tar-pax}
+ at cindex Option, @option{tar-v7}
+ at cindex Option, @option{tar-ustar}
+ at cindex Option, @option{tar-pax}
+ at cindex @command{tar} formats
+ at cindex v7 @command{tar} format
+ at cindex ustar format
+ at cindex pax format
+ at opindex tar-v7
+ at opindex tar-ustar
+ at opindex tar-pax
+
+These three mutually exclusive options select the tar format to use
+when generating tarballs with @samp{make dist}. (The tar file created
+is then compressed according to the set of @option{no-dist-gzip},
+ at option{dist-bzip2}, @option{dist-lzip}, @option{dist-xz} and
+ at option{dist-tarZ} options in use.)
+
+These options must be passed as arguments to @code{AM_INIT_AUTOMAKE}
+(@pxref{Macros}) because they can require additional configure checks.
+Automake will complain if it sees such options in an
+ at code{AUTOMAKE_OPTIONS} variable.
+
+ at option{tar-v7} selects the old V7 tar format. This is the historical
+default. This antiquated format is understood by all tar
+implementations and supports file names with up to 99 characters. When
+given longer file names some tar implementations will diagnose the
+problem while other will generate broken tarballs or use non-portable
+extensions. Furthermore, the V7 format cannot store empty
+directories. When using this format, consider using the
+ at option{filename-length-max=99} option to catch file names too long.
+
+ at option{tar-ustar} selects the ustar format defined by POSIX
+1003.1-1988. This format is believed to be old enough to be portable.
+It fully supports empty directories. It can store file names with up
+to 256 characters, provided that the file name can be split at
+directory separator in two parts, first of them being at most 155
+bytes long. So, in most cases the maximum file name length will be
+shorter than 256 characters. However you may run against broken tar
+implementations that incorrectly handle file names longer than 99
+characters (please report them to @email{@value{PACKAGE_BUGREPORT}} so we
+can document this accurately).
+
+ at option{tar-pax} selects the new pax interchange format defined by POSIX
+1003.1-2001. It does not limit the length of file names. However,
+this format is very young and should probably be restricted to
+packages that target only very modern platforms. There are moves to
+change the pax format in an upward-compatible way, so this option may
+refer to a more recent version in the future.
+
+ at xref{Formats, , Controlling the Archive Format, tar, GNU Tar}, for
+further discussion about tar formats.
+
+ at command{configure} knows several ways to construct these formats. It
+will not abort if it cannot find a tool up to the task (so that the
+package can still be built), but @samp{make dist} will fail.
+
+ at item @var{version}
+ at cindex Option, @var{version}
+A version number (e.g., @samp{0.30}) can be specified. If Automake is not
+newer than the version specified, creation of the @file{Makefile.in}
+will be suppressed.
+
+ at item @option{-W at var{category}} or @option{--warnings=@var{category}}
+ at cindex Option, warnings
+ at cindex Option, @option{-W at var{category}}
+ at cindex Option, @option{--warnings=@var{category}}
+These options behave exactly like their command-line counterpart
+(@pxref{automake Invocation}). This allows you to enable or disable some
+warning categories on a per-file basis. You can also setup some warnings
+for your entire project; for instance, try @samp{AM_INIT_AUTOMAKE([-Wall])}
+in your @file{configure.ac}.
+
+ at end table
+
+Unrecognized options are diagnosed by @command{automake}.
+
+If you want an option to apply to all the files in the tree, you can use
+the @code{AM_INIT_AUTOMAKE} macro in @file{configure.ac}.
+ at xref{Macros}.
+
+
+ at node Miscellaneous
+ at chapter Miscellaneous Rules
+
+There are a few rules and variables that didn't fit anywhere else.
+
+ at menu
+* Tags:: Interfacing to etags and mkid
+* Suffixes:: Handling new file extensions
+* Multilibs:: Support for multilibs (deprecated, soon to be removed).
+ at end menu
+
+
+ at node Tags
+ at section Interfacing to @command{etags}
+
+ at cindex @file{TAGS} support
+
+Automake will generate rules to generate @file{TAGS} files for use with
+GNU Emacs under some circumstances.
+
+ at trindex tags
+If any C, C++ or Fortran 77 source code or headers are present, then
+ at code{tags} and @code{TAGS} rules will be generated for the directory.
+All files listed using the @code{_SOURCES}, @code{_HEADERS}, and
+ at code{_LISP} primaries will be used to generate tags. Note that
+generated source files that are not distributed must be declared in
+variables like @code{nodist_noinst_HEADERS} or
+ at code{nodist_ at var{prog}_SOURCES} or they will be ignored.
+
+A @code{tags} rule will be output at the topmost directory of a
+multi-directory package. When run from this topmost directory,
+ at samp{make tags} will generate a @file{TAGS} file that includes by
+reference all @file{TAGS} files from subdirectories.
+
+The @code{tags} rule will also be generated if the variable
+ at code{ETAGS_ARGS} is defined. This variable is intended for use in
+directories that contain taggable source that @command{etags} does
+not understand. The user can use the @code{ETAGSFLAGS} to pass
+additional flags to @command{etags}; @code{AM_ETAGSFLAGS} is also
+available for use in @file{Makefile.am}.
+ at vindex ETAGS_ARGS
+ at vindex ETAGSFLAGS
+ at vindex AM_ETAGSFLAGS
+
+Here is how Automake generates tags for its source, and for nodes in its
+Texinfo file:
+
+ at example
+ETAGS_ARGS = automake.in --lang=none \
+ --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
+ at end example
+
+If you add file names to @code{ETAGS_ARGS}, you will probably also
+want to define @code{TAGS_DEPENDENCIES}. The contents of this variable
+are added directly to the dependencies for the @code{tags} rule.
+ at vindex TAGS_DEPENDENCIES
+
+Automake also generates a @code{ctags} rule that can be used to
+build @command{vi}-style @file{tags} files. The variable @code{CTAGS}
+is the name of the program to invoke (by default @command{ctags});
+ at code{CTAGSFLAGS} can be used by the user to pass additional flags,
+and @code{AM_CTAGSFLAGS} can be used by the @file{Makefile.am}.
+
+Automake will also generate an @code{ID} rule that will run
+ at command{mkid} on the source. This is only supported on a
+directory-by-directory basis.
+ at trindex id
+
+Finally, Automake also emits rules to support the
+ at uref{http://www.gnu.org/software/global/, GNU Global Tags program}.
+The @code{GTAGS} rule runs Global Tags and puts the
+result in the top build directory. The variable @code{GTAGS_ARGS}
+holds arguments that are passed to @command{gtags}.
+ at vindex GTAGS_ARGS
+
+
+ at node Suffixes
+ at section Handling new file extensions
+
+ at cindex Adding new @code{SUFFIXES}
+ at cindex @code{SUFFIXES}, adding
+ at vindex SUFFIXES
+
+It is sometimes useful to introduce a new implicit rule to handle a file
+type that Automake does not know about.
+
+For instance, suppose you had a compiler that could compile @file{.foo}
+files to @file{.o} files. You would simply define a suffix rule for
+your language:
+
+ at example
+.foo.o:
+ foocc -c -o $@@ $<
+ at end example
+
+Then you could directly use a @file{.foo} file in a @code{_SOURCES}
+variable and expect the correct results:
+
+ at example
+bin_PROGRAMS = doit
+doit_SOURCES = doit.foo
+ at end example
+
+This was the simpler and more common case. In other cases, you will
+have to help Automake to figure out which extensions you are defining your
+suffix rule for. This usually happens when your extension does not
+start with a dot. Then, all you have to do is to put a list of new
+suffixes in the @code{SUFFIXES} variable @strong{before} you define your
+implicit rule.
+
+For instance, the following definition prevents Automake from misinterpreting
+the @samp{.idlC.cpp:} rule as an attempt to transform @file{.idlC} files into
+ at file{.cpp} files.
+
+ at c Keep in sync with suffix7.test.
+ at example
+SUFFIXES = .idl C.cpp
+.idlC.cpp:
+ # whatever
+ at end example
+
+As you may have noted, the @code{SUFFIXES} variable behaves like the
+ at code{.SUFFIXES} special target of @command{make}. You should not touch
+ at code{.SUFFIXES} yourself, but use @code{SUFFIXES} instead and let
+Automake generate the suffix list for @code{.SUFFIXES}. Any given
+ at code{SUFFIXES} go at the start of the generated suffixes list, followed
+by Automake generated suffixes not already in the list.
+
+ at node Multilibs
+ at section Support for Multilibs (deprecated, soon to be removed).
+
+Automake used to support an obscure feature called multilibs. @emph{This
+feature is now deprecated, and will be removed in the next major Automake
+version}. Still, its implementation will remain available in the
+ at file{contrib/} directory of the Automake distribution, so it should be
+very easy for motivated users to continue to use it in their projects,
+if they really need to.
+
+A @dfn{multilib} is a library that is built for multiple different ABIs
+at a single time; each time the library is built with a different target
+flag combination. This is only useful when the library is intended to
+be cross-compiled, and it is almost exclusively used for compiler
+support libraries.
+
+ at node Include
+ at chapter Include
+
+ at cmindex include
+ at cindex Including @file{Makefile} fragment
+ at cindex @file{Makefile} fragment, including
+
+Automake supports an @code{include} directive that can be used to
+include other @file{Makefile} fragments when @command{automake} is run.
+Note that these fragments are read and interpreted by @command{automake},
+not by @command{make}. As with conditionals, @command{make} has no idea that
+ at code{include} is in use.
+
+There are two forms of @code{include}:
+
+ at table @code
+ at item include $(srcdir)/file
+Include a fragment that is found relative to the current source
+directory.
+
+ at item include $(top_srcdir)/file
+Include a fragment that is found relative to the top source directory.
+ at end table
+
+Note that if a fragment is included inside a conditional, then the
+condition applies to the entire contents of that fragment.
+
+Makefile fragments included this way are always distributed because
+they are needed to rebuild @file{Makefile.in}.
+
+ at node Conditionals
+ at chapter Conditionals
+
+ at cindex Conditionals
+
+Automake supports a simple type of conditionals.
+
+These conditionals are not the same as conditionals in
+GNU Make. Automake conditionals are checked at configure time by the
+ at file{configure} script, and affect the translation from
+ at file{Makefile.in} to @file{Makefile}. They are based on options passed
+to @file{configure} and on results that @file{configure} has discovered
+about the host system. GNU Make conditionals are checked at @command{make}
+time, and are based on variables passed to the make program or defined
+in the @file{Makefile}.
+
+Automake conditionals will work with any make program.
+
+ at menu
+* Usage of Conditionals:: Declaring conditional content
+* Limits of Conditionals:: Enclosing complete statements
+ at end menu
+
+ at node Usage of Conditionals
+ at section Usage of Conditionals
+
+ at acindex AM_CONDITIONAL
+Before using a conditional, you must define it by using
+ at code{AM_CONDITIONAL} in the @file{configure.ac} file (@pxref{Macros}).
+
+ at defmac AM_CONDITIONAL (@var{conditional}, @var{condition})
+The conditional name, @var{conditional}, should be a simple string
+starting with a letter and containing only letters, digits, and
+underscores. It must be different from @samp{TRUE} and @samp{FALSE}
+that are reserved by Automake.
+
+The shell @var{condition} (suitable for use in a shell @code{if}
+statement) is evaluated when @command{configure} is run. Note that you
+must arrange for @emph{every} @code{AM_CONDITIONAL} to be invoked every
+time @command{configure} is run. If @code{AM_CONDITIONAL} is run
+conditionally (e.g., in a shell @code{if} statement), then the result
+will confuse @command{automake}.
+ at end defmac
+
+ at cindex @option{--enable-debug}, example
+ at cindex Example conditional @option{--enable-debug}
+ at cindex Conditional example, @option{--enable-debug}
+
+Conditionals typically depend upon options that the user provides to
+the @command{configure} script. Here is an example of how to write a
+conditional that is true if the user uses the @option{--enable-debug}
+option.
+
+ at example
+AC_ARG_ENABLE([debug],
+[ --enable-debug Turn on debugging],
+[case "$@{enableval@}" in
+ yes) debug=true ;;
+ no) debug=false ;;
+ *) AC_MSG_ERROR([bad value $@{enableval@} for --enable-debug]) ;;
+esac],[debug=false])
+AM_CONDITIONAL([DEBUG], [test x$debug = xtrue])
+ at end example
+
+Here is an example of how to use that conditional in @file{Makefile.am}:
+
+ at cmindex if
+ at cmindex endif
+ at cmindex else
+
+ at example
+if DEBUG
+DBG = debug
+else
+DBG =
+endif
+noinst_PROGRAMS = $(DBG)
+ at end example
+
+This trivial example could also be handled using @code{EXTRA_PROGRAMS}
+(@pxref{Conditional Programs}).
+
+You may only test a single variable in an @code{if} statement, possibly
+negated using @samp{!}. The @code{else} statement may be omitted.
+Conditionals may be nested to any depth. You may specify an argument to
+ at code{else} in which case it must be the negation of the condition used
+for the current @code{if}. Similarly you may specify the condition
+that is closed on the @code{endif} line:
+
+ at example
+if DEBUG
+DBG = debug
+else !DEBUG
+DBG =
+endif !DEBUG
+ at end example
+
+ at noindent
+Unbalanced conditions are errors. The @code{if}, @code{else}, and
+ at code{endif} statements should not be indented, i.e., start on column
+one.
+
+The @code{else} branch of the above two examples could be omitted,
+since assigning the empty string to an otherwise undefined variable
+makes no difference.
+
+ at acindex AM_COND_IF
+In order to allow access to the condition registered by
+ at code{AM_CONDITIONAL} inside @file{configure.ac}, and to allow
+conditional @code{AC_CONFIG_FILES}, @code{AM_COND_IF} may be used:
+
+ at defmac AM_COND_IF (@var{conditional}, @ovar{if-true}, @ovar{if-false})
+If @var{conditional} is fulfilled, execute @var{if-true}, otherwise
+execute @var{if-false}. If either branch contains @code{AC_CONFIG_FILES},
+it will cause @command{automake} to output the rules for the respective
+files only for the given condition.
+ at end defmac
+
+ at code{AM_COND_IF} macros may be nested when m4 quotation is used
+properly (@pxref{M4 Quotation, ,, autoconf, The Autoconf Manual}).
+
+ at cindex Example conditional @code{AC_CONFIG_FILES}
+ at cindex @code{AC_CONFIG_FILES}, conditional
+
+Here is an example of how to define a conditional config file:
+
+ at example
+AM_CONDITIONAL([SHELL_WRAPPER], [test "x$with_wrapper" = xtrue])
+AM_COND_IF([SHELL_WRAPPER],
+ [AC_CONFIG_FILES([wrapper:wrapper.in])])
+ at end example
+
+ at node Limits of Conditionals
+ at section Limits of Conditionals
+
+Conditionals should enclose complete statements like variables or
+rules definitions. Automake cannot deal with conditionals used inside
+a variable definition, for instance, and is not even able to diagnose
+this situation. The following example would not work:
+
+ at example
+# This syntax is not understood by Automake
+AM_CPPFLAGS = \
+ -DFEATURE_A \
+if WANT_DEBUG
+ -DDEBUG \
+endif
+ -DFEATURE_B
+ at end example
+
+However the intended definition of @code{AM_CPPFLAGS} can be achieved
+with
+
+ at example
+if WANT_DEBUG
+ DEBUGFLAGS = -DDEBUG
+endif
+AM_CPPFLAGS = -DFEATURE_A $(DEBUGFLAGS) -DFEATURE_B
+ at end example
+
+ at noindent
+or
+
+ at example
+AM_CPPFLAGS = -DFEATURE_A
+if WANT_DEBUG
+AM_CPPFLAGS += -DDEBUG
+endif
+AM_CPPFLAGS += -DFEATURE_B
+ at end example
+
+More details and examples of conditionals are described alongside
+various Automake features in this manual (@pxref{Conditional
+Subdirectories}, @pxref{Conditional Sources}, @pxref{Conditional
+Programs}, @pxref{Conditional Libtool Libraries}, @pxref{Conditional
+Libtool Sources}).
+
+ at node Silencing Make
+ at chapter Silencing @command{make}
+
+ at cindex Silent @command{make}
+ at cindex Silencing @command{make}
+ at cindex Silent rules
+ at cindex Silent @command{make} rules
+
+ at menu
+* Make verbosity:: Make is verbose by default
+* Tricks For Silencing Make:: Standard and generic ways to silence make
+* Automake silent-rules Option:: How Automake can help in silencing make
+ at end menu
+
+ at node Make verbosity
+ at section Make is verbose by default
+
+Normally, when executing the set of rules associated with a target,
+ at command{make} prints each rule before it is executed. This behaviour,
+while having been in place for a long time, and being even mandated by
+the POSIX standard, starkly violates the ``silence is golden'' UNIX
+principle at footnote{See also
+ at uref{http://catb.org/~esr/writings/taoup/html/ch11s09.html}.}:
+
+ at quotation
+When a program has nothing interesting or surprising to say, it should
+say nothing. Well-behaved Unix programs do their jobs unobtrusively,
+with a minimum of fuss and bother. Silence is golden.
+ at end quotation
+
+In fact, while such verbosity of @command{make} can theoretically be
+useful to track bugs and understand reasons of failures right away, it
+can also hide warning and error messages from @command{make}-invoked
+tools, drowning them in a flood of uninteresting and seldom useful
+messages, and thus allowing them to go easily undetected.
+
+This problem can be very annoying, especially for developers, who usually
+know quite well what's going on behind the scenes, and for whom the
+verbose output from @command{make} ends up being mostly noise that hampers
+the easy detection of potentially important warning messages.
+
+ at node Tricks For Silencing Make
+ at section Standard and generic ways to silence make
+
+Here we describe some common idioms/tricks to obtain a quieter make
+output, with their relative advantages and drawbacks. In the next
+section (@ref{Automake silent-rules Option}) we'll see how Automake
+can help in this respect.
+
+ at itemize @bullet
+
+ at item @command{make -s}
+
+This simply causes @command{make} not to print @emph{any} rule before
+executing it.
+
+The @option{-s} flag is mandated by POSIX, universally supported, and
+its purpose and function are easy to understand.
+
+But it also has its serious limitations too. First of all, it embodies
+an ``all or nothing'' strategy, i.e., either everything is silenced, or
+nothing is; this lack of granularity can sometimes be a fatal flaw.
+Moreover, when the @option{-s} flag is used, the @command{make} output
+might turn out to be too much terse; in case of errors, the user won't
+be able to easily see what rule or command have caused them, or even,
+in case of tools with poor error reporting, what the errors were!
+
+ at item @command{make >/dev/null || make}
+
+Apparently, this perfectly obeys the ``silence is golden'' rule: warnings
+from stderr are passed through, output reporting is done only in case of
+error, and in that case it should provide a verbose-enough report to allow
+an easy determination of the error location and causes.
+
+However, calling @command{make} two times in a row might hide errors
+(especially intermittent ones), or subtly change the expected semantic
+of the @command{make} calls --- things these which can clearly make
+debugging and error assessment very difficult.
+
+ at item @command{make --no-print-directory}
+
+This is GNU @command{make} specific. When called with the
+ at option{--no-print-directory} option, GNU @command{make} will disable
+printing of the working directory by invoked sub- at command{make}s (the
+well-known ``@i{Entering/Leaving directory ...}'' messages). This helps
+to decrease the verbosity of the output, but experience has shown that
+it can also often render debugging considerably harder in projects using
+deeply-nested @command{make} recursion.
+
+As an aside, notice that the @option{--no-print-directory} option is
+automatically activated if the @option{-s} flag is used.
+
+ at c TODO: Other tricks?
+ at c TODO: Maybe speak about the @code{.SILENT} target?
+ at c TODO: - Pros: More granularity on what to silence.
+ at c TODO: - Cons: No easy way to temporarily override.
+
+ at end itemize
+
+ at node Automake silent-rules Option
+ at section How Automake can help in silencing make
+
+The tricks and idioms for silencing @command{make} described in the
+previous section can be useful from time to time, but we've seen that
+they all have their serious drawbacks and limitations. That's why
+automake provides support for a more advanced and flexible way of
+obtaining quieter output from @command{make}: the @option{silent-rules}
+mode.
+
+ at c TODO: Maybe describe in brief the precedent set by the build system
+ at c of the Linux Kernel, from which Automake took inspiration ... Links?
+
+To give the gist of what @option{silent-rules} can do, here is a simple
+comparison between a typical @command{make} output (where silent rules
+are disabled) and one with silent rules enabled:
+
+ at example
+% @kbd{cat Makefile.am}
+bin_PROGRAMS = foo
+foo_SOURCES = main.c func.c
+% @kbd{cat main.c}
+int main (void) @{ return func (); @} /* func used undeclared */
+% @kbd{cat func.c}
+int func (void) @{ int i; return i; @} /* i used uninitialized */
+
+ at i{The make output is by default very verbose. This causes warnings
+from the compiler to be somewhat hidden, and not immediate to spot.}
+% @kbd{make CFLAGS=-Wall}
+gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ...
+-DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ...
+-DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT main.o
+-MD -MP -MF .deps/main.Tpo -c -o main.o main.c
+main.c: In function ‘main’:
+main.c:3:3: warning: implicit declaration of function ‘func’
+mv -f .deps/main.Tpo .deps/main.Po
+gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ...
+-DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ...
+-DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT func.o
+-MD -MP -MF .deps/func.Tpo -c -o func.o func.c
+func.c: In function ‘func’:
+func.c:4:3: warning: ‘i’ used uninitialized in this function
+mv -f .deps/func.Tpo .deps/func.Po
+gcc -Wall -o foo main.o func.o
+
+ at i{Clean up, so that we we can rebuild everything from scratch.}
+% @kbd{make clean}
+test -z "foo" || rm -f foo
+rm -f *.o
+
+ at i{Silent rules enabled: the output is minimal but informative. In
+particular, the warnings from the compiler stick out very clearly.}
+% @kbd{make V=0 CFLAGS=-Wall}
+ CC main.o
+main.c: In function ‘main’:
+main.c:3:3: warning: implicit declaration of function ‘func’
+ CC func.o
+func.c: In function ‘func’:
+func.c:4:3: warning: ‘i’ used uninitialized in this function
+ CCLD foo
+ at end example
+
+ at cindex silent-rules and libtool
+Also, in projects using @command{libtool}, the use of silent rules can
+automatically enable the @command{libtool}'s @option{--silent} option:
+
+ at example
+% @kbd{cat Makefile.am}
+lib_LTLIBRARIES = libx.la
+
+% @kbd{make # Both make and libtool are verbose by default.}
+...
+libtool: compile: gcc -DPACKAGE_NAME=\"foo\" ... -DLT_OBJDIR=\".libs/\"
+ -I. -g -O2 -MT libx.lo -MD -MP -MF .deps/libx.Tpo -c libx.c -fPIC
+ -DPIC -o .libs/libx.o
+mv -f .deps/libx.Tpo .deps/libx.Plo
+/bin/sh ./libtool --tag=CC --mode=link gcc -g -O2 -o libx.la -rpath
+ /usr/local/lib libx.lo
+libtool: link: gcc -shared .libs/libx.o -Wl,-soname -Wl,libx.so.0
+ -o .libs/libx.so.0.0.0
+libtool: link: cd .libs && rm -f libx.so && ln -s libx.so.0.0.0 libx.so
+...
+
+% @kbd{make V=0}
+ CC libx.lo
+ CCLD libx.la
+ at end example
+
+Let's now see how the @option{silent-rules} mode interfaces with the
+package developer and the package user.
+
+To enable the use of @option{silent-rules} in his package, a developer
+needs to do either of the following:
+
+ at itemize @bullet
+ at item
+Add the @option{silent-rules} option as argument to @code{AM_INIT_AUTOMAKE}.
+ at item
+Call the @code{AM_SILENT_RULES} macro from within the @file{configure.ac}
+file.
+ at end itemize
+
+It is not possible to instead specify @option{silent-rules} in a
+ at file{Makefile.am} file.
+
+If the developer has done either of the above, then the user of the
+package may influence the verbosity at @command{configure} run time as
+well as at @command{make} run time:
+
+ at itemize @bullet
+ at item
+ at opindex --enable-silent-rules
+ at opindex --disable-silent-rules
+Passing @option{--enable-silent-rules} to @command{configure} will cause
+build rules to be less verbose; the option @option{--disable-silent-rules}
+will cause normal verbose output.
+ at item
+ at vindex @code{V}
+At @command{make} run time, the default chosen at @command{configure}
+time may be overridden: @code{make V=1} will produce verbose output,
+ at code{make V=0} less verbose output.
+ at end itemize
+
+ at cindex default verbosity for silent-rules
+Note that silent rules are @emph{disabled} by default; the user must
+enable them explicitly at either @command{configure} run time or at
+ at command{make} run time. We think that this is a good policy, since
+it provides the casual user with enough information to prepare a good
+bug report in case anything breaks.
+
+Still, notwithstanding the rationales above, a developer who wants to
+make silent rules enabled by default in his own package can do so by
+adding a @samp{yes} argument to the @code{AM_SILENT_RULES} call in
+ at file{configure.ac}. We advise against this approach, though.
+
+ at c Keep in sync with silent-configsite.test
+Users who prefer to have silent rules enabled by default can edit their
+ at file{config.site} file to make the variable @code{enable_silent_rules}
+default to @samp{yes}. This should still allow disabling silent rules
+at @command{configure} time and at @command{make} time.
+
+ at c FIXME: there's really a need to specify this explicitly?
+For portability to different @command{make} implementations, package authors
+are advised to not set the variable @code{V} inside the @file{Makefile.am}
+file, to allow the user to override the value for subdirectories as well.
+
+The current implementation of this feature normally uses nested
+variable expansion @samp{$(@var{var1}$(V))}, a @file{Makefile} feature
+that is not required by POSIX 2008 but is widely supported in
+practice. The @option{silent-rules} option thus turns off warnings
+about recursive variable expansion, which are in turn enabled by
+ at option{-Wportability} (@pxref{automake Invocation}). On the rare
+ at command{make} implementations that do not support nested variable
+expansion, whether rules are silent is always determined at configure
+time, and cannot be overridden at make time. Future versions of POSIX
+are likely to require nested variable expansion, so this minor
+limitation should go away with time.
+
+ at vindex @code{AM_V_GEN}
+ at vindex @code{AM_V_at}
+ at vindex @code{AM_DEFAULT_VERBOSITY}
+ at vindex @code{AM_V}
+ at vindex @code{AM_DEFAULT_V}
+To extend the silent mode to your own rules, you have two choices:
+
+ at itemize @bullet
+ at item
+You can use the predefined variable @code{AM_V_GEN} as a prefix to
+commands that should output a status line in silent mode, and
+ at code{AM_V_at} as a prefix to commands that should not output anything
+in silent mode. When output is to be verbose, both of these variables
+will expand to the empty string.
+ at item
+You can add your own variables, so strings of your own choice are shown.
+The following snippet shows how you would define your own equivalent of
+ at code{AM_V_GEN}:
+
+ at example
+pkg_verbose = $(pkg_verbose_@@AM_V@@)
+pkg_verbose_ = $(pkg_verbose_@@AM_DEFAULT_V@@)
+pkg_verbose_0 = @@echo PKG-GEN $@@;
+
+foo: foo.in
+ $(pkg_verbose)cp $(srcdir)/foo.in $@@
+ at end example
+
+ at end itemize
+
+As a final note, observe that, even when silent rules are enabled,
+the @option{--no-print-directory} option is still required with GNU
+ at command{make} if the ``@i{Entering/Leaving directory ...}'' messages
+are to be disabled.
+
+ at node Gnits
+ at chapter The effect of @option{--gnu} and @option{--gnits}
+
+ at cindex @option{--gnu}, required files
+ at cindex @option{--gnu}, complete description
+
+The @option{--gnu} option (or @option{gnu} in the
+ at code{AUTOMAKE_OPTIONS} variable) causes @command{automake} to check
+the following:
+
+ at itemize @bullet
+ at item
+The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{AUTHORS},
+and @file{ChangeLog}, plus one of @file{COPYING.LIB}, @file{COPYING.LESSER}
+or @file{COPYING}, are required at the topmost directory of the package.
+
+If the @option{--add-missing} option is given, @command{automake} will
+add a generic version of the @file{INSTALL} file as well as the
+ at file{COPYING} file containing the text of the current version of the
+GNU General Public License existing at the time of this Automake release
+(version 3 as this is written, @uref{http://www.gnu.org/@/copyleft/@/gpl.html}).
+However, an existing @file{COPYING} file will never be overwritten by
+ at command{automake}.
+
+ at item
+The options @option{no-installman} and @option{no-installinfo} are
+prohibited.
+ at end itemize
+
+Note that this option will be extended in the future to do even more
+checking; it is advisable to be familiar with the precise requirements
+of the GNU standards. Also, @option{--gnu} can require certain
+non-standard GNU programs to exist for use by various maintainer-only
+rules; for instance, in the future @command{pathchk} might be required for
+ at samp{make dist}.
+
+ at cindex @option{--gnits}, complete description
+
+The @option{--gnits} option does everything that @option{--gnu} does, and
+checks the following as well:
+
+ at itemize @bullet
+ at item
+ at samp{make installcheck} will check to make sure that the @option{--help}
+and @option{--version} really print a usage message and a version string,
+respectively. This is the @option{std-options} option (@pxref{Options}).
+
+ at item
+ at samp{make dist} will check to make sure the @file{NEWS} file has been
+updated to the current version.
+
+ at item
+ at code{VERSION} is checked to make sure its format complies with Gnits
+standards.
+ at c FIXME xref when standards are finished
+
+ at item
+ at cindex @file{README-alpha}
+If @code{VERSION} indicates that this is an alpha release, and the file
+ at file{README-alpha} appears in the topmost directory of a package, then
+it is included in the distribution. This is done in @option{--gnits}
+mode, and no other, because this mode is the only one where version
+number formats are constrained, and hence the only mode where Automake
+can automatically determine whether @file{README-alpha} should be
+included.
+
+ at item
+The file @file{THANKS} is required.
+ at end itemize
+
+
+ at node Cygnus
+ at chapter The effect of @option{--cygnus}
+
+ at cindex @option{cygnus} strictness
+
+ at emph{The features described in this section are deprecated; you must
+not use any of them in new code, and should remove their use from older
+but still maintained code: they will be withdrawn in a future Automake
+release.}
+
+Some packages, notably GNU GCC and GNU gdb, used to have a build
+environment originally written at Cygnus Support (subsequently renamed
+Cygnus Solutions, and then later purchased by Red Hat). Packages with
+this ancestry are sometimes referred to as ``Cygnus'' trees.
+
+A Cygnus tree has slightly different rules for how a
+ at file{Makefile.in} is to be constructed. Passing @option{--cygnus} to
+ at command{automake} will cause any generated @file{Makefile.in} to
+comply with Cygnus rules.
+
+Here are the precise effects of @option{--cygnus}:
+
+ at itemize @bullet
+
+ at item
+The @option{foreign} strictness is implied.
+
+ at item
+The options @option{no-installinfo}, @option{no-dependencies} and
+ at option{no-dist} are implied (@pxref{Options}).
+
+ at item
+The macro @code{AM_MAINTAINER_MODE} is required.
+
+ at item
+Info files are always created in the build directory, and not in the
+source directory. Packages that don't use the @option{cygnus} option
+can emulate this effect by using the @option{no-installinfo} option
+and listing the generated info files in the @code{CLEANFILES} variable.
+
+ at item
+ at file{texinfo.tex} is not required if a Texinfo source file is
+specified. The assumption is that the file will be supplied, but in a
+place that Automake cannot find -- it is an artifact of how Cygnus
+packages are typically bundled. This effect can be emulated in
+packages not using the @option{cygnus} option with a proper definition
+of the @code{TEXINFO_TEX} variable (@pxref{Texinfo}).
+
+ at item
+Certain tools will be searched for in the build tree as well as in the
+user's @env{PATH}. These tools are @command{runtest}, @command{expect},
+ at command{makeinfo} and @command{texi2dvi}.
+
+ at item
+The @code{check} target doesn't depend on @code{all}.
+ at end itemize
+
+
+ at node Not Enough
+ at chapter When Automake Isn't Enough
+
+In some situations, where Automake is not up to one task, one has to
+resort to handwritten rules or even handwritten @file{Makefile}s.
+
+ at menu
+* Extending:: Adding new rules or overriding existing ones.
+* Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
+ at end menu
+
+ at node Extending
+ at section Extending Automake Rules
+
+With some minor exceptions (for example @code{_PROGRAMS} variables,
+ at code{TESTS}, or @code{XFAIL_TESTS}) being rewritten to append
+ at samp{$(EXEEXT)}), the contents of a @file{Makefile.am} is copied to
+ at file{Makefile.in} verbatim.
+
+ at cindex copying semantics
+
+These copying semantics mean that many problems can be worked around
+by simply adding some @command{make} variables and rules to
+ at file{Makefile.am}. Automake will ignore these additions.
+
+ at cindex conflicting definitions
+ at cindex rules, conflicting
+ at cindex variables, conflicting
+ at cindex definitions, conflicts
+
+Since a @file{Makefile.in} is built from data gathered from three
+different places (@file{Makefile.am}, @file{configure.ac}, and
+ at command{automake} itself), it is possible to have conflicting
+definitions of rules or variables. When building @file{Makefile.in}
+the following priorities are respected by @command{automake} to ensure
+the user always has the last word:
+
+ at itemize
+ at item
+User defined variables in @file{Makefile.am} have priority over
+variables @code{AC_SUBST}ed from @file{configure.ac}, and
+ at code{AC_SUBST}ed variables have priority over
+ at command{automake}-defined variables.
+ at item
+As far as rules are concerned, a user-defined rule overrides any
+ at command{automake}-defined rule for the same target.
+ at end itemize
+
+ at cindex overriding rules
+ at cindex overriding semantics
+ at cindex rules, overriding
+
+These overriding semantics make it possible to fine tune some default
+settings of Automake, or replace some of its rules. Overriding
+Automake rules is often inadvisable, particularly in the topmost
+directory of a package with subdirectories. The @option{-Woverride}
+option (@pxref{automake Invocation}) comes in handy to catch overridden
+definitions.
+
+Note that Automake does not make any distinction between rules with
+commands and rules that only specify dependencies. So it is not
+possible to append new dependencies to an @command{automake}-defined
+target without redefining the entire rule.
+
+ at cindex @option{-local} targets
+ at cindex local targets
+
+However, various useful targets have a @samp{-local} version you can
+specify in your @file{Makefile.am}. Automake will supplement the
+standard target with these user-supplied targets.
+
+ at trindex all
+ at trindex all-local
+ at trindex info
+ at trindex info-local
+ at trindex dvi
+ at trindex dvi-local
+ at trindex ps
+ at trindex ps-local
+ at trindex pdf
+ at trindex pdf-local
+ at trindex html
+ at trindex html-local
+ at trindex check
+ at trindex check-local
+ at trindex install
+ at trindex install-data
+ at trindex install-data-local
+ at trindex install-dvi
+ at trindex install-dvi-local
+ at trindex install-exec
+ at trindex install-exec-local
+ at trindex install-html
+ at trindex install-html-local
+ at trindex install-info
+ at trindex install-info-local
+ at trindex install-pdf
+ at trindex install-pdf-local
+ at trindex install-ps
+ at trindex install-ps-local
+ at trindex uninstall
+ at trindex uninstall-local
+ at trindex mostlyclean
+ at trindex mostlyclean-local
+ at trindex clean
+ at trindex clean-local
+ at trindex distclean
+ at trindex distclean-local
+ at trindex installdirs
+ at trindex installdirs-local
+ at trindex installcheck
+ at trindex installcheck-local
+
+The targets that support a local version are @code{all}, @code{info},
+ at code{dvi}, @code{ps}, @code{pdf}, @code{html}, @code{check},
+ at code{install-data}, @code{install-dvi}, @code{install-exec},
+ at code{install-html}, @code{install-info}, @code{install-pdf},
+ at code{install-ps}, @code{uninstall}, @code{installdirs},
+ at code{installcheck} and the various @code{clean} targets
+(@code{mostlyclean}, @code{clean}, @code{distclean}, and
+ at code{maintainer-clean}).
+
+Note that there are no @code{uninstall-exec-local} or
+ at code{uninstall-data-local} targets; just use @code{uninstall-local}.
+It doesn't make sense to uninstall just data or just executables.
+
+For instance, here is one way to erase a subdirectory during
+ at samp{make clean} (@pxref{Clean}).
+
+ at example
+clean-local:
+ -rm -rf testSubDir
+ at end example
+
+You may be tempted to use @code{install-data-local} to install a file
+to some hard-coded location, but you should avoid this
+(@pxref{Hard-Coded Install Paths}).
+
+With the @code{-local} targets, there is no particular guarantee of
+execution order; typically, they are run early, but with parallel
+make, there is no way to be sure of that.
+
+ at cindex @option{-hook} targets
+ at cindex hook targets
+ at trindex install-data-hook
+ at trindex install-exec-hook
+ at trindex uninstall-hook
+ at trindex dist-hook
+
+In contrast, some rules also have a way to run another rule, called a
+ at dfn{hook}; hooks are always executed after the main rule's work is done.
+The hook is named after the principal target, with @samp{-hook} appended.
+The targets allowing hooks are @code{install-data},
+ at code{install-exec}, @code{uninstall}, @code{dist}, and
+ at code{distcheck}.
+
+For instance, here is how to create a hard link to an installed program:
+
+ at example
+install-exec-hook:
+ ln $(DESTDIR)$(bindir)/program$(EXEEXT) \
+ $(DESTDIR)$(bindir)/proglink$(EXEEXT)
+ at end example
+
+Although cheaper and more portable than symbolic links, hard links
+will not work everywhere (for instance, OS/2 does not have
+ at command{ln}). Ideally you should fall back to @samp{cp -p} when
+ at command{ln} does not work. An easy way, if symbolic links are
+acceptable to you, is to add @code{AC_PROG_LN_S} to
+ at file{configure.ac} (@pxref{Particular Programs, , Particular Program
+Checks, autoconf, The Autoconf Manual}) and use @samp{$(LN_S)} in
+ at file{Makefile.am}.
+
+ at cindex versioned binaries, installing
+ at cindex installing versioned binaries
+ at cindex @code{LN_S} example
+For instance, here is how you could install a versioned copy of a
+program using @samp{$(LN_S)}:
+
+ at c Keep in sync with insthook.test
+ at example
+install-exec-hook:
+ cd $(DESTDIR)$(bindir) && \
+ mv -f prog$(EXEEXT) prog-$(VERSION)$(EXEEXT) && \
+ $(LN_S) prog-$(VERSION)$(EXEEXT) prog$(EXEEXT)
+ at end example
+
+Note that we rename the program so that a new version will erase the
+symbolic link, not the real binary. Also we @command{cd} into the
+destination directory in order to create relative links.
+
+When writing @code{install-exec-hook} or @code{install-data-hook},
+please bear in mind that the exec/data distinction is based on the
+installation directory, not on the primary used (@pxref{The Two Parts of
+Install}).
+ at c Keep in sync with primary-prefix-couples-documented-valid.test.
+So a @code{foo_SCRIPTS} will be installed by
+ at code{install-data}, and a @code{barexec_SCRIPTS} will be installed by
+ at code{install-exec}. You should define your hooks consequently.
+
+ at c FIXME should include discussion of variables you can use in these
+ at c rules
+
+ at node Third-Party Makefiles
+ at section Third-Party @file{Makefile}s
+
+ at cindex Third-party packages, interfacing with
+ at cindex Interfacing with third-party packages
+
+In most projects all @file{Makefile}s are generated by Automake. In
+some cases, however, projects need to embed subdirectories with
+handwritten @file{Makefile}s. For instance, one subdirectory could be
+a third-party project with its own build system, not using Automake.
+
+It is possible to list arbitrary directories in @code{SUBDIRS} or
+ at code{DIST_SUBDIRS} provided each of these directories has a
+ at file{Makefile} that recognizes all the following recursive targets.
+
+ at cindex recursive targets and third-party @file{Makefile}s
+When a user runs one of these targets, that target is run recursively
+in all subdirectories. This is why it is important that even
+third-party @file{Makefile}s support them.
+
+ at table @code
+ at item all
+Compile the entire package. This is the default target in
+Automake-generated @file{Makefile}s, but it does not need to be the
+default in third-party @file{Makefile}s.
+
+ at item distdir
+ at trindex distdir
+ at vindex distdir
+ at vindex top_distdir
+Copy files to distribute into @samp{$(distdir)}, before a tarball is
+constructed. Of course this target is not required if the
+ at option{no-dist} option (@pxref{Options}) is used.
+
+The variables @samp{$(top_distdir)} and @samp{$(distdir)}
+(@pxref{The dist Hook}) will be passed from the outer package to the subpackage
+when the @code{distdir} target is invoked. These two variables have
+been adjusted for the directory that is being recursed into, so they
+are ready to use.
+
+ at item install
+ at itemx install-data
+ at itemx install-exec
+ at itemx uninstall
+Install or uninstall files (@pxref{Install}).
+
+ at item install-dvi
+ at itemx install-html
+ at itemx install-info
+ at itemx install-ps
+ at itemx install-pdf
+Install only some specific documentation format (@pxref{Texinfo}).
+
+ at item installdirs
+Create install directories, but do not install any files.
+
+ at item check
+ at itemx installcheck
+Check the package (@pxref{Tests}).
+
+ at item mostlyclean
+ at itemx clean
+ at itemx distclean
+ at itemx maintainer-clean
+Cleaning rules (@pxref{Clean}).
+
+ at item dvi
+ at itemx pdf
+ at itemx ps
+ at itemx info
+ at itemx html
+Build the documentation in various formats (@pxref{Texinfo}).
+
+ at item tags
+ at itemx ctags
+Build @file{TAGS} and @file{CTAGS} (@pxref{Tags}).
+ at end table
+
+If you have ever used Gettext in a project, this is a good example of
+how third-party @file{Makefile}s can be used with Automake. The
+ at file{Makefile}s @command{gettextize} puts in the @file{po/} and
+ at file{intl/} directories are handwritten @file{Makefile}s that
+implement all these targets. That way they can be added to
+ at code{SUBDIRS} in Automake packages.
+
+Directories that are only listed in @code{DIST_SUBDIRS} but not in
+ at code{SUBDIRS} need only the @code{distclean},
+ at code{maintainer-clean}, and @code{distdir} rules (@pxref{Conditional
+Subdirectories}).
+
+Usually, many of these rules are irrelevant to the third-party
+subproject, but they are required for the whole package to work. It's
+OK to have a rule that does nothing, so if you are integrating a
+third-party project with no documentation or tag support, you could
+simply augment its @file{Makefile} as follows:
+
+ at example
+EMPTY_AUTOMAKE_TARGETS = dvi pdf ps info html tags ctags
+.PHONY: $(EMPTY_AUTOMAKE_TARGETS)
+$(EMPTY_AUTOMAKE_TARGETS):
+ at end example
+
+Another aspect of integrating third-party build systems is whether
+they support VPATH builds (@pxref{VPATH Builds}). Obviously if the
+subpackage does not support VPATH builds the whole package will not
+support VPATH builds. This in turns means that @samp{make distcheck}
+will not work, because it relies on VPATH builds. Some people can
+live without this (actually, many Automake users have never heard of
+ at samp{make distcheck}). Other people may prefer to revamp the
+existing @file{Makefile}s to support VPATH at . Doing so does not
+necessarily require Automake, only Autoconf is needed (@pxref{Build
+Directories, , Build Directories, autoconf, The Autoconf Manual}).
+The necessary substitutions: @samp{@@srcdir@@}, @samp{@@top_srcdir@@},
+and @samp{@@top_builddir@@} are defined by @file{configure} when it
+processes a @file{Makefile} (@pxref{Preset Output Variables, , Preset
+Output Variables, autoconf, The Autoconf Manual}), they are not
+computed by the Makefile like the aforementioned @samp{$(distdir)} and
+ at samp{$(top_distdir)} variables.
+
+It is sometimes inconvenient to modify a third-party @file{Makefile}
+to introduce the above required targets. For instance, one may want to
+keep the third-party sources untouched to ease upgrades to new
+versions.
+
+ at cindex @file{GNUmakefile} including @file{Makefile}
+Here are two other ideas. If GNU make is assumed, one possibility is
+to add to that subdirectory a @file{GNUmakefile} that defines the
+required targets and includes the third-party @file{Makefile}. For
+this to work in VPATH builds, @file{GNUmakefile} must lie in the build
+directory; the easiest way to do this is to write a
+ at file{GNUmakefile.in} instead, and have it processed with
+ at code{AC_CONFIG_FILES} from the outer package. For example if we
+assume @file{Makefile} defines all targets except the documentation
+targets, and that the @code{check} target is actually called
+ at code{test}, we could write @file{GNUmakefile} (or
+ at file{GNUmakefile.in}) like this:
+
+ at example
+# First, include the real Makefile
+include Makefile
+# Then, define the other targets needed by Automake Makefiles.
+.PHONY: dvi pdf ps info html check
+dvi pdf ps info html:
+check: test
+ at end example
+
+ at cindex Proxy @file{Makefile} for third-party packages
+A similar idea that does not use @code{include} is to write a proxy
+ at file{Makefile} that dispatches rules to the real @file{Makefile},
+either with @samp{$(MAKE) -f Makefile.real $(AM_MAKEFLAGS) target} (if
+it's OK to rename the original @file{Makefile}) or with @samp{cd
+subdir && $(MAKE) $(AM_MAKEFLAGS) target} (if it's OK to store the
+subdirectory project one directory deeper). The good news is that
+this proxy @file{Makefile} can be generated with Automake. All we
+need are @option{-local} targets (@pxref{Extending}) that perform the
+dispatch. Of course the other Automake features are available, so you
+could decide to let Automake perform distribution or installation.
+Here is a possible @file{Makefile.am}:
+
+ at example
+all-local:
+ cd subdir && $(MAKE) $(AM_MAKEFLAGS) all
+check-local:
+ cd subdir && $(MAKE) $(AM_MAKEFLAGS) test
+clean-local:
+ cd subdir && $(MAKE) $(AM_MAKEFLAGS) clean
+
+# Assuming the package knows how to install itself
+install-data-local:
+ cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-data
+install-exec-local:
+ cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-exec
+uninstall-local:
+ cd subdir && $(MAKE) $(AM_MAKEFLAGS) uninstall
+
+# Distribute files from here.
+EXTRA_DIST = subdir/Makefile subdir/program.c ...
+ at end example
+
+Pushing this idea to the extreme, it is also possible to ignore the
+subproject build system and build everything from this proxy
+ at file{Makefile.am}. This might sound very sensible if you need VPATH
+builds but the subproject does not support them.
+
+ at node Distributing
+ at chapter Distributing @file{Makefile.in}s
+
+Automake places no restrictions on the distribution of the resulting
+ at file{Makefile.in}s. We still encourage software authors to
+distribute their work under terms like those of the GPL, but doing so
+is not required to use Automake.
+
+Some of the files that can be automatically installed via the
+ at option{--add-missing} switch do fall under the GPL at . However, these also
+have a special exception allowing you to distribute them with your
+package, regardless of the licensing you choose.
+
+
+ at node API Versioning
+ at chapter Automake API Versioning
+
+New Automake releases usually include bug fixes and new features.
+Unfortunately they may also introduce new bugs and incompatibilities.
+This makes four reasons why a package may require a particular Automake
+version.
+
+Things get worse when maintaining a large tree of packages, each one
+requiring a different version of Automake. In the past, this meant that
+any developer (and sometimes users) had to install several versions of
+Automake in different places, and switch @samp{$PATH} appropriately for
+each package.
+
+Starting with version 1.6, Automake installs versioned binaries. This
+means you can install several versions of Automake in the same
+ at samp{$prefix}, and can select an arbitrary Automake version by running
+ at command{automake-1.6} or @command{automake-1.7} without juggling with
+ at samp{$PATH}. Furthermore, @file{Makefile}'s generated by Automake 1.6
+will use @command{automake-1.6} explicitly in their rebuild rules.
+
+The number @samp{1.6} in @command{automake-1.6} is Automake's API version,
+not Automake's version. If a bug fix release is made, for instance
+Automake 1.6.1, the API version will remain 1.6. This means that a
+package that works with Automake 1.6 should also work with 1.6.1; after
+all, this is what people expect from bug fix releases.
+
+If your package relies on a feature or a bug fix introduced in
+a release, you can pass this version as an option to Automake to ensure
+older releases will not be used. For instance, use this in your
+ at file{configure.ac}:
+
+ at example
+ AM_INIT_AUTOMAKE([1.6.1]) dnl Require Automake 1.6.1 or better.
+ at end example
+
+ at noindent
+or, in a particular @file{Makefile.am}:
+
+ at example
+ AUTOMAKE_OPTIONS = 1.6.1 # Require Automake 1.6.1 or better.
+ at end example
+
+ at noindent
+Automake will print an error message if its version is
+older than the requested version.
+
+
+ at heading What is in the API
+
+Automake's programming interface is not easy to define. Basically it
+should include at least all @strong{documented} variables and targets
+that a @file{Makefile.am} author can use, any behavior associated with
+them (e.g., the places where @samp{-hook}'s are run), the command line
+interface of @command{automake} and @command{aclocal}, @dots{}
+
+ at heading What is not in the API
+
+Every undocumented variable, target, or command line option, is not part
+of the API at . You should avoid using them, as they could change from one
+version to the other (even in bug fix releases, if this helps to fix a
+bug).
+
+If it turns out you need to use such an undocumented feature, contact
+ at email{automake@@gnu.org} and try to get it documented and exercised by
+the test-suite.
+
+ at node Upgrading
+ at chapter Upgrading a Package to a Newer Automake Version
+
+Automake maintains three kind of files in a package.
+
+ at itemize
+ at item @file{aclocal.m4}
+ at item @file{Makefile.in}s
+ at item auxiliary tools like @file{install-sh} or @file{py-compile}
+ at end itemize
+
+ at file{aclocal.m4} is generated by @command{aclocal} and contains some
+Automake-supplied M4 macros. Auxiliary tools are installed by
+ at samp{automake --add-missing} when needed. @file{Makefile.in}s are
+built from @file{Makefile.am} by @command{automake}, and rely on the
+definitions of the M4 macros put in @file{aclocal.m4} as well as the
+behavior of the auxiliary tools installed.
+
+Because all these files are closely related, it is important to
+regenerate all of them when upgrading to a newer Automake release.
+The usual way to do that is
+
+ at example
+aclocal # with any option needed (such a -I m4)
+autoconf
+automake --add-missing --force-missing
+ at end example
+
+ at noindent
+or more conveniently:
+
+ at example
+autoreconf -vfi
+ at end example
+
+The use of @option{--force-missing} ensures that auxiliary tools will be
+overridden by new versions (@pxref{automake Invocation}).
+
+It is important to regenerate all these files each time Automake is
+upgraded, even between bug fixes releases. For instance, it is not
+unusual for a bug fix to involve changes to both the rules generated
+in @file{Makefile.in} and the supporting M4 macros copied to
+ at file{aclocal.m4}.
+
+Presently @command{automake} is able to diagnose situations where
+ at file{aclocal.m4} has been generated with another version of
+ at command{aclocal}. However it never checks whether auxiliary scripts
+are up-to-date. In other words, @command{automake} will tell you when
+ at command{aclocal} needs to be rerun, but it will never diagnose a
+missing @option{--force-missing}.
+
+Before upgrading to a new major release, it is a good idea to read the
+file @file{NEWS}. This file lists all changes between releases: new
+features, obsolete constructs, known incompatibilities, and
+workarounds.
+
+ at node FAQ
+ at chapter Frequently Asked Questions about Automake
+
+This chapter covers some questions that often come up on the mailing
+lists.
+
+ at menu
+* CVS:: CVS and generated files
+* maintainer-mode:: missing and AM_MAINTAINER_MODE
+* Wildcards:: Why doesn't Automake support wildcards?
+* Limitations on File Names:: Limitations on source and installed file names
+* distcleancheck:: Files left in build directory after distclean
+* Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
+* Renamed Objects:: Why are object files sometimes renamed?
+* Per-Object Flags:: How to simulate per-object flags?
+* Multiple Outputs:: Writing rules for tools with many output files
+* Hard-Coded Install Paths:: Installing to hard-coded locations
+* Debugging Make Rules:: Strategies when things don't work as expected
+* Reporting Bugs:: Feedback on bugs and feature requests
+ at end menu
+
+ at node CVS
+ at section CVS and generated files
+
+ at subheading Background: distributed generated Files
+ at cindex generated files, distributed
+ at cindex rebuild rules
+
+Packages made with Autoconf and Automake ship with some generated
+files like @file{configure} or @file{Makefile.in}. These files were
+generated on the developer's host and are distributed so that
+end-users do not have to install the maintainer tools required to
+rebuild them. Other generated files like Lex scanners, Yacc parsers,
+or Info documentation, are usually distributed on similar grounds.
+
+Automake outputs rules in @file{Makefile}s to rebuild these files. For
+instance, @command{make} will run @command{autoconf} to rebuild
+ at file{configure} whenever @file{configure.ac} is changed. This makes
+development safer by ensuring a @file{configure} is never out-of-date
+with respect to @file{configure.ac}.
+
+As generated files shipped in packages are up-to-date, and because
+ at command{tar} preserves times-tamps, these rebuild rules are not
+triggered when a user unpacks and builds a package.
+
+ at subheading Background: CVS and Timestamps
+ at cindex timestamps and CVS
+ at cindex CVS and timestamps
+
+Unless you use CVS keywords (in which case files must be updated at
+commit time), CVS preserves timestamp during @samp{cvs commit} and
+ at samp{cvs import -d} operations.
+
+When you check out a file using @samp{cvs checkout} its timestamp is
+set to that of the revision that is being checked out.
+
+However, during @command{cvs update}, files will have the date of the
+update, not the original timestamp of this revision. This is meant to
+make sure that @command{make} notices sources files have been updated.
+
+This timestamp shift is troublesome when both sources and generated
+files are kept under CVS at . Because CVS processes files in lexical
+order, @file{configure.ac} will appear newer than @file{configure}
+after a @command{cvs update} that updates both files, even if
+ at file{configure} was newer than @file{configure.ac} when it was
+checked in. Calling @command{make} will then trigger a spurious rebuild
+of @file{configure}.
+
+ at subheading Living with CVS in Autoconfiscated Projects
+ at cindex CVS and generated files
+ at cindex generated files and CVS
+
+There are basically two clans amongst maintainers: those who keep all
+distributed files under CVS, including generated files, and those who
+keep generated files @emph{out} of CVS.
+
+ at subsubheading All Files in CVS
+
+ at itemize @bullet
+ at item
+The CVS repository contains all distributed files so you know exactly
+what is distributed, and you can checkout any prior version entirely.
+
+ at item
+Maintainers can see how generated files evolve (for instance, you can
+see what happens to your @file{Makefile.in}s when you upgrade Automake
+and make sure they look OK).
+
+ at item
+Users do not need the autotools to build a checkout of the project, it
+works just like a released tarball.
+
+ at item
+If users use @command{cvs update} to update their copy, instead of
+ at command{cvs checkout} to fetch a fresh one, timestamps will be
+inaccurate. Some rebuild rules will be triggered and attempt to
+run developer tools such as @command{autoconf} or @command{automake}.
+
+Actually, calls to such tools are all wrapped into a call to the
+ at command{missing} script discussed later (@pxref{maintainer-mode}).
+ at command{missing} will take care of fixing the timestamps when these
+tools are not installed, so that the build can continue.
+
+ at item
+In distributed development, developers are likely to have different
+version of the maintainer tools installed. In this case rebuilds
+triggered by timestamp lossage will lead to spurious changes
+to generated files. There are several solutions to this:
+
+ at itemize
+ at item
+All developers should use the same versions, so that the rebuilt files
+are identical to files in CVS at . (This starts to be difficult when each
+project you work on uses different versions.)
+ at item
+Or people use a script to fix the timestamp after a checkout (the GCC
+folks have such a script).
+ at item
+Or @file{configure.ac} uses @code{AM_MAINTAINER_MODE}, which will
+disable all these rebuild rules by default. This is further discussed
+in @ref{maintainer-mode}.
+ at end itemize
+
+ at item
+Although we focused on spurious rebuilds, the converse can also
+happen. CVS's timestamp handling can also let you think an
+out-of-date file is up-to-date.
+
+For instance, suppose a developer has modified @file{Makefile.am} and
+has rebuilt @file{Makefile.in}, and then decides to do a last-minute
+change to @file{Makefile.am} right before checking in both files
+(without rebuilding @file{Makefile.in} to account for the change).
+
+This last change to @file{Makefile.am} makes the copy of
+ at file{Makefile.in} out-of-date. Since CVS processes files
+alphabetically, when another developer @samp{cvs update}s his or her
+tree, @file{Makefile.in} will happen to be newer than
+ at file{Makefile.am}. This other developer will not see that
+ at file{Makefile.in} is out-of-date.
+
+ at end itemize
+
+ at subsubheading Generated Files out of CVS
+
+One way to get CVS and @command{make} working peacefully is to never
+store generated files in CVS, i.e., do not CVS-control files that
+are @file{Makefile} targets (also called @emph{derived} files).
+
+This way developers are not annoyed by changes to generated files. It
+does not matter if they all have different versions (assuming they are
+compatible, of course). And finally, timestamps are not lost, changes
+to sources files can't be missed as in the
+ at file{Makefile.am}/@file{Makefile.in} example discussed earlier.
+
+The drawback is that the CVS repository is not an exact copy of what
+is distributed and that users now need to install various development
+tools (maybe even specific versions) before they can build a checkout.
+But, after all, CVS's job is versioning, not distribution.
+
+Allowing developers to use different versions of their tools can also
+hide bugs during distributed development. Indeed, developers will be
+using (hence testing) their own generated files, instead of the
+generated files that will be released actually. The developer who
+prepares the tarball might be using a version of the tool that
+produces bogus output (for instance a non-portable C file), something
+other developers could have noticed if they weren't using their own
+versions of this tool.
+
+ at subheading Third-party Files
+ at cindex CVS and third-party files
+ at cindex third-party files and CVS
+
+Another class of files not discussed here (because they do not cause
+timestamp issues) are files that are shipped with a package, but
+maintained elsewhere. For instance, tools like @command{gettextize}
+and @command{autopoint} (from Gettext) or @command{libtoolize} (from
+Libtool), will install or update files in your package.
+
+These files, whether they are kept under CVS or not, raise similar
+concerns about version mismatch between developers' tools. The
+Gettext manual has a section about this, see @ref{CVS Issues, CVS
+Issues, Integrating with CVS, gettext, GNU gettext tools}.
+
+ at node maintainer-mode
+ at section @command{missing} and @code{AM_MAINTAINER_MODE}
+
+ at subheading @command{missing}
+ at cindex @command{missing}, purpose
+
+The @command{missing} script is a wrapper around several maintainer
+tools, designed to warn users if a maintainer tool is required but
+missing. Typical maintainer tools are @command{autoconf},
+ at command{automake}, @command{bison}, etc. Because file generated by
+these tools are shipped with the other sources of a package, these
+tools shouldn't be required during a user build and they are not
+checked for in @file{configure}.
+
+However, if for some reason a rebuild rule is triggered and involves a
+missing tool, @command{missing} will notice it and warn the user.
+Besides the warning, when a tool is missing, @command{missing} will
+attempt to fix timestamps in a way that allows the build to continue.
+For instance, @command{missing} will touch @file{configure} if
+ at command{autoconf} is not installed. When all distributed files are
+kept under version control, this feature of @command{missing} allows a
+user @emph{with no maintainer tools} to build a package off its version
+control repository, bypassing any timestamp inconsistency (implied by
+e.g.@: @samp{cvs update} or @samp{git clone}).
+
+If the required tool is installed, @command{missing} will run it and
+won't attempt to continue after failures. This is correct during
+development: developers love fixing failures. However, users with
+wrong versions of maintainer tools may get an error when the rebuild
+rule is spuriously triggered, halting the build. This failure to let
+the build continue is one of the arguments of the
+ at code{AM_MAINTAINER_MODE} advocates.
+
+ at subheading @code{AM_MAINTAINER_MODE}
+ at cindex @code{AM_MAINTAINER_MODE}, purpose
+ at acindex AM_MAINTAINER_MODE
+
+ at code{AM_MAINTAINER_MODE} allows you to choose whether the so called
+"rebuild rules" should be enabled or disabled. With
+ at code{AM_MAINTAINER_MODE([enable])}, they are enabled by default,
+otherwise they are disabled by default. In the latter case, if
+you have @code{AM_MAINTAINER_MODE} in @file{configure.ac}, and run
+ at samp{./configure && make}, then @command{make} will *never* attempt to
+rebuild @file{configure}, @file{Makefile.in}s, Lex or Yacc outputs, etc.
+I.e., this disables build rules for files that are usually distributed
+and that users should normally not have to update.
+
+The user can override the default setting by passing either
+ at samp{--enable-maintainer-mode} or @samp{--disable-maintainer-mode}
+to @command{configure}.
+
+People use @code{AM_MAINTAINER_MODE} either because they do not want their
+users (or themselves) annoyed by timestamps lossage (@pxref{CVS}), or
+because they simply can't stand the rebuild rules and prefer running
+maintainer tools explicitly.
+
+ at code{AM_MAINTAINER_MODE} also allows you to disable some custom build
+rules conditionally. Some developers use this feature to disable
+rules that need exotic tools that users may not have available.
+
+Several years ago Fran@,{c}ois Pinard pointed out several arguments
+against this @code{AM_MAINTAINER_MODE} macro. Most of them relate to
+insecurity. By removing dependencies you get non-dependable builds:
+changes to sources files can have no effect on generated files and this
+can be very confusing when unnoticed. He adds that security shouldn't
+be reserved to maintainers (what @option{--enable-maintainer-mode}
+suggests), on the contrary. If one user has to modify a
+ at file{Makefile.am}, then either @file{Makefile.in} should be updated
+or a warning should be output (this is what Automake uses
+ at command{missing} for) but the last thing you want is that nothing
+happens and the user doesn't notice it (this is what happens when
+rebuild rules are disabled by @code{AM_MAINTAINER_MODE}).
+
+Jim Meyering, the inventor of the @code{AM_MAINTAINER_MODE} macro was
+swayed by Fran@,{c}ois's arguments, and got rid of
+ at code{AM_MAINTAINER_MODE} in all of his packages.
+
+Still many people continue to use @code{AM_MAINTAINER_MODE}, because
+it helps them working on projects where all files are kept under version
+control, and because @command{missing} isn't enough if you have the
+wrong version of the tools.
+
+
+ at node Wildcards
+ at section Why doesn't Automake support wildcards?
+ at cindex wildcards
+
+Developers are lazy. They would often like to use wildcards in
+ at file{Makefile.am}s, so that they would not need to remember to
+update @file{Makefile.am}s every time they add, delete, or rename
+a file.
+
+There are several objections to this:
+ at itemize
+ at item
+When using CVS (or similar) developers need to remember they have to
+run @samp{cvs add} or @samp{cvs rm} anyway. Updating
+ at file{Makefile.am} accordingly quickly becomes a reflex.
+
+Conversely, if your application doesn't compile
+because you forgot to add a file in @file{Makefile.am}, it will help
+you remember to @samp{cvs add} it.
+
+ at item
+Using wildcards makes it easy to distribute files by mistake. For
+instance, some code a developer is experimenting with (a test case,
+say) that should not be part of the distribution.
+
+ at item
+Using wildcards it's easy to omit some files by mistake. For
+instance, one developer creates a new file, uses it in many places,
+but forgets to commit it. Another developer then checks out the
+incomplete project and is able to run @samp{make dist} successfully,
+even though a file is missing. By listing files, @samp{make dist}
+ at emph{will} complain.
+
+ at item
+Wildcards are not portable to some non-GNU @command{make} implementations,
+e.g., NetBSD @command{make} will not expand globs such as @samp{*} in
+prerequisites of a target.
+
+ at item
+Finally, it's really hard to @emph{forget} to add a file to
+ at file{Makefile.am}: files that are not listed in @file{Makefile.am} are
+not compiled or installed, so you can't even test them.
+ at end itemize
+
+Still, these are philosophical objections, and as such you may disagree,
+or find enough value in wildcards to dismiss all of them. Before you
+start writing a patch against Automake to teach it about wildcards,
+let's see the main technical issue: portability.
+
+Although @samp{$(wildcard ...)} works with GNU @command{make}, it is
+not portable to other @command{make} implementations.
+
+The only way Automake could support @command{$(wildcard ...)} is by
+expending @command{$(wildcard ...)} when @command{automake} is run.
+The resulting @file{Makefile.in}s would be portable since they would
+list all files and not use @samp{$(wildcard ...)}. However that
+means developers would need to remember to run @command{automake} each
+time they add, delete, or rename files.
+
+Compared to editing @file{Makefile.am}, this is a very small gain. Sure,
+it's easier and faster to type @samp{automake; make} than to type
+ at samp{emacs Makefile.am; make}. But nobody bothered enough to write a
+patch to add support for this syntax. Some people use scripts to
+generate file lists in @file{Makefile.am} or in separate
+ at file{Makefile} fragments.
+
+Even if you don't care about portability, and are tempted to use
+ at samp{$(wildcard ...)} anyway because you target only GNU Make, you
+should know there are many places where Automake needs to know exactly
+which files should be processed. As Automake doesn't know how to
+expand @samp{$(wildcard ...)}, you cannot use it in these places.
+ at samp{$(wildcard ...)} is a black box comparable to @code{AC_SUBST}ed
+variables as far Automake is concerned.
+
+You can get warnings about @samp{$(wildcard ...}) constructs using the
+ at option{-Wportability} flag.
+
+ at node Limitations on File Names
+ at section Limitations on File Names
+ at cindex file names, limitations on
+
+Automake attempts to support all kinds of file names, even those that
+contain unusual characters or are unusually long. However, some
+limitations are imposed by the underlying operating system and tools.
+
+Most operating systems prohibit the use of the null byte in file
+names, and reserve @samp{/} as a directory separator. Also, they
+require that file names are properly encoded for the user's locale.
+Automake is subject to these limits.
+
+Portable packages should limit themselves to POSIX file
+names. These can contain ASCII letters and digits,
+ at samp{_}, @samp{.}, and @samp{-}. File names consist of components
+separated by @samp{/}. File name components cannot begin with
+ at samp{-}.
+
+Portable POSIX file names cannot contain components that exceed a
+14-byte limit, but nowadays it's normally safe to assume the
+more-generous XOPEN limit of 255 bytes. POSIX
+limits file names to 255 bytes (XOPEN allows 1023 bytes),
+but you may want to limit a source tarball to file names of 99 bytes
+to avoid interoperability problems with old versions of @command{tar}.
+
+If you depart from these rules (e.g., by using non-ASCII
+characters in file names, or by using lengthy file names), your
+installers may have problems for reasons unrelated to Automake.
+However, if this does not concern you, you should know about the
+limitations imposed by Automake itself. These limitations are
+undesirable, but some of them seem to be inherent to underlying tools
+like Autoconf, Make, M4, and the shell. They fall into three
+categories: install directories, build directories, and file names.
+
+The following characters:
+
+ at example
+ at r{newline} " # $ ' `
+ at end example
+
+should not appear in the names of install directories. For example,
+the operand of @command{configure}'s @option{--prefix} option should
+not contain these characters.
+
+Build directories suffer the same limitations as install directories,
+and in addition should not contain the following characters:
+
+ at example
+& @@ \
+ at end example
+
+For example, the full name of the directory containing the source
+files should not contain these characters.
+
+Source and installation file names like @file{main.c} are limited even
+further: they should conform to the POSIX/XOPEN
+rules described above. In addition, if you plan to port to
+non-POSIX environments, you should avoid file names that
+differ only in case (e.g., @file{makefile} and @file{Makefile}).
+Nowadays it is no longer worth worrying about the 8.3 limits of
+DOS file systems.
+
+ at node distcleancheck
+ at section Files left in build directory after distclean
+ at cindex @code{distclean}, diagnostic
+ at cindex @samp{make distclean}, diagnostic
+ at cindex dependencies and distributed files
+ at trindex distclean
+ at trindex distcleancheck
+
+This is a diagnostic you might encounter while running @samp{make
+distcheck}.
+
+As explained in @ref{Checking the Distribution}, @samp{make distcheck}
+attempts to build and check your package for errors like this one.
+
+ at samp{make distcheck} will perform a @code{VPATH} build of your
+package (@pxref{VPATH Builds}), and then call @samp{make distclean}.
+Files left in the build directory after @samp{make distclean} has run
+are listed after this error.
+
+This diagnostic really covers two kinds of errors:
+
+ at itemize @bullet
+ at item
+files that are forgotten by distclean;
+ at item
+distributed files that are erroneously rebuilt.
+ at end itemize
+
+The former left-over files are not distributed, so the fix is to mark
+them for cleaning (@pxref{Clean}), this is obvious and doesn't deserve
+more explanations.
+
+The latter bug is not always easy to understand and fix, so let's
+proceed with an example. Suppose our package contains a program for
+which we want to build a man page using @command{help2man}. GNU
+ at command{help2man} produces simple manual pages from the @option{--help}
+and @option{--version} output of other commands (@pxref{Top, , Overview,
+help2man, The Help2man Manual}). Because we don't want to force our
+users to install @command{help2man}, we decide to distribute the
+generated man page using the following setup.
+
+ at example
+# This Makefile.am is bogus.
+bin_PROGRAMS = foo
+foo_SOURCES = foo.c
+dist_man_MANS = foo.1
+
+foo.1: foo$(EXEEXT)
+ help2man --output=foo.1 ./foo$(EXEEXT)
+ at end example
+
+This will effectively distribute the man page. However,
+ at samp{make distcheck} will fail with:
+
+ at example
+ERROR: files left in build directory after distclean:
+./foo.1
+ at end example
+
+Why was @file{foo.1} rebuilt? Because although distributed,
+ at file{foo.1} depends on a non-distributed built file:
+ at file{foo$(EXEEXT)}. @file{foo$(EXEEXT)} is built by the user, so it
+will always appear to be newer than the distributed @file{foo.1}.
+
+ at samp{make distcheck} caught an inconsistency in our package. Our
+intent was to distribute @file{foo.1} so users do not need to install
+ at command{help2man}, however since this rule causes this file to be
+always rebuilt, users @emph{do} need @command{help2man}. Either we
+should ensure that @file{foo.1} is not rebuilt by users, or there is
+no point in distributing @file{foo.1}.
+
+More generally, the rule is that distributed files should never depend
+on non-distributed built files. If you distribute something
+generated, distribute its sources.
+
+One way to fix the above example, while still distributing
+ at file{foo.1} is to not depend on @file{foo$(EXEEXT)}. For instance,
+assuming @command{foo --version} and @command{foo --help} do not
+change unless @file{foo.c} or @file{configure.ac} change, we could
+write the following @file{Makefile.am}:
+
+ at example
+bin_PROGRAMS = foo
+foo_SOURCES = foo.c
+dist_man_MANS = foo.1
+
+foo.1: foo.c $(top_srcdir)/configure.ac
+ $(MAKE) $(AM_MAKEFLAGS) foo$(EXEEXT)
+ help2man --output=foo.1 ./foo$(EXEEXT)
+ at end example
+
+This way, @file{foo.1} will not get rebuilt every time
+ at file{foo$(EXEEXT)} changes. The @command{make} call makes sure
+ at file{foo$(EXEEXT)} is up-to-date before @command{help2man}. Another
+way to ensure this would be to use separate directories for binaries
+and man pages, and set @code{SUBDIRS} so that binaries are built
+before man pages.
+
+We could also decide not to distribute @file{foo.1}. In
+this case it's fine to have @file{foo.1} dependent upon
+ at file{foo$(EXEEXT)}, since both will have to be rebuilt.
+However it would be impossible to build the package in a
+cross-compilation, because building @file{foo.1} involves
+an @emph{execution} of @file{foo$(EXEEXT)}.
+
+Another context where such errors are common is when distributed files
+are built by tools that are built by the package. The pattern is
+similar:
+
+ at example
+distributed-file: built-tools distributed-sources
+ build-command
+ at end example
+
+ at noindent
+should be changed to
+
+ at example
+distributed-file: distributed-sources
+ $(MAKE) $(AM_MAKEFLAGS) built-tools
+ build-command
+ at end example
+
+ at noindent
+or you could choose not to distribute @file{distributed-file}, if
+cross-compilation does not matter.
+
+The points made through these examples are worth a summary:
+
+ at cartouche
+ at itemize
+ at item
+Distributed files should never depend upon non-distributed built
+files.
+ at item
+Distributed files should be distributed with all their dependencies.
+ at item
+If a file is @emph{intended} to be rebuilt by users, then there is no point
+in distributing it.
+ at end itemize
+ at end cartouche
+
+ at vrindex distcleancheck_listfiles
+For desperate cases, it's always possible to disable this check by
+setting @code{distcleancheck_listfiles} as documented in @ref{Checking
+the Distribution}.
+Make sure you do understand the reason why @samp{make distcheck}
+complains before you do this. @code{distcleancheck_listfiles} is a
+way to @emph{hide} errors, not to fix them. You can always do better.
+
+ at node Flag Variables Ordering
+ at section Flag Variables Ordering
+ at cindex Ordering flag variables
+ at cindex Flag variables, ordering
+
+ at display
+What is the difference between @code{AM_CFLAGS}, @code{CFLAGS}, and
+ at code{mumble_CFLAGS}?
+ at end display
+
+ at display
+Why does @command{automake} output @code{CPPFLAGS} after
+ at code{AM_CPPFLAGS} on compile lines? Shouldn't it be the converse?
+ at end display
+
+ at display
+My @file{configure} adds some warning flags into @code{CXXFLAGS}. In
+one @file{Makefile.am} I would like to append a new flag, however if I
+put the flag into @code{AM_CXXFLAGS} it is prepended to the other
+flags, not appended.
+ at end display
+
+ at subheading Compile Flag Variables
+ at cindex Flag Variables, Ordering
+ at cindex Compile Flag Variables
+ at cindex @code{AM_CCASFLAGS} and @code{CCASFLAGS}
+ at cindex @code{AM_CFLAGS} and @code{CFLAGS}
+ at cindex @code{AM_CPPFLAGS} and @code{CPPFLAGS}
+ at cindex @code{AM_CXXFLAGS} and @code{CXXFLAGS}
+ at cindex @code{AM_FCFLAGS} and @code{FCFLAGS}
+ at cindex @code{AM_FFLAGS} and @code{FFLAGS}
+ at cindex @code{AM_GCJFLAGS} and @code{GCJFLAGS}
+ at cindex @code{AM_LDFLAGS} and @code{LDFLAGS}
+ at cindex @code{AM_LFLAGS} and @code{LFLAGS}
+ at cindex @code{AM_LIBTOOLFLAGS} and @code{LIBTOOLFLAGS}
+ at cindex @code{AM_OBJCFLAGS} and @code{OBJCFLAGS}
+ at cindex @code{AM_RFLAGS} and @code{RFLAGS}
+ at cindex @code{AM_UPCFLAGS} and @code{UPCFLAGS}
+ at cindex @code{AM_YFLAGS} and @code{YFLAGS}
+ at cindex @code{CCASFLAGS} and @code{AM_CCASFLAGS}
+ at cindex @code{CFLAGS} and @code{AM_CFLAGS}
+ at cindex @code{CPPFLAGS} and @code{AM_CPPFLAGS}
+ at cindex @code{CXXFLAGS} and @code{AM_CXXFLAGS}
+ at cindex @code{FCFLAGS} and @code{AM_FCFLAGS}
+ at cindex @code{FFLAGS} and @code{AM_FFLAGS}
+ at cindex @code{GCJFLAGS} and @code{AM_GCJFLAGS}
+ at cindex @code{LDFLAGS} and @code{AM_LDFLAGS}
+ at cindex @code{LFLAGS} and @code{AM_LFLAGS}
+ at cindex @code{LIBTOOLFLAGS} and @code{AM_LIBTOOLFLAGS}
+ at cindex @code{OBJCFLAGS} and @code{AM_OBJCFLAGS}
+ at cindex @code{RFLAGS} and @code{AM_RFLAGS}
+ at cindex @code{UPCFLAGS} and @code{AM_UPCFLAGS}
+ at cindex @code{YFLAGS} and @code{AM_YFLAGS}
+
+This section attempts to answer all the above questions. We will
+mostly discuss @code{CPPFLAGS} in our examples, but actually the
+answer holds for all the compile flags used in Automake:
+ at code{CCASFLAGS}, @code{CFLAGS}, @code{CPPFLAGS}, @code{CXXFLAGS},
+ at code{FCFLAGS}, @code{FFLAGS}, @code{GCJFLAGS}, @code{LDFLAGS},
+ at code{LFLAGS}, @code{LIBTOOLFLAGS}, @code{OBJCFLAGS}, @code{RFLAGS},
+ at code{UPCFLAGS}, and @code{YFLAGS}.
+
+ at code{CPPFLAGS}, @code{AM_CPPFLAGS}, and @code{mumble_CPPFLAGS} are
+three variables that can be used to pass flags to the C preprocessor
+(actually these variables are also used for other languages like C++
+or preprocessed Fortran). @code{CPPFLAGS} is the user variable
+(@pxref{User Variables}), @code{AM_CPPFLAGS} is the Automake variable,
+and @code{mumble_CPPFLAGS} is the variable specific to the
+ at code{mumble} target (we call this a per-target variable,
+ at pxref{Program and Library Variables}).
+
+Automake always uses two of these variables when compiling C sources
+files. When compiling an object file for the @code{mumble} target,
+the first variable will be @code{mumble_CPPFLAGS} if it is defined, or
+ at code{AM_CPPFLAGS} otherwise. The second variable is always
+ at code{CPPFLAGS}.
+
+In the following example,
+
+ at example
+bin_PROGRAMS = foo bar
+foo_SOURCES = xyz.c
+bar_SOURCES = main.c
+foo_CPPFLAGS = -DFOO
+AM_CPPFLAGS = -DBAZ
+ at end example
+
+ at noindent
+ at file{xyz.o} will be compiled with @samp{$(foo_CPPFLAGS) $(CPPFLAGS)},
+(because @file{xyz.o} is part of the @code{foo} target), while
+ at file{main.o} will be compiled with @samp{$(AM_CPPFLAGS) $(CPPFLAGS)}
+(because there is no per-target variable for target @code{bar}).
+
+The difference between @code{mumble_CPPFLAGS} and @code{AM_CPPFLAGS}
+being clear enough, let's focus on @code{CPPFLAGS}. @code{CPPFLAGS}
+is a user variable, i.e., a variable that users are entitled to modify
+in order to compile the package. This variable, like many others,
+is documented at the end of the output of @samp{configure --help}.
+
+For instance, someone who needs to add @file{/home/my/usr/include} to
+the C compiler's search path would configure a package with
+
+ at example
+./configure CPPFLAGS='-I /home/my/usr/include'
+ at end example
+
+ at noindent
+and this flag would be propagated to the compile rules of all
+ at file{Makefile}s.
+
+It is also not uncommon to override a user variable at
+ at command{make}-time. Many installers do this with @code{prefix}, but
+this can be useful with compiler flags too. For instance, if, while
+debugging a C++ project, you need to disable optimization in one
+specific object file, you can run something like
+
+ at example
+rm file.o
+make CXXFLAGS=-O0 file.o
+make
+ at end example
+
+The reason @samp{$(CPPFLAGS)} appears after @samp{$(AM_CPPFLAGS)} or
+ at samp{$(mumble_CPPFLAGS)} in the compile command is that users
+should always have the last say. It probably makes more sense if you
+think about it while looking at the @samp{CXXFLAGS=-O0} above, which
+should supersede any other switch from @code{AM_CXXFLAGS} or
+ at code{mumble_CXXFLAGS} (and this of course replaces the previous value
+of @code{CXXFLAGS}).
+
+You should never redefine a user variable such as @code{CPPFLAGS} in
+ at file{Makefile.am}. Use @samp{automake -Woverride} to diagnose such
+mistakes. Even something like
+
+ at example
+CPPFLAGS = -DDATADIR=\"$(datadir)\" @@CPPFLAGS@@
+ at end example
+
+ at noindent
+is erroneous. Although this preserves @file{configure}'s value of
+ at code{CPPFLAGS}, the definition of @code{DATADIR} will disappear if a
+user attempts to override @code{CPPFLAGS} from the @command{make}
+command line.
+
+ at example
+AM_CPPFLAGS = -DDATADIR=\"$(datadir)\"
+ at end example
+
+ at noindent
+is all that is needed here if no per-target flags are used.
+
+You should not add options to these user variables within
+ at file{configure} either, for the same reason. Occasionally you need
+to modify these variables to perform a test, but you should reset
+their values afterwards. In contrast, it is OK to modify the
+ at samp{AM_} variables within @file{configure} if you @code{AC_SUBST}
+them, but it is rather rare that you need to do this, unless you
+really want to change the default definitions of the @samp{AM_}
+variables in all @file{Makefile}s.
+
+What we recommend is that you define extra flags in separate
+variables. For instance, you may write an Autoconf macro that computes
+a set of warning options for the C compiler, and @code{AC_SUBST} them
+in @code{WARNINGCFLAGS}; you may also have an Autoconf macro that
+determines which compiler and which linker flags should be used to
+link with library @file{libfoo}, and @code{AC_SUBST} these in
+ at code{LIBFOOCFLAGS} and @code{LIBFOOLDFLAGS}. Then, a
+ at file{Makefile.am} could use these variables as follows:
+
+ at example
+AM_CFLAGS = $(WARNINGCFLAGS)
+bin_PROGRAMS = prog1 prog2
+prog1_SOURCES = @dots{}
+prog2_SOURCES = @dots{}
+prog2_CFLAGS = $(LIBFOOCFLAGS) $(AM_CFLAGS)
+prog2_LDFLAGS = $(LIBFOOLDFLAGS)
+ at end example
+
+In this example both programs will be compiled with the flags
+substituted into @samp{$(WARNINGCFLAGS)}, and @code{prog2} will
+additionally be compiled with the flags required to link with
+ at file{libfoo}.
+
+Note that listing @code{AM_CFLAGS} in a per-target @code{CFLAGS}
+variable is a common idiom to ensure that @code{AM_CFLAGS} applies to
+every target in a @file{Makefile.in}.
+
+Using variables like this gives you full control over the ordering of
+the flags. For instance, if there is a flag in $(WARNINGCFLAGS) that
+you want to negate for a particular target, you can use something like
+ at samp{prog1_CFLAGS = $(AM_CFLAGS) -no-flag}. If all these flags had
+been forcefully appended to @code{CFLAGS}, there would be no way to
+disable one flag. Yet another reason to leave user variables to
+users.
+
+Finally, we have avoided naming the variable of the example
+ at code{LIBFOO_LDFLAGS} (with an underscore) because that would cause
+Automake to think that this is actually a per-target variable (like
+ at code{mumble_LDFLAGS}) for some non-declared @code{LIBFOO} target.
+
+ at subheading Other Variables
+
+There are other variables in Automake that follow similar principles
+to allow user options. For instance, Texinfo rules (@pxref{Texinfo})
+use @code{MAKEINFOFLAGS} and @code{AM_MAKEINFOFLAGS}. Similarly,
+DejaGnu tests (@pxref{DejaGnu Tests}) use @code{RUNTESTDEFAULTFLAGS} and
+ at code{AM_RUNTESTDEFAULTFLAGS}. The tags and ctags rules
+(@pxref{Tags}) use @code{ETAGSFLAGS}, @code{AM_ETAGSFLAGS},
+ at code{CTAGSFLAGS}, and @code{AM_CTAGSFLAGS}. Java rules
+(@pxref{Java}) use @code{JAVACFLAGS} and @code{AM_JAVACFLAGS}. None
+of these rules support per-target flags (yet).
+
+To some extent, even @code{AM_MAKEFLAGS} (@pxref{Subdirectories})
+obeys this naming scheme. The slight difference is that
+ at code{MAKEFLAGS} is passed to sub- at command{make}s implicitly by
+ at command{make} itself.
+
+However you should not think that all variables ending with
+ at code{FLAGS} follow this convention. For instance,
+ at code{DISTCHECK_CONFIGURE_FLAGS} (@pxref{Checking the Distribution}) and
+ at code{ACLOCAL_AMFLAGS} (see @ref{Rebuilding} and @ref{Local Macros}),
+are two variables that are only useful to the maintainer and have no
+user counterpart.
+
+ at code{ARFLAGS} (@pxref{A Library}) is usually defined by Automake and
+has neither @code{AM_} nor per-target cousin.
+
+Finally you should not think that the existence of a per-target
+variable implies the existance of an @code{AM_} variable or of a user
+variable. For instance, the @code{mumble_LDADD} per-target variable
+overrides the makefile-wide @code{LDADD} variable (which is not a user
+variable), and @code{mumble_LIBADD} exists only as a per-target
+variable. @xref{Program and Library Variables}.
+
+
+ at node Renamed Objects
+ at section Why are object files sometimes renamed?
+
+This happens when per-target compilation flags are used. Object
+files need to be renamed just in case they would clash with object
+files compiled from the same sources, but with different flags.
+Consider the following example.
+
+ at example
+bin_PROGRAMS = true false
+true_SOURCES = generic.c
+true_CPPFLAGS = -DEXIT_CODE=0
+false_SOURCES = generic.c
+false_CPPFLAGS = -DEXIT_CODE=1
+ at end example
+
+ at noindent
+Obviously the two programs are built from the same source, but it
+would be bad if they shared the same object, because @file{generic.o}
+cannot be built with both @samp{-DEXIT_CODE=0} @emph{and}
+ at samp{-DEXIT_CODE=1}. Therefore @command{automake} outputs rules to
+build two different objects: @file{true-generic.o} and
+ at file{false-generic.o}.
+
+ at command{automake} doesn't actually look whether source files are
+shared to decide if it must rename objects. It will just rename all
+objects of a target as soon as it sees per-target compilation flags
+used.
+
+It's OK to share object files when per-target compilation flags are not
+used. For instance, @file{true} and @file{false} will both use
+ at file{version.o} in the following example.
+
+ at example
+AM_CPPFLAGS = -DVERSION=1.0
+bin_PROGRAMS = true false
+true_SOURCES = true.c version.c
+false_SOURCES = false.c version.c
+ at end example
+
+Note that the renaming of objects is also affected by the
+ at code{_SHORTNAME} variable (@pxref{Program and Library Variables}).
+
+
+ at node Per-Object Flags
+ at section Per-Object Flags Emulation
+ at cindex Per-object flags, emulated
+
+ at display
+One of my source files needs to be compiled with different flags. How
+do I do?
+ at end display
+
+Automake supports per-program and per-library compilation flags (see
+ at ref{Program and Library Variables} and @ref{Flag Variables
+Ordering}). With this you can define compilation flags that apply to
+all files compiled for a target. For instance, in
+
+ at example
+bin_PROGRAMS = foo
+foo_SOURCES = foo.c foo.h bar.c bar.h main.c
+foo_CFLAGS = -some -flags
+ at end example
+
+ at noindent
+ at file{foo-foo.o}, @file{foo-bar.o}, and @file{foo-main.o} will all be
+compiled with @samp{-some -flags}. (If you wonder about the names of
+these object files, see @ref{Renamed Objects}.) Note that
+ at code{foo_CFLAGS} gives the flags to use when compiling all the C
+sources of the @emph{program} @code{foo}, it has nothing to do with
+ at file{foo.c} or @file{foo-foo.o} specifically.
+
+What if @file{foo.c} needs to be compiled into @file{foo.o} using some
+specific flags, that none of the other files requires? Obviously
+per-program flags are not directly applicable here. Something like
+per-object flags are expected, i.e., flags that would be used only
+when creating @file{foo-foo.o}. Automake does not support that,
+however this is easy to simulate using a library that contains only
+that object, and compiling this library with per-library flags.
+
+ at example
+bin_PROGRAMS = foo
+foo_SOURCES = bar.c bar.h main.c
+foo_CFLAGS = -some -flags
+foo_LDADD = libfoo.a
+noinst_LIBRARIES = libfoo.a
+libfoo_a_SOURCES = foo.c foo.h
+libfoo_a_CFLAGS = -some -other -flags
+ at end example
+
+Here @file{foo-bar.o} and @file{foo-main.o} will all be
+compiled with @samp{-some -flags}, while @file{libfoo_a-foo.o} will
+be compiled using @samp{-some -other -flags}. Eventually, all
+three objects will be linked to form @file{foo}.
+
+This trick can also be achieved using Libtool convenience libraries,
+for instance @samp{noinst_LTLIBRARIES = libfoo.la} (@pxref{Libtool
+Convenience Libraries}).
+
+Another tempting idea to implement per-object flags is to override the
+compile rules @command{automake} would output for these files.
+Automake will not define a rule for a target you have defined, so you
+could think about defining the @samp{foo-foo.o: foo.c} rule yourself.
+We recommend against this, because this is error prone. For instance,
+if you add such a rule to the first example, it will break the day you
+decide to remove @code{foo_CFLAGS} (because @file{foo.c} will then be
+compiled as @file{foo.o} instead of @file{foo-foo.o}, @pxref{Renamed
+Objects}). Also in order to support dependency tracking, the two
+ at file{.o}/@file{.obj} extensions, and all the other flags variables
+involved in a compilation, you will end up modifying a copy of the
+rule previously output by @command{automake} for this file. If a new
+release of Automake generates a different rule, your copy will need to
+be updated by hand.
+
+ at node Multiple Outputs
+ at section Handling Tools that Produce Many Outputs
+ at cindex multiple outputs, rules with
+ at cindex many outputs, rules with
+ at cindex rules with multiple outputs
+
+This section describes a @command{make} idiom that can be used when a
+tool produces multiple output files. It is not specific to Automake
+and can be used in ordinary @file{Makefile}s.
+
+Suppose we have a program called @command{foo} that will read one file
+called @file{data.foo} and produce two files named @file{data.c} and
+ at file{data.h}. We want to write a @file{Makefile} rule that captures
+this one-to-two dependency.
+
+The naive rule is incorrect:
+
+ at example
+# This is incorrect.
+data.c data.h: data.foo
+ foo data.foo
+ at end example
+
+ at noindent
+What the above rule really says is that @file{data.c} and
+ at file{data.h} each depend on @file{data.foo}, and can each be built by
+running @samp{foo data.foo}. In other words it is equivalent to:
+
+ at example
+# We do not want this.
+data.c: data.foo
+ foo data.foo
+data.h: data.foo
+ foo data.foo
+ at end example
+
+ at noindent
+which means that @command{foo} can be run twice. Usually it will not
+be run twice, because @command{make} implementations are smart enough
+to check for the existence of the second file after the first one has
+been built; they will therefore detect that it already exists.
+However there are a few situations where it can run twice anyway:
+
+ at itemize
+ at item
+The most worrying case is when running a parallel @command{make}. If
+ at file{data.c} and @file{data.h} are built in parallel, two @samp{foo
+data.foo} commands will run concurrently. This is harmful.
+ at item
+Another case is when the dependency (here @file{data.foo}) is
+(or depends upon) a phony target.
+ at end itemize
+
+A solution that works with parallel @command{make} but not with
+phony dependencies is the following:
+
+ at example
+data.c data.h: data.foo
+ foo data.foo
+data.h: data.c
+ at end example
+
+ at noindent
+The above rules are equivalent to
+
+ at example
+data.c: data.foo
+ foo data.foo
+data.h: data.foo data.c
+ foo data.foo
+ at end example
+
+ at noindent
+therefore a parallel @command{make} will have to serialize the builds
+of @file{data.c} and @file{data.h}, and will detect that the second is
+no longer needed once the first is over.
+
+Using this pattern is probably enough for most cases. However it does
+not scale easily to more output files (in this scheme all output files
+must be totally ordered by the dependency relation), so we will
+explore a more complicated solution.
+
+Another idea is to write the following:
+
+ at example
+# There is still a problem with this one.
+data.c: data.foo
+ foo data.foo
+data.h: data.c
+ at end example
+
+ at noindent
+The idea is that @samp{foo data.foo} is run only when @file{data.c}
+needs to be updated, but we further state that @file{data.h} depends
+upon @file{data.c}. That way, if @file{data.h} is required and
+ at file{data.foo} is out of date, the dependency on @file{data.c} will
+trigger the build.
+
+This is almost perfect, but suppose we have built @file{data.h} and
+ at file{data.c}, and then we erase @file{data.h}. Then, running
+ at samp{make data.h} will not rebuild @file{data.h}. The above rules
+just state that @file{data.c} must be up-to-date with respect to
+ at file{data.foo}, and this is already the case.
+
+What we need is a rule that forces a rebuild when @file{data.h} is
+missing. Here it is:
+
+ at example
+data.c: data.foo
+ foo data.foo
+data.h: data.c
+## Recover from the removal of $@@
+ @@if test -f $@@; then :; else \
+ rm -f data.c; \
+ $(MAKE) $(AM_MAKEFLAGS) data.c; \
+ fi
+ at end example
+
+The above scheme can be extended to handle more outputs and more
+inputs. One of the outputs is selected to serve as a witness to the
+successful completion of the command, it depends upon all inputs, and
+all other outputs depend upon it. For instance, if @command{foo}
+should additionally read @file{data.bar} and also produce
+ at file{data.w} and @file{data.x}, we would write:
+
+ at example
+data.c: data.foo data.bar
+ foo data.foo data.bar
+data.h data.w data.x: data.c
+## Recover from the removal of $@@
+ @@if test -f $@@; then :; else \
+ rm -f data.c; \
+ $(MAKE) $(AM_MAKEFLAGS) data.c; \
+ fi
+ at end example
+
+However there are now three minor problems in this setup. One is related
+to the timestamp ordering of @file{data.h}, @file{data.w},
+ at file{data.x}, and @file{data.c}. Another one is a race condition
+if a parallel @command{make} attempts to run multiple instances of the
+recover block at once. Finally, the recursive rule breaks @samp{make -n}
+when run with GNU @command{make} (as well as some other @command{make}
+implementations), as it may remove @file{data.h} even when it should not
+(@pxref{MAKE Variable, , How the @code{MAKE} Variable Works, make,
+The GNU Make Manual}).
+
+Let us deal with the first problem. @command{foo} outputs four files,
+but we do not know in which order these files are created. Suppose
+that @file{data.h} is created before @file{data.c}. Then we have a
+weird situation. The next time @command{make} is run, @file{data.h}
+will appear older than @file{data.c}, the second rule will be
+triggered, a shell will be started to execute the @samp{if at dots{}fi}
+command, but actually it will just execute the @code{then} branch,
+that is: nothing. In other words, because the witness we selected is
+not the first file created by @command{foo}, @command{make} will start
+a shell to do nothing each time it is run.
+
+A simple riposte is to fix the timestamps when this happens.
+
+ at example
+data.c: data.foo data.bar
+ foo data.foo data.bar
+data.h data.w data.x: data.c
+ @@if test -f $@@; then \
+ touch $@@; \
+ else \
+## Recover from the removal of $@@
+ rm -f data.c; \
+ $(MAKE) $(AM_MAKEFLAGS) data.c; \
+ fi
+ at end example
+
+Another solution is to use a different and dedicated file as witness,
+rather than using any of @command{foo}'s outputs.
+
+ at example
+data.stamp: data.foo data.bar
+ @@rm -f data.tmp
+ @@touch data.tmp
+ foo data.foo data.bar
+ @@mv -f data.tmp $@@
+data.c data.h data.w data.x: data.stamp
+## Recover from the removal of $@@
+ @@if test -f $@@; then :; else \
+ rm -f data.stamp; \
+ $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
+ fi
+ at end example
+
+ at file{data.tmp} is created before @command{foo} is run, so it has a
+timestamp older than output files output by @command{foo}. It is then
+renamed to @file{data.stamp} after @command{foo} has run, because we
+do not want to update @file{data.stamp} if @command{foo} fails.
+
+This solution still suffers from the second problem: the race
+condition in the recover rule. If, after a successful build, a user
+erases @file{data.c} and @file{data.h}, and runs @samp{make -j}, then
+ at command{make} may start both recover rules in parallel. If the two
+instances of the rule execute @samp{$(MAKE) $(AM_MAKEFLAGS)
+data.stamp} concurrently the build is likely to fail (for instance, the
+two rules will create @file{data.tmp}, but only one can rename it).
+
+Admittedly, such a weird situation does not arise during ordinary
+builds. It occurs only when the build tree is mutilated. Here
+ at file{data.c} and @file{data.h} have been explicitly removed without
+also removing @file{data.stamp} and the other output files.
+ at code{make clean; make} will always recover from these situations even
+with parallel makes, so you may decide that the recover rule is solely
+to help non-parallel make users and leave things as-is. Fixing this
+requires some locking mechanism to ensure only one instance of the
+recover rule rebuilds @file{data.stamp}. One could imagine something
+along the following lines.
+
+ at example
+data.c data.h data.w data.x: data.stamp
+## Recover from the removal of $@@
+ @@if test -f $@@; then :; else \
+ trap 'rm -rf data.lock data.stamp' 1 2 13 15; \
+## mkdir is a portable test-and-set
+ if mkdir data.lock 2>/dev/null; then \
+## This code is being executed by the first process.
+ rm -f data.stamp; \
+ $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
+ result=$$?; rm -rf data.lock; exit $$result; \
+ else \
+## This code is being executed by the follower processes.
+## Wait until the first process is done.
+ while test -d data.lock; do sleep 1; done; \
+## Succeed if and only if the first process succeeded.
+ test -f data.stamp; \
+ fi; \
+ fi
+ at end example
+
+Using a dedicated witness, like @file{data.stamp}, is very handy when
+the list of output files is not known beforehand. As an illustration,
+consider the following rules to compile many @file{*.el} files into
+ at file{*.elc} files in a single command. It does not matter how
+ at code{ELFILES} is defined (as long as it is not empty: empty targets
+are not accepted by POSIX).
+
+ at example
+ELFILES = one.el two.el three.el @dots{}
+ELCFILES = $(ELFILES:=c)
+
+elc-stamp: $(ELFILES)
+ @@rm -f elc-temp
+ @@touch elc-temp
+ $(elisp_comp) $(ELFILES)
+ @@mv -f elc-temp $@@
+
+$(ELCFILES): elc-stamp
+ @@if test -f $@@; then :; else \
+## Recover from the removal of $@@
+ trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
+ if mkdir elc-lock 2>/dev/null; then \
+## This code is being executed by the first process.
+ rm -f elc-stamp; \
+ $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
+ rmdir elc-lock; \
+ else \
+## This code is being executed by the follower processes.
+## Wait until the first process is done.
+ while test -d elc-lock; do sleep 1; done; \
+## Succeed if and only if the first process succeeded.
+ test -f elc-stamp; exit $$?; \
+ at c $$
+ fi; \
+ fi
+ at end example
+
+These solutions all still suffer from the third problem, namely that
+they break the promise that @samp{make -n} should not cause any actual
+changes to the tree. For those solutions that do not create lock files,
+it is possible to split the recover rules into two separate recipe
+commands, one of which does all work but the recursion, and the
+other invokes the recursive @samp{$(MAKE)}. The solutions involving
+locking could act upon the contents of the @samp{MAKEFLAGS} variable,
+but parsing that portably is not easy (@pxref{The Make Macro MAKEFLAGS,,,
+autoconf, The Autoconf Manual}). Here is an example:
+
+ at example
+ELFILES = one.el two.el three.el @dots{}
+ELCFILES = $(ELFILES:=c)
+
+elc-stamp: $(ELFILES)
+ @@rm -f elc-temp
+ @@touch elc-temp
+ $(elisp_comp) $(ELFILES)
+ @@mv -f elc-temp $@@
+
+$(ELCFILES): elc-stamp
+## Recover from the removal of $@@
+ @@dry=; for f in x $$MAKEFLAGS; do \
+ case $$f in \
+ *=*|--*);; \
+ *n*) dry=:;; \
+ esac; \
+ done; \
+ if test -f $@@; then :; else \
+ $$dry trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
+ if $$dry mkdir elc-lock 2>/dev/null; then \
+## This code is being executed by the first process.
+ $$dry rm -f elc-stamp; \
+ $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
+ $$dry rmdir elc-lock; \
+ else \
+## This code is being executed by the follower processes.
+## Wait until the first process is done.
+ while test -d elc-lock && test -z "$$dry"; do \
+ at c $$
+ sleep 1; \
+ done; \
+## Succeed if and only if the first process succeeded.
+ $$dry test -f elc-stamp; exit $$?; \
+ fi; \
+ fi
+ at end example
+
+For completeness it should be noted that GNU @command{make} is able to
+express rules with multiple output files using pattern rules
+(@pxref{Pattern Examples, , Pattern Rule Examples, make, The GNU Make
+Manual}). We do not discuss pattern rules here because they are not
+portable, but they can be convenient in packages that assume GNU
+ at command{make}.
+
+
+ at node Hard-Coded Install Paths
+ at section Installing to Hard-Coded Locations
+
+ at display
+My package needs to install some configuration file. I tried to use
+the following rule, but @samp{make distcheck} fails. Why?
+
+ at example
+# Do not do this.
+install-data-local:
+ $(INSTALL_DATA) $(srcdir)/afile $(DESTDIR)/etc/afile
+ at end example
+ at end display
+
+ at display
+My package needs to populate the installation directory of another
+package at install-time. I can easily compute that installation
+directory in @file{configure}, but if I install files therein,
+ at samp{make distcheck} fails. How else should I do?
+ at end display
+
+These two setups share their symptoms: @samp{make distcheck} fails
+because they are installing files to hard-coded paths. In the later
+case the path is not really hard-coded in the package, but we can
+consider it to be hard-coded in the system (or in whichever tool that
+supplies the path). As long as the path does not use any of the
+standard directory variables (@samp{$(prefix)}, @samp{$(bindir)},
+ at samp{$(datadir)}, etc.), the effect will be the same:
+user-installations are impossible.
+
+As a (non-root) user who wants to install a package, you usually have no
+right to install anything in @file{/usr} or @file{/usr/local}. So you
+do something like @samp{./configure --prefix ~/usr} to install a
+package in your own @file{~/usr} tree.
+
+If a package attempts to install something to some hard-coded path
+(e.g., @file{/etc/afile}), regardless of this @option{--prefix} setting,
+then the installation will fail. @samp{make distcheck} performs such
+a @option{--prefix} installation, hence it will fail too.
+
+Now, there are some easy solutions.
+
+The above @code{install-data-local} example for installing
+ at file{/etc/afile} would be better replaced by
+
+ at example
+sysconf_DATA = afile
+ at end example
+
+ at noindent
+by default @code{sysconfdir} will be @samp{$(prefix)/etc}, because
+this is what the GNU Standards require. When such a package is
+installed on an FHS compliant system, the installer will have to set
+ at samp{--sysconfdir=/etc}. As the maintainer of the package you
+should not be concerned by such site policies: use the appropriate
+standard directory variable to install your files so that the installer
+can easily redefine these variables to match their site conventions.
+
+Installing files that should be used by another package is slightly
+more involved. Let's take an example and assume you want to install
+a shared library that is a Python extension module. If you ask Python
+where to install the library, it will answer something like this:
+
+ at example
+% @kbd{python -c 'from distutils import sysconfig;
+ print sysconfig.get_python_lib(1,0)'}
+/usr/lib/python2.5/site-packages
+ at end example
+
+If you indeed use this absolute path to install your shared library,
+non-root users will not be able to install the package, hence
+distcheck fails.
+
+Let's do better. The @samp{sysconfig.get_python_lib()} function
+actually accepts a third argument that will replace Python's
+installation prefix.
+
+ at example
+% @kbd{python -c 'from distutils import sysconfig;
+ print sysconfig.get_python_lib(1,0,"$@{exec_prefix@}")'}
+$@{exec_prefix@}/lib/python2.5/site-packages
+ at end example
+
+You can also use this new path. If you do
+ at itemize @bullet
+ at item
+root users can install your package with the same @option{--prefix}
+as Python (you get the behavior of the previous attempt)
+
+ at item
+non-root users can install your package too, they will have the
+extension module in a place that is not searched by Python but they
+can work around this using environment variables (and if you installed
+scripts that use this shared library, it's easy to tell Python were to
+look in the beginning of your script, so the script works in both
+cases).
+ at end itemize
+
+The @code{AM_PATH_PYTHON} macro uses similar commands to define
+ at samp{$(pythondir)} and @samp{$(pyexecdir)} (@pxref{Python}).
+
+Of course not all tools are as advanced as Python regarding that
+substitution of @var{prefix}. So another strategy is to figure the
+part of the installation directory that must be preserved. For
+instance, here is how @code{AM_PATH_LISPDIR} (@pxref{Emacs Lisp})
+computes @samp{$(lispdir)}:
+
+ at example
+$EMACS -batch -q -eval '(while load-path
+ (princ (concat (car load-path) "\n"))
+ (setq load-path (cdr load-path)))' >conftest.out
+lispdir=`sed -n
+ -e 's,/$,,'
+ -e '/.*\/lib\/x*emacs\/site-lisp$/@{
+ s,.*/lib/\(x*emacs/site-lisp\)$,$@{libdir@}/\1,;p;q;
+ @}'
+ -e '/.*\/share\/x*emacs\/site-lisp$/@{
+ s,.*/share/\(x*emacs/site-lisp\),$@{datarootdir@}/\1,;p;q;
+ @}'
+ conftest.out`
+ at end example
+
+I.e., it just picks the first directory that looks like
+ at file{*/lib/*emacs/site-lisp} or @file{*/share/*emacs/site-lisp} in
+the search path of emacs, and then substitutes @samp{$@{libdir@}} or
+ at samp{$@{datadir@}} appropriately.
+
+The emacs case looks complicated because it processes a list and
+expects two possible layouts, otherwise it's easy, and the benefits for
+non-root users are really worth the extra @command{sed} invocation.
+
+
+ at node Debugging Make Rules
+ at section Debugging Make Rules
+ at cindex debugging rules
+ at cindex rules, debugging
+
+The rules and dependency trees generated by @command{automake} can get
+rather complex, and leave the developer head-scratching when things
+don't work as expected. Besides the debug options provided by the
+ at command{make} command (@pxref{Options Summary,,, make, The GNU Make
+Manual}), here's a couple of further hints for debugging makefiles
+generated by @command{automake} effectively:
+
+ at itemize
+ at item
+If less verbose output has been enabled in the package with the
+ at samp{silent-rules} option (@pxref{Options}), you can use
+ at code{make V=1} to see the commands being executed.
+ at item
+ at code{make -n} can help show what would be done without actually doing
+it. Note however, that this will @emph{still execute} commands prefixed
+with @samp{+}, and, when using GNU @command{make}, commands that contain
+the strings @samp{$(MAKE)} or @samp{$@{MAKE@}} (@pxref{Instead of
+Execution,,, make, The GNU Make Manual}).
+Typically, this is helpful to show what recursive rules would do, but it
+means that, in your own rules, you should not mix such recursion with
+actions that change any files. at footnote{Automake's @samp{dist} and
+ at samp{distcheck} rules had a bug in this regard in that they created
+directories even with @option{-n}, but this has been fixed in Automake
+1.11.} Furthermore, note that GNU @command{make} will update
+prerequisites for the @file{Makefile} file itself even with @option{-n}
+(@pxref{Remaking Makefiles,,, make, The GNU Make Manual}).
+ at item
+ at code{make SHELL="/bin/bash -vx"} can help debug complex rules.
+ at xref{The Make Macro SHELL,,, autoconf, The Autoconf Manual}, for some
+portability quirks associated with this construct.
+ at item
+ at code{echo 'print: ; @@echo "$(VAR)"' | make -f Makefile -f - print}
+can be handy to examine the expanded value of variables. You may need
+to use a target other than @samp{print} if that is already used or a
+file with that name exists.
+ at item
+ at url{http://bashdb.sourceforge.net/@/remake/} provides a modified
+GNU @command{make} command called @command{remake} that copes with
+complex GNU @command{make}-specific Makefiles and allows to trace
+execution, examine variables, and call rules interactively, much like
+a debugger.
+ at end itemize
+
+
+ at node Reporting Bugs
+ at section Reporting Bugs
+
+Most nontrivial software has bugs. Automake is no exception. Although
+we cannot promise we can or will fix a bug, and we might not even agree
+that it is a bug, we want to hear about problems you encounter. Often we
+agree they are bugs and want to fix them.
+
+To make it possible for us to fix a bug, please report it. In order to
+do so effectively, it helps to know when and how to do it.
+
+Before reporting a bug, it is a good idea to see if it is already known.
+You can look at the @uref{http://debbugs.gnu.org/, GNU Bug Tracker}
+and the @uref{http://lists.gnu.org/@/archive/@/html/@/bug-automake/,
+bug-automake mailing list archives} for previous bug reports. We
+previously used a
+ at uref{http://sourceware.org/@/cgi-bin/@/gnatsweb.pl?database=automake,
+Gnats database} for bug tracking, so some bugs might have been reported
+there already. Please do not use it for new bug reports, however.
+
+If the bug is not already known, it should be reported. It is very
+important to report bugs in a way that is useful and efficient. For
+this, please familiarize yourself with
+ at uref{http://www.chiark.greenend.org.uk/@/~sgtatham/@/bugs.html, How to
+Report Bugs Effectively} and
+ at uref{http://catb.org/@/~esr/@/faqs/@/smart-questions.html, How to Ask
+Questions the Smart Way}. This helps you and developers to save time
+which can then be spent on fixing more bugs and implementing more
+features.
+
+For a bug report, a feature request or other suggestions, please send
+email to @email{@value{PACKAGE_BUGREPORT}}. This will then open a new
+bug in the @uref{http://debbugs.gnu.org/@/automake, bug tracker}. Be
+sure to include the versions of Autoconf and Automake that you use.
+Ideally, post a minimal @file{Makefile.am} and @file{configure.ac} that
+reproduces the problem you encounter. If you have encountered test
+suite failures, please attach the @file{tests/test-suite.log} file.
+
+
+ at node History
+ at chapter History of Automake
+
+This chapter presents various aspects of the history of Automake. The
+exhausted reader can safely skip it; this will be more of interest to
+nostalgic people, or to those curious to learn about the evolution of
+Automake.
+
+ at menu
+* Timeline:: The Automake story.
+* Dependency Tracking Evolution:: Evolution of Automatic Dependency Tracking
+* Releases:: Statistics about Automake Releases
+ at end menu
+
+ at node Timeline
+ at section Timeline
+
+ at table @asis
+ at item 1994-09-19 First CVS commit.
+
+If we can trust the CVS repository, David J. at tie{}MacKenzie (djm) started
+working on Automake (or AutoMake, as it was spelt then) this Monday.
+
+The first version of the @command{automake} script looks as follows.
+
+ at example
+#!/bin/sh
+
+status=0
+
+for makefile
+do
+ if test ! -f $@{makefile@}.am; then
+ echo "automake: $@{makefile@}.am: No such honkin' file"
+ status=1
+ continue
+ fi
+
+ exec 4> $@{makefile@}.in
+
+done
+ at end example
+
+From this you can already see that Automake will be about reading
+ at file{*.am} file and producing @file{*.in} files. You cannot see
+anything else, but if you also know that David is the one who created
+Autoconf two years before you can guess the rest.
+
+Several commits follow, and by the end of the day Automake is
+reported to work for GNU fileutils and GNU m4.
+
+The modus operandi is the one that is still used today: variable
+assignments in @file{Makefile.am} files trigger injections of
+precanned @file{Makefile} fragments into the generated
+ at file{Makefile.in}. The use of @file{Makefile} fragments was inspired
+by the 4.4BSD @command{make} and include files, however Automake aims
+to be portable and to conform to the GNU standards for @file{Makefile}
+variables and targets.
+
+At this point, the most recent release of Autoconf is version 1.11,
+and David is preparing to release Autoconf 2.0 in late October. As a
+matter of fact, he will barely touch Automake after September.
+
+ at item 1994-11-05 David MacKenzie's last commit.
+
+At this point Automake is a 200 line portable shell script, plus 332
+lines of @file{Makefile} fragments. In the @file{README}, David
+states his ambivalence between ``portable shell'' and ``more
+appropriate language'':
+
+ at quotation
+I wrote it keeping in mind the possibility of it becoming an Autoconf
+macro, so it would run at configure-time. That would slow
+configuration down a bit, but allow users to modify the Makefile.am
+without needing to fetch the AutoMake package. And, the Makefile.in
+files wouldn't need to be distributed. But all of AutoMake would. So
+I might reimplement AutoMake in Perl, m4, or some other more
+appropriate language.
+ at end quotation
+
+Automake is described as ``an experimental Makefile generator''.
+There is no documentation. Adventurous users are referred to the
+examples and patches needed to use Automake with GNU m4 1.3, fileutils
+3.9, time 1.6, and development versions of find and indent.
+
+These examples seem to have been lost. However at the time of writing
+(10 years later in September, 2004) the FSF still distributes a
+package that uses this version of Automake: check out GNU termutils
+2.0.
+
+ at item 1995-11-12 Tom Tromey's first commit.
+
+After one year of inactivity, Tom Tromey takes over the package.
+Tom was working on GNU cpio back then, and doing this just for fun,
+having trouble finding a project to contribute to. So while hacking
+he wanted to bring the @file{Makefile.in} up to GNU standards. This
+was hard, and one day he saw Automake on @url{ftp://alpha.gnu.org/},
+grabbed it and tried it out.
+
+Tom didn't talk to djm about it until later, just to make sure he
+didn't mind if he made a release. He did a bunch of early releases to
+the Gnits folks.
+
+Gnits was (and still is) totally informal, just a few GNU friends who
+Fran@,cois Pinard knew, who were all interested in making a common
+infrastructure for GNU projects, and shared a similar outlook on how
+to do it. So they were able to make some progress. It came along
+with Autoconf and extensions thereof, and then Automake from David and
+Tom (who were both gnitsians). One of their ideas was to write a
+document paralleling the GNU standards, that was more strict in some
+ways and more detailed. They never finished the GNITS standards, but
+the ideas mostly made their way into Automake.
+
+ at item 1995-11-23 Automake 0.20
+
+Besides introducing automatic dependency tracking (@pxref{Dependency
+Tracking Evolution}), this version also supplies a 9-page manual.
+
+At this time @command{aclocal} and @code{AM_INIT_AUTOMAKE} did not
+exist, so many things had to be done by hand. For instance, here is
+what a configure.in (this is the former name of the
+ at file{configure.ac} we use today) must contain in order to use
+Automake 0.20:
+
+ at example
+PACKAGE=cpio
+VERSION=2.3.911
+AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE")
+AC_DEFINE_UNQUOTED(VERSION, "$VERSION")
+AC_SUBST(PACKAGE)
+AC_SUBST(VERSION)
+AC_ARG_PROGRAM
+AC_PROG_INSTALL
+ at end example
+
+(Today all of the above is achieved by @code{AC_INIT} and
+ at code{AM_INIT_AUTOMAKE}.)
+
+Here is how programs are specified in @file{Makefile.am}:
+
+ at example
+PROGRAMS = hello
+hello_SOURCES = hello.c
+ at end example
+
+This looks pretty much like what we do today, except the
+ at code{PROGRAMS} variable has no directory prefix specifying where
+ at file{hello} should be installed: all programs are installed in
+ at samp{$(bindir)}. @code{LIBPROGRAMS} can be used to specify programs
+that must be built but not installed (it is called
+ at code{noinst_PROGRAMS} nowadays).
+
+Programs can be built conditionally using @code{AC_SUBST}itutions:
+
+ at example
+PROGRAMS = @@progs@@
+AM_PROGRAMS = foo bar baz
+ at end example
+
+(@code{AM_PROGRAMS} has since then been renamed to
+ at code{EXTRA_PROGRAMS}.)
+
+Similarly scripts, static libraries, and data can be built and installed
+using the @code{LIBRARIES}, @code{SCRIPTS}, and @code{DATA} variables.
+However @code{LIBRARIES} were treated a bit specially in that Automake
+did automatically supply the @file{lib} and @file{.a} prefixes.
+Therefore to build @file{libcpio.a}, one had to write
+
+ at example
+LIBRARIES = cpio
+cpio_SOURCES = ...
+ at end example
+
+Extra files to distribute must be listed in @code{DIST_OTHER} (the
+ancestor of @code{EXTRA_DIST}). Also extra directories that are to be
+distributed should appear in @code{DIST_SUBDIRS}, but the manual
+describes this as a temporary ugly hack (today extra directories should
+also be listed in @code{EXTRA_DIST}, and @code{DIST_SUBDIRS} is used
+for another purpose, @pxref{Conditional Subdirectories}).
+
+ at item 1995-11-26 Automake 0.21
+
+In less time than it takes to cook a frozen pizza, Tom rewrites
+Automake using Perl. At this time Perl 5 is only one year old, and
+Perl 4.036 is in use at many sites. Supporting several Perl versions
+has been a source of problems through the whole history of Automake.
+
+If you never used Perl 4, imagine Perl 5 without objects, without
+ at samp{my} variables (only dynamically scoped @samp{local} variables),
+without function prototypes, with function calls that needs to be
+prefixed with @samp{&}, etc. Traces of this old style can still be
+found in today's @command{automake}.
+
+ at item 1995-11-28 Automake 0.22
+ at itemx 1995-11-29 Automake 0.23
+
+Bug fixes.
+
+ at item 1995-12-08 Automake 0.24
+ at itemx 1995-12-10 Automake 0.25
+
+Releases are raining. 0.24 introduces the uniform naming scheme we
+use today, i.e., @code{bin_PROGRAMS} instead of @code{PROGRAMS},
+ at code{noinst_LIBRARIES} instead of @code{LIBLIBRARIES}, etc. (However
+ at code{EXTRA_PROGRAMS} does not exist yet, @code{AM_PROGRAMS} is still
+in use; and @code{TEXINFOS} and @code{MANS} still have no directory
+prefixes.) Adding support for prefixes like that was one of the major
+ideas in @command{automake}; it has lasted pretty well.
+
+AutoMake is renamed to Automake (Tom seems to recall it was Fran@,cois
+Pinard's doing).
+
+0.25 fixes a Perl 4 portability bug.
+
+ at item 1995-12-18 Jim Meyering starts using Automake in GNU Textutils.
+ at item 1995-12-31 Fran@,cois Pinard starts using Automake in GNU tar.
+
+ at item 1996-01-03 Automake 0.26
+ at itemx 1996-01-03 Automake 0.27
+
+Of the many changes and suggestions sent by Fran@,cois Pinard and
+included in 0.26, perhaps the most important is the advice that to
+ease customization a user rule or variable definition should always
+override an Automake rule or definition.
+
+Gordon Matzigkeit and Jim Meyering are two other early contributors
+that have been sending fixes.
+
+0.27 fixes yet another Perl 4 portability bug.
+
+ at item 1996-01-13 Automake 0.28
+
+Automake starts scanning @file{configure.in} for @code{LIBOBJS}
+support. This is an important step because until this version
+Automake only knew about the @file{Makefile.am}s it processed.
+ at file{configure.in} was Autoconf's world and the link between Autoconf
+and Automake had to be done by the @file{Makefile.am} author. For
+instance, if @file{config.h} was generated by @file{configure}, it was the
+package maintainer's responsibility to define the @code{CONFIG_HEADER}
+variable in each @file{Makefile.am}.
+
+Succeeding releases will rely more and more on scanning
+ at file{configure.in} to better automate the Autoconf integration.
+
+0.28 also introduces the @code{AUTOMAKE_OPTIONS} variable and the
+ at option{--gnu} and @option{--gnits} options, the latter being stricter.
+
+ at item 1996-02-07 Automake 0.29
+
+Thanks to @file{configure.in} scanning, @code{CONFIG_HEADER} is gone,
+and rebuild rules for @file{configure}-generated file are
+automatically output.
+
+ at code{TEXINFOS} and @code{MANS} converted to the uniform naming
+scheme.
+
+ at item 1996-02-24 Automake 0.30
+
+The test suite is born. It contains 9 tests. From now on test cases
+will be added pretty regularly (@pxref{Releases}), and this proved to
+be really helpful later on.
+
+ at code{EXTRA_PROGRAMS} finally replaces @code{AM_PROGRAMS}.
+
+All the third-party Autoconf macros, written mostly by Fran@,cois
+Pinard (and later Jim Meyering), are distributed in Automake's
+hand-written @file{aclocal.m4} file. Package maintainers are expected
+to extract the necessary macros from this file. (In previous versions
+you had to copy and paste them from the manual...)
+
+ at item 1996-03-11 Automake 0.31
+
+The test suite in 0.30 was run via a long @code{check-local} rule. Upon
+Ulrich Drepper's suggestion, 0.31 makes it an Automake rule output
+whenever the @code{TESTS} variable is defined.
+
+ at code{DIST_OTHER} is renamed to @code{EXTRA_DIST}, and the @code{check_}
+prefix is introduced. The syntax is now the same as today.
+
+ at item 1996-03-15 Gordon Matzigkeit starts writing libtool.
+
+ at item 1996-04-27 Automake 0.32
+
+ at code{-hook} targets are introduced; an idea from Dieter Baron.
+
+ at file{*.info} files, which were output in the build directory are
+now built in the source directory, because they are distributed. It
+seems these files like to move back and forth as that will happen
+again in future versions.
+
+ at item 1996-05-18 Automake 0.33
+
+Gord Matzigkeit's main two contributions:
+
+ at itemize
+ at item very preliminary libtool support
+ at item the distcheck rule
+ at end itemize
+
+Although they were very basic at this point, these are probably
+among the top features for Automake today.
+
+Jim Meyering also provides the infamous @code{jm_MAINTAINER_MODE},
+since then renamed to @code{AM_MAINTAINER_MODE} and abandoned by its
+author (@pxref{maintainer-mode}).
+
+ at item 1996-05-28 Automake 1.0
+
+After only six months of heavy development, the @command{automake} script is
+3134 lines long, plus 973 lines of @file{Makefile} fragments. The
+package has 30 pages of documentation, and 38 test cases.
+ at file{aclocal.m4} contains 4 macros.
+
+From now on and until version 1.4, new releases will occur at a rate
+of about one a year. 1.1 did not exist, actually 1.1b to 1.1p have
+been the name of beta releases for 1.2. This is the first time
+Automake uses suffix letters to designate beta releases, a habit that
+lasts.
+
+ at item 1996-10-10 Kevin Dalley packages Automake 1.0 for Debian GNU/Linux.
+
+ at item 1996-11-26 David J. at tie{}MacKenzie releases Autoconf 2.12.
+
+Between June and October, the Autoconf development is almost stalled.
+Roland McGrath has been working at the beginning of the year. David
+comes back in November to release 2.12, but he won't touch Autoconf
+anymore after this year, and Autoconf then really stagnates. The
+desolate Autoconf @file{ChangeLog} for 1997 lists only 7 commits.
+
+ at item 1997-02-28 @email{automake@@gnu.ai.mit.edu} list alive
+
+The mailing list is announced as follows:
+ at smallexample
+I've created the "automake" mailing list. It is
+"automake@@gnu.ai.mit.edu". Administrivia, as always, to
+automake-request@@gnu.ai.mit.edu.
+
+The charter of this list is discussion of automake, autoconf, and
+other configuration/portability tools (e.g., libtool). It is expected
+that discussion will range from pleas for help all the way up to
+patches.
+
+This list is archived on the FSF machines. Offhand I don't know if
+you can get the archive without an account there.
+
+This list is open to anybody who wants to join. Tell all your
+friends!
+-- Tom Tromey
+ at end smallexample
+
+Before that people were discussing Automake privately, on the Gnits
+mailing list (which is not public either), and less frequently on
+ at code{gnu.misc.discuss}.
+
+ at code{gnu.ai.mit.edu} is now @code{gnu.org}, in case you never
+noticed. The archives of the early years of the
+ at code{automake@@gnu.org} list have been lost, so today it is almost
+impossible to find traces of discussions that occurred before 1999.
+This has been annoying more than once, as such discussions can be
+useful to understand the rationale behind a piece of uncommented code
+that was introduced back then.
+
+ at item 1997-06-22 Automake 1.2
+
+Automake developments continues, and more and more new Autoconf macros
+are required. Distributing them in @file{aclocal.m4} and requiring
+people to browse this file to extract the relevant macros becomes
+uncomfortable. Ideally, some of them should be contributed to
+Autoconf so that they can be used directly, however Autoconf is
+currently inactive. Automake 1.2 consequently introduces
+ at command{aclocal} (@command{aclocal} was actually started on
+1996-07-28), a tool that automatically constructs an @file{aclocal.m4}
+file from a repository of third-party macros. Because Autoconf has
+stalled, Automake also becomes a kind of repository for such
+third-party macros, even macros completely unrelated to Automake (for
+instance macros that fix broken Autoconf macros).
+
+The 1.2 release contains 20 macros, including the
+ at code{AM_INIT_AUTOMAKE} macro that simplifies the creation of
+ at file{configure.in}.
+
+Libtool is fully supported using @code{*_LTLIBRARIES}.
+
+The missing script is introduced by Fran@,cois Pinard; it is meant to be
+a better solution than @code{AM_MAINTAINER_MODE}
+(@pxref{maintainer-mode}).
+
+Conditionals support was implemented by Ian Lance Taylor. At the
+time, Tom and Ian were working on an internal project at Cygnus. They
+were using ILU, which is pretty similar to CORBA at . They wanted to
+integrate ILU into their build, which was all @file{configure}-based,
+and Ian thought that adding conditionals to @command{automake} was
+simpler than doing all the work in @file{configure} (which was the
+standard at the time). So this was actually funded by Cygnus.
+
+This very useful but tricky feature will take a lot of time to
+stabilize. (At the time this text is written, there are still
+primaries that have not been updated to support conditional
+definitions in Automake 1.9.)
+
+The @command{automake} script has almost doubled: 6089 lines of Perl,
+plus 1294 lines of @file{Makefile} fragments.
+
+ at item 1997-07-08 Gordon Matzigkeit releases Libtool 1.0.
+
+ at item 1998-04-05 Automake 1.3
+
+This is a small advance compared to 1.2.
+It adds support for assembly, and preliminary support for Java.
+
+Perl 5.004_04 is out, but fixes to support Perl 4 are still
+regularly submitted whenever Automake breaks it.
+
+ at item 1998-09-06 @code{sourceware.cygnus.com} is on-line.
+
+Sourceware was setup by Jason Molenda to host open source projects.
+
+ at item 1998-09-19 Automake CVS repository moved to @code{sourceware.cygnus.com}
+ at itemx 1998-10-26 @code{sourceware.cygnus.com} announces it hosts Automake:
+Automake is now hosted on @code{sourceware.cygnus.com}. It has a
+publicly accessible CVS repository. This CVS repository is a copy of
+the one Tom was using on his machine, which in turn is based on
+a copy of the CVS repository of David MacKenzie. This is why we still
+have to full source history. (Automake was on Sourceware until 2007-10-29,
+when it moved to a git repository on @code{savannah.gnu.org},
+but the Sourceware host had been renamed to @code{sources.redhat.com}.)
+
+The oldest file in the administrative directory of the CVS repository
+that was created on Sourceware is dated 1998-09-19, while the
+announcement that @command{automake} and @command{autoconf} had joined
+ at command{sourceware} was made on 1998-10-26. They were among the
+first projects to be hosted there.
+
+The heedful reader will have noticed Automake was exactly 4 years old
+on 1998-09-19.
+
+ at item 1999-01-05 Ben Elliston releases Autoconf 2.13.
+
+ at item 1999-01-14 Automake 1.4
+
+This release adds support for Fortran 77 and for the @code{include}
+statement. Also, @samp{+=} assignments are introduced, but it is
+still quite easy to fool Automake when mixing this with conditionals.
+
+These two releases, Automake 1.4 and Autoconf 2.13 make a duo that
+will be used together for years.
+
+ at command{automake} is 7228 lines, plus 1591 lines of Makefile
+fragment, 20 macros (some 1.3 macros were finally contributed back to
+Autoconf), 197 test cases, and 51 pages of documentation.
+
+ at item 1999-03-27 The @code{user-dep-branch} is created on the CVS repository.
+
+This implements a new dependency tracking schemed that should be
+able to handle automatic dependency tracking using any compiler (not
+just gcc) and any make (not just GNU @command{make}). In addition,
+the new scheme should be more reliable than the old one, as
+dependencies are generated on the end user's machine. Alexandre Oliva
+creates depcomp for this purpose.
+
+ at xref{Dependency Tracking Evolution}, for more details about the
+evolution of automatic dependency tracking in Automake.
+
+ at item 1999-11-21 The @code{user-dep-branch} is merged into the main trunk.
+
+This was a huge problem since we also had patches going in on the
+trunk. The merge took a long time and was very painful.
+
+ at item 2000-05-10
+
+Since September 1999 and until 2003, Akim Demaille will be zealously
+revamping Autoconf.
+
+ at quotation
+I think the next release should be called "3.0".@*
+Let's face it: you've basically rewritten autoconf.@*
+Every weekend there are 30 new patches.@*
+I don't see how we could call this "2.15" with a straight face.@*
+-- Tom Tromey on @email{autoconf@@gnu.org}
+ at end quotation
+
+Actually Akim works like a submarine: he will pile up patches while he
+works off-line during the weekend, and flush them in batch when he
+resurfaces on Monday.
+
+ at item 2001-01-24
+
+On this Wednesday, Autoconf 2.49c, the last beta before Autoconf 2.50
+is out, and Akim has to find something to do during his week-end :)
+
+ at item 2001-01-28
+
+Akim sends a batch of 14 patches to @email{automake@@gnu.org}.
+
+ at quotation
+Aiieeee! I was dreading the day that the Demaillator turned his
+sights on automake at dots{} and now it has arrived! -- Tom Tromey
+ at end quotation
+
+It's only the beginning: in two months he will send 192 patches. Then
+he would slow down so Tom can catch up and review all this. Initially
+Tom actually read all these patches, then he probably trustingly
+answered OK to most of them, and finally gave up and let Akim apply
+whatever he wanted. There was no way to keep up with that patch rate.
+
+ at quotation
+Anyway the patch below won't apply since it predates Akim's
+sourcequake; I have yet to figure where the relevant passage has
+been moved :) -- Alexandre Duret-Lutz
+ at end quotation
+
+All these patches were sent to and discussed on
+ at email{automake@@gnu.org}, so subscribed users were literally drowning in
+technical mails. Eventually, the @email{automake-patches@@gnu.org}
+mailing list was created in May.
+
+Year after year, Automake had drifted away from its initial design:
+construct @file{Makefile.in} by assembling various @file{Makefile}
+fragments. In 1.4, lots of @file{Makefile} rules are being emitted at
+various places in the @command{automake} script itself; this does not
+help ensuring a consistent treatment of these rules (for instance
+making sure that user-defined rules override Automake's own rules).
+One of Akim's goal was moving all these hard-coded rules to separate
+ at file{Makefile} fragments, so the logic could be centralized in a
+ at file{Makefile} fragment processor.
+
+Another significant contribution of Akim is the interface with the
+``trace'' feature of Autoconf. The way to scan @file{configure.in} at
+this time was to read the file and grep the various macro of interest
+to Automake. Doing so could break in many unexpected ways; @command{automake}
+could miss some definition (for instance @samp{AC_SUBST([$1], [$2])}
+where the arguments are known only when M4 is run), or conversely it
+could detect some macro that was not expanded (because it is called
+conditionally). In the CVS version of Autoconf, Akim had implemented
+the @option{--trace} option, which provides accurate information about
+where macros are actually called and with what arguments. Akim will
+equip Automake with a second @file{configure.in} scanner that uses
+this @option{--trace} interface. Since it was not sensible to drop the
+Autoconf 2.13 compatibility yet, this experimental scanner was only
+used when an environment variable was set, the traditional
+grep-scanner being still the default.
+
+ at item 2001-04-25 Gary V. at tie{}Vaughan releases Libtool 1.4
+
+It has been more than two years since Automake 1.4, CVS Automake has
+suffered lot's of heavy changes and still is not ready for release.
+Libtool 1.4 had to be distributed with a patch against Automake 1.4.
+
+ at item 2001-05-08 Automake 1.4-p1
+ at itemx 2001-05-24 Automake 1.4-p2
+
+Gary V. at tie{}Vaughan, the principal Libtool maintainer, makes a ``patch
+release'' of Automake:
+
+ at quotation
+The main purpose of this release is to have a stable automake
+which is compatible with the latest stable libtool.
+ at end quotation
+
+The release also contains obvious fixes for bugs in Automake 1.4,
+some of which were reported almost monthly.
+
+ at item 2001-05-21 Akim Demaille releases Autoconf 2.50
+
+ at item 2001-06-07 Automake 1.4-p3
+ at itemx 2001-06-10 Automake 1.4-p4
+ at itemx 2001-07-15 Automake 1.4-p5
+
+Gary continues his patch-release series. These also add support for
+some new Autoconf 2.50 idioms. Essentially, Autoconf now advocates
+ at file{configure.ac} over @file{configure.in}, and it introduces a new
+syntax for @code{AC_OUTPUT}ing files.
+
+ at item 2001-08-23 Automake 1.5
+
+A major and long-awaited release, that comes more than two years after
+1.4. It brings many changes, among which:
+ at itemize
+ at item The new dependency tracking scheme that uses @command{depcomp}.
+Aside from the improvement on the dependency tracking itself
+(@pxref{Dependency Tracking Evolution}), this also streamlines the use
+of @command{automake}-generated @file{Makefile.in}s as the @file{Makefile.in}s
+used during development are now the same as those used in
+distributions. Before that the @file{Makefile.in}s generated for
+maintainers required GNU @command{make} and GCC, they were different
+from the portable @file{Makefile} generated for distribution; this was
+causing some confusion.
+
+ at item Support for per-target compilation flags.
+
+ at item Support for reference to files in subdirectories in most
+ at file{Makefile.am} variables.
+
+ at item Introduction of the @code{dist_}, @code{nodist_}, and @code{nobase_}
+prefixes.
+ at item Perl 4 support is finally dropped.
+ at end itemize
+
+1.5 did break several packages that worked with 1.4. Enough so that
+Linux distributions could not easily install the new Automake version
+without breaking many of the packages for which they had to run
+ at command{automake}.
+
+Some of these breakages were effectively bugs that would eventually be
+fixed in the next release. However, a lot of damage was caused by
+some changes made deliberately to render Automake stricter on some
+setup we did consider bogus. For instance, @samp{make distcheck} was
+improved to check that @samp{make uninstall} did remove all the files
+ at samp{make install} installed, that @samp{make distclean} did not omit
+some file, and that a VPATH build would work even if the source
+directory was read-only. Similarly, Automake now rejects multiple
+definitions of the same variable (because that would mix very badly
+with conditionals), and @samp{+=} assignments with no previous
+definition. Because these changes all occurred suddenly after 1.4 had
+been established for more than two years, it hurt users.
+
+To make matter worse, meanwhile Autoconf (now at version 2.52) was
+facing similar troubles, for similar reasons.
+
+ at item 2002-03-05 Automake 1.6
+
+This release introduced versioned installation (@pxref{API
+Versioning}). This was mainly pushed by Havoc Pennington, taking the
+GNOME source tree as motive: due to incompatibilities between the
+autotools it's impossible for the GNOME packages to switch to Autoconf
+2.53 and Automake 1.5 all at once, so they are currently stuck with
+Autoconf 2.13 and Automake 1.4.
+
+The idea was to call this version @file{automake-1.6}, call all its
+bug-fix versions identically, and switch to @file{automake-1.7} for
+the next release that adds new features or changes some rules. This
+scheme implies maintaining a bug-fix branch in addition to the
+development trunk, which means more work from the maintainer, but
+providing regular bug-fix releases proved to be really worthwhile.
+
+Like 1.5, 1.6 also introduced a bunch of incompatibilities, intentional or
+not. Perhaps the more annoying was the dependence on the newly
+released Autoconf 2.53. Autoconf seemed to have stabilized enough
+since its explosive 2.50 release and included changes required to fix
+some bugs in Automake. In order to upgrade to Automake 1.6, people
+now had to upgrade Autoconf too; for some packages it was no picnic.
+
+While versioned installation helped people to upgrade, it also
+unfortunately allowed people not to upgrade. At the time of writing,
+some Linux distributions are shipping packages for Automake 1.4, 1.5,
+1.6, 1.7, 1.8, and 1.9. Most of these still install 1.4 by default.
+Some distribution also call 1.4 the ``stable'' version, and present
+``1.9'' as the development version; this does not really makes sense
+since 1.9 is way more solid than 1.4. All this does not help the
+newcomer.
+
+ at item 2002-04-11 Automake 1.6.1
+
+1.6, and the upcoming 1.4-p6 release were the last release by Tom.
+This one and those following will be handled by Alexandre
+Duret-Lutz. Tom is still around, and will be there until about 1.7,
+but his interest into Automake is drifting away towards projects like
+ at command{gcj}.
+
+Alexandre has been using Automake since 2000, and started to
+contribute mostly on Akim's incitement (Akim and Alexandre have been
+working in the same room from 1999 to 2002). In 2001 and 2002 he had
+a lot of free time to enjoy hacking Automake.
+
+ at item 2002-06-14 Automake 1.6.2
+
+ at item 2002-07-28 Automake 1.6.3
+ at itemx 2002-07-28 Automake 1.4-p6
+
+Two releases on the same day. 1.6.3 is a bug-fix release.
+
+Tom Tromey backported the versioned installation mechanism on the 1.4
+branch, so that Automake 1.6.x and Automake 1.4-p6 could be installed
+side by side. Another request from the GNOME folks.
+
+ at item 2002-09-25 Automake 1.7
+
+This release switches to the new @file{configure.ac} scanner Akim
+was experimenting in 1.5.
+
+ at item 2002-10-16 Automake 1.7.1
+ at itemx 2002-12-06 Automake 1.7.2
+ at itemx 2003-02-20 Automake 1.7.3
+ at itemx 2003-04-23 Automake 1.7.4
+ at itemx 2003-05-18 Automake 1.7.5
+ at itemx 2003-07-10 Automake 1.7.6
+ at itemx 2003-09-07 Automake 1.7.7
+ at itemx 2003-10-07 Automake 1.7.8
+
+Many bug-fix releases. 1.7 lasted because the development version
+(upcoming 1.8) was suffering some major internal revamping.
+
+ at item 2003-10-26 Automake on screen
+
+Episode 49, `Repercussions', in the third season of the `Alias' TV
+show is first aired.
+
+Marshall, one of the characters, is working on a computer virus that he
+has to modify before it gets into the wrong hands or something like
+that. The screenshots you see do not show any program code, they show
+a @file{Makefile.in} @code{generated by automake}...
+
+ at item 2003-11-09 Automake 1.7.9
+
+ at item 2003-12-10 Automake 1.8
+
+The most striking update is probably that of @command{aclocal}.
+
+ at command{aclocal} now uses @code{m4_include} in the produced
+ at file{aclocal.m4} when the included macros are already distributed
+with the package (an idiom used in many packages), which reduces code
+duplication. Many people liked that, but in fact this change was
+really introduced to fix a bug in rebuild rules: @file{Makefile.in}
+must be rebuilt whenever a dependency of @file{configure} changes, but
+all the @file{m4} files included in @file{aclocal.m4} where unknown
+from @command{automake}. Now @command{automake} can just trace the
+ at code{m4_include}s to discover the dependencies.
+
+ at command{aclocal} also starts using the @option{--trace} Autoconf option
+in order to discover used macros more accurately. This will turn out
+to be very tricky (later releases will improve this) as people had
+devised many ways to cope with the limitation of previous
+ at command{aclocal} versions, notably using handwritten
+ at code{m4_include}s: @command{aclocal} must make sure not to redefine a
+rule that is already included by such statement.
+
+Automake also has seen its guts rewritten. Although this rewriting
+took a lot of efforts, it is only apparent to the users in that some
+constructions previously disallowed by the implementation now work
+nicely. Conditionals, Locations, Variable and Rule definitions,
+Options: these items on which Automake works have been rewritten as
+separate Perl modules, and documented.
+
+ at itemx 2004-01-11 Automake 1.8.1
+ at itemx 2004-01-12 Automake 1.8.2
+ at itemx 2004-03-07 Automake 1.8.3
+ at itemx 2004-04-25 Automake 1.8.4
+ at itemx 2004-05-16 Automake 1.8.5
+
+ at item 2004-07-28 Automake 1.9
+
+This release tries to simplify the compilation rules it outputs to
+reduce the size of the Makefile. The complaint initially come from
+the libgcj developers. Their @file{Makefile.in} generated with
+Automake 1.4 and custom build rules (1.4 did not support compiled
+Java) is 250KB at . The one generated by 1.8 was over 9MB@! 1.9 gets it
+down to 1.2MB at .
+
+Aside from this it contains mainly minor changes and bug-fixes.
+
+ at itemx 2004-08-11 Automake 1.9.1
+ at itemx 2004-09-19 Automake 1.9.2
+
+Automake has ten years. This chapter of the manual was initially
+written for this occasion.
+
+ at itemx 2007-10-29 Automake repository moves to @code{savannah.gnu.org} and uses
+git as primary repository.
+
+ at end table
+
+ at node Dependency Tracking Evolution
+ at section Dependency Tracking in Automake
+
+Over the years Automake has deployed three different dependency
+tracking methods. Each method, including the current one, has had
+flaws of various sorts. Here we lay out the different dependency
+tracking methods, their flaws, and their fixes. We conclude with
+recommendations for tool writers, and by indicating future directions
+for dependency tracking work in Automake.
+
+ at menu
+* First Take on Dependencies:: Precomputed dependency tracking
+* Dependencies As Side Effects:: Update at developer compile time
+* Dependencies for the User:: Update at user compile time
+* Techniques for Dependencies:: Alternative approaches
+* Recommendations for Tool Writers:: What tool writers can do to help
+* Future Directions for Dependencies:: Languages Automake does not know
+ at end menu
+
+ at node First Take on Dependencies
+ at subsection First Take on Dependency Tracking
+ at unnumberedsubsubsec Description
+
+Our first attempt at automatic dependency tracking was based on the
+method recommended by GNU @command{make}. (@pxref{Automatic
+Prerequisites, , Generating Prerequisites Automatically, make, The GNU
+make Manual})
+
+This version worked by precomputing dependencies ahead of time. For
+each source file, it had a special @file{.P} file that held the
+dependencies. There was a rule to generate a @file{.P} file by
+invoking the compiler appropriately. All such @file{.P} files were
+included by the @file{Makefile}, thus implicitly becoming dependencies
+of @file{Makefile}.
+
+ at unnumberedsubsubsec Bugs
+
+This approach had several critical bugs.
+
+ at itemize
+ at item
+The code to generate the @file{.P} file relied on @command{gcc}.
+(A limitation, not technically a bug.)
+ at item
+The dependency tracking mechanism itself relied on GNU @command{make}.
+(A limitation, not technically a bug.)
+ at item
+Because each @file{.P} file was a dependency of @file{Makefile}, this
+meant that dependency tracking was done eagerly by @command{make}.
+For instance, @samp{make clean} would cause all the dependency files
+to be updated, and then immediately removed. This eagerness also
+caused problems with some configurations; if a certain source file
+could not be compiled on a given architecture for some reason,
+dependency tracking would fail, aborting the entire build.
+ at item
+As dependency tracking was done as a pre-pass, compile times were
+doubled--the compiler had to be run twice per source file.
+ at item
+ at samp{make dist} re-ran @command{automake} to generate a
+ at file{Makefile} that did not have automatic dependency tracking (and
+that was thus portable to any version of @command{make}). In order to
+do this portably, Automake had to scan the dependency files and remove
+any reference that was to a source file not in the distribution.
+This process was error-prone. Also, if @samp{make dist} was run in an
+environment where some object file had a dependency on a source file
+that was only conditionally created, Automake would generate a
+ at file{Makefile} that referred to a file that might not appear in the
+end user's build. A special, hacky mechanism was required to work
+around this.
+ at end itemize
+
+ at unnumberedsubsubsec Historical Note
+
+The code generated by Automake is often inspired by the
+ at file{Makefile} style of a particular author. In the case of the first
+implementation of dependency tracking, I believe the impetus and
+inspiration was Jim Meyering. (I could be mistaken. If you know
+otherwise feel free to correct me.)
+
+ at node Dependencies As Side Effects
+ at subsection Dependencies As Side Effects
+ at unnumberedsubsubsec Description
+
+The next refinement of Automake's automatic dependency tracking scheme
+was to implement dependencies as side effects of the compilation.
+This was aimed at solving the most commonly reported problems with the
+first approach. In particular we were most concerned with eliminating
+the weird rebuilding effect associated with make clean.
+
+In this approach, the @file{.P} files were included using the
+ at code{-include} command, which let us create these files lazily. This
+avoided the @samp{make clean} problem.
+
+We only computed dependencies when a file was actually compiled. This
+avoided the performance penalty associated with scanning each file
+twice. It also let us avoid the other problems associated with the
+first, eager, implementation. For instance, dependencies would never
+be generated for a source file that was not compilable on a given
+architecture (because it in fact would never be compiled).
+
+ at unnumberedsubsubsec Bugs
+
+ at itemize
+ at item
+This approach also relied on the existence of @command{gcc} and GNU
+ at command{make}. (A limitation, not technically a bug.)
+ at item
+Dependency tracking was still done by the developer, so the problems
+from the first implementation relating to massaging of dependencies by
+ at samp{make dist} were still in effect.
+ at item
+This implementation suffered from the ``deleted header file'' problem.
+Suppose a lazily-created @file{.P} file includes a dependency on a
+given header file, like this:
+
+ at example
+maude.o: maude.c something.h
+ at end example
+
+Now suppose that you remove @file{something.h} and update @file{maude.c}
+so that this include is no longer needed. If you run @command{make},
+you will get an error because there is no way to create
+ at file{something.h}.
+
+We fixed this problem in a later release by further massaging the
+output of @command{gcc} to include a dummy dependency for each header
+file.
+ at end itemize
+
+ at node Dependencies for the User
+ at subsection Dependencies for the User
+ at unnumberedsubsubsec Description
+
+The bugs associated with @samp{make dist}, over time, became a real
+problem. Packages using Automake were being built on a large number
+of platforms, and were becoming increasingly complex. Broken
+dependencies were distributed in ``portable'' @file{Makefile.in}s,
+leading to user complaints. Also, the requirement for @command{gcc}
+and GNU @command{make} was a constant source of bug reports. The next
+implementation of dependency tracking aimed to remove these problems.
+
+We realized that the only truly reliable way to automatically track
+dependencies was to do it when the package itself was built. This
+meant discovering a method portable to any version of make and any
+compiler. Also, we wanted to preserve what we saw as the best point
+of the second implementation: dependency computation as a side effect
+of compilation.
+
+In the end we found that most modern make implementations support some
+form of include directive. Also, we wrote a wrapper script that let
+us abstract away differences between dependency tracking methods for
+compilers. For instance, some compilers cannot generate dependencies
+as a side effect of compilation. In this case we simply have the
+script run the compiler twice. Currently our wrapper script
+(@command{depcomp}) knows about twelve different compilers (including
+a "compiler" that simply invokes @command{makedepend} and then the
+real compiler, which is assumed to be a standard Unix-like C compiler
+with no way to do dependency tracking).
+
+ at unnumberedsubsubsec Bugs
+
+ at itemize
+ at item
+Running a wrapper script for each compilation slows down the build.
+ at item
+Many users don't really care about precise dependencies.
+ at item
+This implementation, like every other automatic dependency tracking
+scheme in common use today (indeed, every one we've ever heard of),
+suffers from the ``duplicated new header'' bug.
+
+This bug occurs because dependency tracking tools, such as the
+compiler, only generate dependencies on the successful opening of a
+file, and not on every probe.
+
+Suppose for instance that the compiler searches three directories for
+a given header, and that the header is found in the third directory.
+If the programmer erroneously adds a header file with the same name to
+the first directory, then a clean rebuild from scratch could fail
+(suppose the new header file is buggy), whereas an incremental rebuild
+will succeed.
+
+What has happened here is that people have a misunderstanding of what
+a dependency is. Tool writers think a dependency encodes information
+about which files were read by the compiler. However, a dependency
+must actually encode information about what the compiler tried to do.
+
+This problem is not serious in practice. Programmers typically do not
+use the same name for a header file twice in a given project. (At
+least, not in C or C++. This problem may be more troublesome in
+Java.) This problem is easy to fix, by modifying dependency
+generators to record every probe, instead of every successful open.
+
+ at item
+Since Automake generates dependencies as a side effect of compilation,
+there is a bootstrapping problem when header files are generated by
+running a program. The problem is that, the first time the build is
+done, there is no way by default to know that the headers are
+required, so make might try to run a compilation for which the headers
+have not yet been built.
+
+This was also a problem in the previous dependency tracking implementation.
+
+The current fix is to use @code{BUILT_SOURCES} to list built headers
+(@pxref{Sources}). This causes them to be built before any other
+build rules are run. This is unsatisfactory as a general solution,
+however in practice it seems sufficient for most actual programs.
+ at end itemize
+
+This code is used since Automake 1.5.
+
+In GCC 3.0, we managed to convince the maintainers to add special
+command-line options to help Automake more efficiently do its job. We
+hoped this would let us avoid the use of a wrapper script when
+Automake's automatic dependency tracking was used with @command{gcc}.
+
+Unfortunately, this code doesn't quite do what we want. In
+particular, it removes the dependency file if the compilation fails;
+we'd prefer that it instead only touch the file in any way if the
+compilation succeeds.
+
+Nevertheless, since Automake 1.7, when a recent @command{gcc} is
+detected at @command{configure} time, we inline the
+dependency-generation code and do not use the @command{depcomp}
+wrapper script. This makes compilations faster for those using this
+compiler (probably our primary user base). The counterpart is that
+because we have to encode two compilation rules in @file{Makefile}
+(with or without @command{depcomp}), the produced @file{Makefile}s are
+larger.
+
+ at node Techniques for Dependencies
+ at subsection Techniques for Computing Dependencies
+
+There are actually several ways for a build tool like Automake to
+cause tools to generate dependencies.
+
+ at table @asis
+ at item @command{makedepend}
+This was a commonly-used method in the past. The idea is to run a
+special program over the source and have it generate dependency
+information. Traditional implementations of @command{makedepend} are
+not completely precise; ordinarily they were conservative and
+discovered too many dependencies.
+ at item The tool
+An obvious way to generate dependencies is to simply write the tool so
+that it can generate the information needed by the build tool. This is
+also the most portable method. Many compilers have an option to
+generate dependencies. Unfortunately, not all tools provide such an
+option.
+ at item The file system
+It is possible to write a special file system that tracks opens,
+reads, writes, etc, and then feed this information back to the build
+tool. @command{clearmake} does this. This is a very powerful
+technique, as it doesn't require cooperation from the
+tool. Unfortunately it is also very difficult to implement and also
+not practical in the general case.
+ at item @code{LD_PRELOAD}
+Rather than use the file system, one could write a special library to
+intercept @code{open} and other syscalls. This technique is also quite
+powerful, but unfortunately it is not portable enough for use in
+ at command{automake}.
+ at end table
+
+ at node Recommendations for Tool Writers
+ at subsection Recommendations for Tool Writers
+
+We think that every compilation tool ought to be able to generate
+dependencies as a side effect of compilation. Furthermore, at least
+while @command{make}-based tools are nearly universally in use (at
+least in the free software community), the tool itself should generate
+dummy dependencies for header files, to avoid the deleted header file
+bug. Finally, the tool should generate a dependency for each probe,
+instead of each successful file open, in order to avoid the duplicated
+new header bug.
+
+ at node Future Directions for Dependencies
+ at subsection Future Directions for Dependencies
+
+Currently, only languages and compilers understood by Automake can
+have dependency tracking enabled. We would like to see if it is
+practical (and worthwhile) to let this support be extended by the user
+to languages unknown to Automake.
+
+ at node Releases
+ at section Release Statistics
+
+The following table (inspired by @samp{perlhist(1)}) quantifies the
+evolution of Automake using these metrics:
+
+ at table @asis
+ at item Date, Rel
+The date and version of the release.
+ at item am
+The number of lines of the @command{automake} script.
+ at item acl
+The number of lines of the @command{aclocal} script.
+ at item pm
+The number of lines of the @command{Perl} supporting modules.
+ at item @file{*.am}
+The number of lines of the @file{Makefile} fragments. The number in
+parentheses is the number of files.
+ at item m4
+The number of lines (and files) of Autoconf macros.
+ at item doc
+The number of pages of the documentation (the Postscript version).
+ at item t
+The number of test cases in the test suite. Of those, the number in
+parentheses is the number of generated test cases.
+ at end table
+
+ at multitable {8888-88-88} {8.8-p8} {8888} {8888} {8888} {8888 (88)} {8888 (88)} {888} {888 (88)}
+ at headitem Date @tab Rel @tab am @tab acl @tab pm @tab @file{*.am} @tab m4 @tab doc @tab t
+ at item 1994-09-19 @tab CVS @tab 141 @tab @tab @tab 299 (24) @tab @tab @tab
+ at item 1994-11-05 @tab CVS @tab 208 @tab @tab @tab 332 (28) @tab @tab @tab
+ at item 1995-11-23 @tab 0.20 @tab 533 @tab @tab @tab 458 (35) @tab @tab 9 @tab
+ at item 1995-11-26 @tab 0.21 @tab 613 @tab @tab @tab 480 (36) @tab @tab 11 @tab
+ at item 1995-11-28 @tab 0.22 @tab 1116 @tab @tab @tab 539 (38) @tab @tab 12 @tab
+ at item 1995-11-29 @tab 0.23 @tab 1240 @tab @tab @tab 541 (38) @tab @tab 12 @tab
+ at item 1995-12-08 @tab 0.24 @tab 1462 @tab @tab @tab 504 (33) @tab @tab 14 @tab
+ at item 1995-12-10 @tab 0.25 @tab 1513 @tab @tab @tab 511 (37) @tab @tab 15 @tab
+ at item 1996-01-03 @tab 0.26 @tab 1706 @tab @tab @tab 438 (36) @tab @tab 16 @tab
+ at item 1996-01-03 @tab 0.27 @tab 1706 @tab @tab @tab 438 (36) @tab @tab 16 @tab
+ at item 1996-01-13 @tab 0.28 @tab 1964 @tab @tab @tab 934 (33) @tab @tab 16 @tab
+ at item 1996-02-07 @tab 0.29 @tab 2299 @tab @tab @tab 936 (33) @tab @tab 17 @tab
+ at item 1996-02-24 @tab 0.30 @tab 2544 @tab @tab @tab 919 (32) @tab 85 (1) @tab 20 @tab 9
+ at item 1996-03-11 @tab 0.31 @tab 2877 @tab @tab @tab 919 (32) @tab 85 (1) @tab 29 @tab 17
+ at item 1996-04-27 @tab 0.32 @tab 3058 @tab @tab @tab 921 (31) @tab 85 (1) @tab 30 @tab 26
+ at item 1996-05-18 @tab 0.33 @tab 3110 @tab @tab @tab 926 (31) @tab 105 (1) @tab 30 @tab 35
+ at item 1996-05-28 @tab 1.0 @tab 3134 @tab @tab @tab 973 (32) @tab 105 (1) @tab 30 @tab 38
+ at item 1997-06-22 @tab 1.2 @tab 6089 @tab 385 @tab @tab 1294 (36) @tab 592 (20) @tab 37 @tab 126
+ at item 1998-04-05 @tab 1.3 @tab 6415 @tab 422 @tab @tab 1470 (39) @tab 741 (23) @tab 39 @tab 156
+ at item 1999-01-14 @tab 1.4 @tab 7240 @tab 426 @tab @tab 1591 (40) @tab 734 (20) @tab 51 @tab 197
+ at item 2001-05-08 @tab 1.4-p1 @tab 7251 @tab 426 @tab @tab 1591 (40) @tab 734 (20) @tab 51 @tab 197
+ at item 2001-05-24 @tab 1.4-p2 @tab 7268 @tab 439 @tab @tab 1591 (40) @tab 734 (20) @tab 49 @tab 197
+ at item 2001-06-07 @tab 1.4-p3 @tab 7312 @tab 439 @tab @tab 1591 (40) @tab 734 (20) @tab 49 @tab 197
+ at item 2001-06-10 @tab 1.4-p4 @tab 7321 @tab 439 @tab @tab 1591 (40) @tab 734 (20) @tab 49 @tab 198
+ at item 2001-07-15 @tab 1.4-p5 @tab 7228 @tab 426 @tab @tab 1596 (40) @tab 734 (20) @tab 51 @tab 198
+ at item 2001-08-23 @tab 1.5 @tab 8016 @tab 475 @tab 600 @tab 2654 (39) @tab 1166 (29) @tab 63 @tab 327
+ at item 2002-03-05 @tab 1.6 @tab 8465 @tab 475 @tab 1136 @tab 2732 (39) @tab 1603 (27) @tab 66 @tab 365
+ at item 2002-04-11 @tab 1.6.1 @tab 8544 @tab 475 @tab 1136 @tab 2741 (39) @tab 1603 (27) @tab 66 @tab 372
+ at item 2002-06-14 @tab 1.6.2 @tab 8575 @tab 475 @tab 1136 @tab 2800 (39) @tab 1609 (27) @tab 67 @tab 386
+ at item 2002-07-28 @tab 1.6.3 @tab 8600 @tab 475 @tab 1153 @tab 2809 (39) @tab 1609 (27) @tab 67 @tab 391
+ at item 2002-07-28 @tab 1.4-p6 @tab 7332 @tab 455 @tab @tab 1596 (40) @tab 735 (20) @tab 49 @tab 197
+ at item 2002-09-25 @tab 1.7 @tab 9189 @tab 471 @tab 1790 @tab 2965 (39) @tab 1606 (28) @tab 73 @tab 430
+ at item 2002-10-16 @tab 1.7.1 @tab 9229 @tab 475 @tab 1790 @tab 2977 (39) @tab 1606 (28) @tab 73 @tab 437
+ at item 2002-12-06 @tab 1.7.2 @tab 9334 @tab 475 @tab 1790 @tab 2988 (39) @tab 1606 (28) @tab 77 @tab 445
+ at item 2003-02-20 @tab 1.7.3 @tab 9389 @tab 475 @tab 1790 @tab 3023 (39) @tab 1651 (29) @tab 84 @tab 448
+ at item 2003-04-23 @tab 1.7.4 @tab 9429 @tab 475 @tab 1790 @tab 3031 (39) @tab 1644 (29) @tab 85 @tab 458
+ at item 2003-05-18 @tab 1.7.5 @tab 9429 @tab 475 @tab 1790 @tab 3033 (39) @tab 1645 (29) @tab 85 @tab 459
+ at item 2003-07-10 @tab 1.7.6 @tab 9442 @tab 475 @tab 1790 @tab 3033 (39) @tab 1660 (29) @tab 85 @tab 461
+ at item 2003-09-07 @tab 1.7.7 @tab 9443 @tab 475 @tab 1790 @tab 3041 (39) @tab 1660 (29) @tab 90 @tab 467
+ at item 2003-10-07 @tab 1.7.8 @tab 9444 @tab 475 @tab 1790 @tab 3041 (39) @tab 1660 (29) @tab 90 @tab 468
+ at item 2003-11-09 @tab 1.7.9 @tab 9444 @tab 475 @tab 1790 @tab 3048 (39) @tab 1660 (29) @tab 90 @tab 468
+ at item 2003-12-10 @tab 1.8 @tab 7171 @tab 585 @tab 7730 @tab 3236 (39) @tab 1666 (31) @tab 104 @tab 521
+ at item 2004-01-11 @tab 1.8.1 @tab 7217 @tab 663 @tab 7726 @tab 3287 (39) @tab 1686 (31) @tab 104 @tab 525
+ at item 2004-01-12 @tab 1.8.2 @tab 7217 @tab 663 @tab 7726 @tab 3288 (39) @tab 1686 (31) @tab 104 @tab 526
+ at item 2004-03-07 @tab 1.8.3 @tab 7214 @tab 686 @tab 7735 @tab 3303 (39) @tab 1695 (31) @tab 111 @tab 530
+ at item 2004-04-25 @tab 1.8.4 @tab 7214 @tab 686 @tab 7736 @tab 3310 (39) @tab 1701 (31) @tab 112 @tab 531
+ at item 2004-05-16 @tab 1.8.5 @tab 7240 @tab 686 @tab 7736 @tab 3299 (39) @tab 1701 (31) @tab 112 @tab 533
+ at item 2004-07-28 @tab 1.9 @tab 7508 @tab 715 @tab 7794 @tab 3352 (40) @tab 1812 (32) @tab 115 @tab 551
+ at item 2004-08-11 @tab 1.9.1 @tab 7512 @tab 715 @tab 7794 @tab 3354 (40) @tab 1812 (32) @tab 115 @tab 552
+ at item 2004-09-19 @tab 1.9.2 @tab 7512 @tab 715 @tab 7794 @tab 3354 (40) @tab 1812 (32) @tab 132 @tab 554
+ at item 2004-11-01 @tab 1.9.3 @tab 7507 @tab 718 @tab 7804 @tab 3354 (40) @tab 1812 (32) @tab 134 @tab 556
+ at item 2004-12-18 @tab 1.9.4 @tab 7508 @tab 718 @tab 7856 @tab 3361 (40) @tab 1811 (32) @tab 140 @tab 560
+ at item 2005-02-13 @tab 1.9.5 @tab 7523 @tab 719 @tab 7859 @tab 3373 (40) @tab 1453 (32) @tab 142 @tab 562
+ at item 2005-07-10 @tab 1.9.6 @tab 7539 @tab 699 @tab 7867 @tab 3400 (40) @tab 1453 (32) @tab 144 @tab 570
+ at item 2006-10-15 @tab 1.10 @tab 7859 @tab 1072 @tab 8024 @tab 3512 (40) @tab 1496 (34) @tab 172 @tab 604
+ at item 2008-01-19 @tab 1.10.1 @tab 7870 @tab 1089 @tab 8025 @tab 3520 (40) @tab 1499 (34) @tab 173 @tab 617
+ at item 2008-11-23 @tab 1.10.2 @tab 7882 @tab 1089 @tab 8027 @tab 3540 (40) @tab 1509 (34) @tab 176 @tab 628
+ at item 2009-05-17 @tab 1.11 @tab 8721 @tab 1092 @tab 8289 @tab 4164 (42) @tab 1714 (37) @tab 181 @tab 732 (20)
+ at item 2009-12-07 @tab 1.10.3 @tab 7892 @tab 1089 @tab 8027 @tab 3566 (40) @tab 1535 (34) @tab 174 @tab 636
+ at item 2009-12-07 @tab 1.11.1 @tab 8722 @tab 1092 @tab 8292 @tab 4162 (42) @tab 1730 (37) @tab 181 @tab 739 (20)
+ at item 2011-12-21 @tab 1.11.2 @tab 8822 @tab 1112 @tab 8330 @tab 4223 (42) @tab 1821 (38) @tab 189 @tab 915 (22)
+ at item 2012-02-01 @tab 1.11.3 @tab 8790 @tab 1068 @tab 8453 @tab 4280 (42) @tab 1852 (38) @tab 190 @tab 932 (22)
+ at end multitable
+
+
+ at c ========================================================== Appendices
+
+ at page
+ at node Copying This Manual
+ at appendix Copying This Manual
+
+ at menu
+* GNU Free Documentation License:: License for copying this manual
+ at end menu
+
+ at node GNU Free Documentation License
+ at appendixsec GNU Free Documentation License
+ at include fdl.texi
+
+ at page
+ at node Indices
+ at appendix Indices
+
+ at menu
+* Macro Index:: Index of Autoconf macros
+* Variable Index:: Index of Makefile variables
+* General Index:: General index
+ at end menu
+
+ at node Macro Index
+ at appendixsec Macro Index
+
+ at printindex fn
+
+ at node Variable Index
+ at appendixsec Variable Index
+
+ at printindex vr
+
+ at node General Index
+ at appendixsec General Index
+
+ at printindex cp
+
+
+ at bye
+
+ at c LocalWords: texinfo setfilename settitle setchapternewpage texi direntry
+ at c LocalWords: dircategory in's aclocal ifinfo titlepage Tromey vskip pt sp
+ at c LocalWords: filll defcodeindex ov cv op tr syncodeindex fn cp vr ifnottex
+ at c LocalWords: dir Automake's ac Dist Gnits gnits cygnus dfn Autoconf's pxref
+ at c LocalWords: cindex Autoconf autoconf perl samp cvs dist trindex SUBST foo
+ at c LocalWords: xs emph FIXME ref vindex pkglibdir pkgincludedir pkgdatadir mt
+ at c LocalWords: pkg libdir cpio bindir sbindir rmt pax sbin zar zardir acindex
+ at c LocalWords: HTML htmldir html noinst TEXINFOS nodist nobase strudel CFLAGS
+ at c LocalWords: libmumble CC YFLAGS ansi knr itemx de fication config url comp
+ at c LocalWords: depcomp elisp sh mdate mkinstalldirs mkdir py tex dvi ps pdf
+ at c LocalWords: ylwrap zardoz INIT gettext acinclude mv FUNCS LIBOBJS LDADD fr
+ at c LocalWords: uref featureful dnl src LINGUAS es ko nl pl sl sv PROG ISC doc
+ at c LocalWords: POSIX STDC fcntl FUNC ALLOCA blksize struct stat intl po chmod
+ at c LocalWords: ChangeLog SUBDIRS gettextize gpl testdata getopt INTLLIBS cpp
+ at c LocalWords: localedir datadir DLOCALEDIR DEXIT CPPFLAGS autoreconf opindex
+ at c LocalWords: AUX var symlink deps Wno Wnone package's aclocal's distclean
+ at c LocalWords: ltmain xref LIBSOURCE LIBSOURCES LIBOBJ MEMCMP vs RANLIB CXX
+ at c LocalWords: LDFLAGS LIBTOOL libtool XTRA LIBS gettext's acdir APIVERSION
+ at c LocalWords: dirlist noindent usr MULTILIB multilib Multilibs TIOCGWINSZ sc
+ at c LocalWords: GWINSZ termios SRCDIR tarball bzip LISPDIR lispdir XEmacs CCAS
+ at c LocalWords: emacsen MicroEmacs CCASFLAGS UX GCJ gcj GCJFLAGS posix DMALLOC
+ at c LocalWords: dmalloc ldmalloc REGEX regex rx DEPDIR DEP DEFUN aclocaldir fi
+ at c LocalWords: mymacro myothermacro AMFLAGS autopoint autogen libtoolize yum
+ at c LocalWords: autoheader README MAKEFLAGS subdir Inetutils sync COND endif
+ at c LocalWords: Miller's installable includedir inc pkgdata EXEEXT libexec bsd
+ at c LocalWords: pkglib libexecdir prog libcpio cpio's dlopen dlpreopen linux
+ at c LocalWords: subsubsection OBJEXT esac lib LTLIBRARIES liblob LIBADD AR ar
+ at c LocalWords: ARFLAGS cru ing maude libgettext lo LTLIBOBJS rpath SGI PRE yy
+ at c LocalWords: libmaude CCLD CXXFLAGS FFLAGS LFLAGS OBJCFLAGS RFLAGS DEFS cc
+ at c LocalWords: SHORTNAME vtable srcdir nostdinc basename yxx cxx ll lxx gdb
+ at c LocalWords: lexers yymaxdepth maxdepth yyparse yylex yyerror yylval lval
+ at c LocalWords: yychar yydebug yypact yyr yydef def yychk chk yypgo pgo yyact
+ at c LocalWords: yyexca exca yyerrflag errflag yynerrs nerrs yyps yypv pv yys
+ at c LocalWords: yystate yytmp tmp yyv yyval val yylloc lloc yyreds yytoks toks
+ at c LocalWords: yylhs yylen yydefred yydgoto yysindex yyrindex yygindex yyname
+ at c LocalWords: yytable yycheck yyrule byacc CXXCOMPILE CXXLINK FLINK cfortran
+ at c LocalWords: Catalogue preprocessable FLIBS libfoo baz JAVACFLAGS java exe
+ at c LocalWords: SunOS fying basenames exeext uninstalled oldinclude kr FSF's
+ at c LocalWords: pkginclude oldincludedir sysconf sharedstate localstate gcc rm
+ at c LocalWords: sysconfdir sharedstatedir localstatedir preexist CLEANFILES gz
+ at c LocalWords: depfile tmpdepfile depmode const interoperate
+ at c LocalWords: JAVAC javac JAVAROOT builddir CLASSPATH ENV pyc pyo pkgpython
+ at c LocalWords: pyexecdir pkgpyexecdir Python's pythondir pkgpythondir txi ois
+ at c LocalWords: installinfo vers MAKEINFO makeinfo MAKEINFOFLAGS noinstall rf
+ at c LocalWords: mandir thesame alsothesame installman myexecbin DESTDIR Pinard
+ at c LocalWords: uninstall installdirs uninstalls MOSTLYCLEANFILES mostlyclean
+ at c LocalWords: DISTCLEANFILES MAINTAINERCLEANFILES GZIP gzip shar exp
+ at c LocalWords: distdir distcheck distcleancheck listfiles distuninstallcheck
+ at c LocalWords: VPATH tarfile stdout XFAIL DejaGnu dejagnu DEJATOOL runtest ln
+ at c LocalWords: RUNTESTDEFAULTFLAGS toolchain RUNTESTFLAGS asis readme DVIPS
+ at c LocalWords: installcheck gzipped tarZ std utils etags mkid multilibbing cd
+ at c LocalWords: ARGS taggable ETAGSFLAGS lang ctags CTAGSFLAGS GTAGS gtags idl
+ at c LocalWords: foocc doit idlC multilibs ABIs cmindex defmac ARG enableval FC
+ at c LocalWords: MSG xtrue DBG pathchk CYGWIN afile proglink versioned CVS's TE
+ at c LocalWords: wildcards Autoconfiscated subsubheading autotools Meyering API
+ at c LocalWords: ois's wildcard Wportability cartouche vrindex printindex Duret
+ at c LocalWords: DSOMEFLAG DVERSION automake Lutz insertcopying versioning FAQ
+ at c LocalWords: LTLIBOBJ Libtool's libtool's libltdl dlopening itutions libbar
+ at c LocalWords: WANTEDLIBS libhello sublibraries libtop libsub dlopened Ratfor
+ at c LocalWords: mymodule timestamps timestamp underquoted MAKEINFOHTMLFLAGS te
+ at c LocalWords: GNUmakefile Subpackages subpackage's subpackages aux
+ at c LocalWords: detailmenu Timeline pwd reldir AUTOM autom PREREQ FOOBAR libc
+ at c LocalWords: libhand subpackage moduleN libmain libmisc FCFLAGS FCCOMPILE
+ at c LocalWords: FCLINK subst sed ELCFILES elc MAKEINFOHTML dvips esyscmd ustar
+ at c LocalWords: tarballs Woverride vfi ELFILES djm AutoMake honkin FSF
+ at c LocalWords: fileutils precanned MacKenzie's reimplement termutils Tromey's
+ at c LocalWords: cois gnitsians LIBPROGRAMS progs LIBLIBRARIES Textutils Ulrich
+ at c LocalWords: Matzigkeit Drepper's Gord Matzigkeit's jm Dalley Debian org
+ at c LocalWords: Administrivia ILU CORBA Sourceware Molenda sourceware Elliston
+ at c LocalWords: dep Oliva Akim Demaille Aiieeee Demaillator Akim's sourcequake
+ at c LocalWords: grep backported screenshots libgcj KB unnumberedsubsubsec pre
+ at c LocalWords: precomputing hacky makedepend inline clearmake LD PRELOAD Rel
+ at c LocalWords: syscalls perlhist acl pm multitable headitem fdl appendixsec
+ at c LocalWords: LTALLOCA MALLOC malloc memcmp strdup alloca libcompat xyz DFOO
+ at c LocalWords: unprefixed buildable preprocessed DBAZ DDATADIR WARNINGCFLAGS
+ at c LocalWords: LIBFOOCFLAGS LIBFOOLDFLAGS ftable testSubDir obj LIBTOOLFLAGS
+ at c LocalWords: barexec Pinard's automatize initialize lzip lzma xz
diff --git a/debian/docs/src/automake/1.11.5/fdl.texi b/debian/docs/src/automake/1.11.5/fdl.texi
new file mode 100644
index 0000000..8805f1a
--- /dev/null
+++ b/debian/docs/src/automake/1.11.5/fdl.texi
@@ -0,0 +1,506 @@
+ at c The GNU Free Documentation License.
+ at center Version 1.3, 3 November 2008
+
+ at c This file is intended to be included within another document,
+ at c hence no sectioning command or @node.
+
+ at display
+Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
+ at uref{http://fsf.org/}
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+ at end display
+
+ at enumerate 0
+ at item
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document @dfn{free} in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
+ at item
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The ``Document'', below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as ``you''. You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section
+of the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall
+subject (or to related matters) and contains nothing that could fall
+directly within that overall subject. (Thus, if the Document is in
+part a textbook of mathematics, a Secondary Section may not explain
+any mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A copy that is not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
+ at sc{ascii} without markup, Texinfo input format, La at TeX{} input
+format, @acronym{SGML} or @acronym{XML} using a publicly available
+ at acronym{DTD}, and standard-conforming simple @acronym{HTML},
+PostScript or @acronym{PDF} designed for human modification. Examples
+of transparent image formats include @acronym{PNG}, @acronym{XCF} and
+ at acronym{JPG}. Opaque formats include proprietary formats that can be
+read and edited only by proprietary word processors, @acronym{SGML} or
+ at acronym{XML} for which the @acronym{DTD} and/or processing tools are
+not generally available, and the machine-generated @acronym{HTML},
+PostScript or @acronym{PDF} produced by some word processors for
+output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+The ``publisher'' means any person or entity that distributes copies
+of the Document to the public.
+
+A section ``Entitled XYZ'' means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as ``Acknowledgements'',
+``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
+of such a section when you modify the Document means that it remains a
+section ``Entitled XYZ'' according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
+ at item
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+ at item
+COPYING IN QUANTITY
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+ at item
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
+ at enumerate A
+ at item
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
+ at item
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has fewer than five),
+unless they release you from this requirement.
+
+ at item
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+ at item
+Preserve all the copyright notices of the Document.
+
+ at item
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+ at item
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
+ at item
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
+ at item
+Include an unaltered copy of this License.
+
+ at item
+Preserve the section Entitled ``History'', Preserve its Title, and add
+to it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section Entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
+ at item
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
+ at item
+For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
+the Title of the section, and preserve in the section all the
+substance and tone of each of the contributor acknowledgements and/or
+dedications given therein.
+
+ at item
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
+ at item
+Delete any section Entitled ``Endorsements''. Such a section
+may not be included in the Modified Version.
+
+ at item
+Do not retitle any existing section to be Entitled ``Endorsements'' or
+to conflict in title with any Invariant Section.
+
+ at item
+Preserve any Warranty Disclaimers.
+ at end enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+ at item
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled ``History''
+in the various original documents, forming one section Entitled
+``History''; likewise combine any sections Entitled ``Acknowledgements'',
+and any sections Entitled ``Dedications''. You must delete all
+sections Entitled ``Endorsements.''
+
+ at item
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+ at item
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an ``aggregate'' if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
+ at item
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled ``Acknowledgements'',
+``Dedications'', or ``History'', the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
+ at item
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document
+except as expressly provided under this License. Any attempt
+otherwise to copy, modify, sublicense, or distribute it is void, and
+will automatically terminate your rights under this License.
+
+However, if you cease all violation of this License, then your license
+from a particular copyright holder is reinstated (a) provisionally,
+unless and until the copyright holder explicitly and finally
+terminates your license, and (b) permanently, if the copyright holder
+fails to notify you of the violation by some reasonable means prior to
+60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License. If your rights have been terminated and not permanently
+reinstated, receipt of a copy of some or all of the same material does
+not give you any rights to use it.
+
+ at item
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
+ at uref{http://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation. If the Document
+specifies that a proxy can decide which future versions of this
+License can be used, that proxy's public statement of acceptance of a
+version permanently authorizes you to choose that version for the
+Document.
+
+ at item
+RELICENSING
+
+``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any
+World Wide Web server that publishes copyrightable works and also
+provides prominent facilities for anybody to edit those works. A
+public wiki that anybody can edit is an example of such a server. A
+``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the
+site means any set of copyrightable works thus published on the MMC
+site.
+
+``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0
+license published by Creative Commons Corporation, a not-for-profit
+corporation with a principal place of business in San Francisco,
+California, as well as future copyleft versions of that license
+published by that same organization.
+
+``Incorporate'' means to publish or republish a Document, in whole or
+in part, as part of another Document.
+
+An MMC is ``eligible for relicensing'' if it is licensed under this
+License, and if all works that were first published under this License
+somewhere other than this MMC, and subsequently incorporated in whole
+or in part into the MMC, (1) had no cover texts or invariant sections,
+and (2) were thus incorporated prior to November 1, 2008.
+
+The operator of an MMC Site may republish an MMC contained in the site
+under CC-BY-SA on the same site at any time before August 1, 2009,
+provided the MMC is eligible for relicensing.
+
+ at end enumerate
+
+ at page
+ at heading ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+ at smallexample
+ at group
+ Copyright (C) @var{year} @var{your name}.
+ 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''.
+ at end group
+ at end smallexample
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the ``with at dots{}Texts.'' line with this:
+
+ at smallexample
+ at group
+ with the Invariant Sections being @var{list their titles}, with
+ the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
+ being @var{list}.
+ at end group
+ at end smallexample
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+ at c Local Variables:
+ at c ispell-local-pdict: "ispell-dict"
+ at c End:
+
diff --git a/debian/docs/src/automake/1.11.5/version.texi b/debian/docs/src/automake/1.11.5/version.texi
new file mode 100644
index 0000000..94729ff
--- /dev/null
+++ b/debian/docs/src/automake/1.11.5/version.texi
@@ -0,0 +1,4 @@
+ at set UPDATED 13 April 2012
+ at set UPDATED-MONTH April 2012
+ at set EDITION 1.11.5
+ at set VERSION 1.11.5
diff --git a/debian/docs/src/parsers/build.xml b/debian/docs/src/parsers/build.xml
new file mode 100644
index 0000000..9abc931
--- /dev/null
+++ b/debian/docs/src/parsers/build.xml
@@ -0,0 +1,15 @@
+<project name="Texinfo Parser" default="compile" basedir=".">
+ <property name="src" value="."/>
+ <property name="build" value="build"/>
+ <property name="build.compiler" value="modern"/>
+
+ <target name="init">
+ <tstamp/>
+ <mkdir dir="${build}"/>
+ </target>
+
+ <target name="compile" depends="init">
+ <javac srcdir="${src}" destdir="${build}" />
+ </target>
+</project>
+
\ No newline at end of file
diff --git a/debian/docs/src/parsers/src/org/eclipse/linuxtools/cdt/libhover/texinfoparsers/ParseAutoconfTexinfo.java b/debian/docs/src/parsers/src/org/eclipse/linuxtools/cdt/libhover/texinfoparsers/ParseAutoconfTexinfo.java
new file mode 100644
index 0000000..c944c66
--- /dev/null
+++ b/debian/docs/src/parsers/src/org/eclipse/linuxtools/cdt/libhover/texinfoparsers/ParseAutoconfTexinfo.java
@@ -0,0 +1,646 @@
+/*******************************************************************************
+ * Copyright (c) 2007 Red Hat Inc..
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ * Red Hat Incorporated - initial API and implementation
+ *******************************************************************************/
+package org.eclipse.linuxtools.cdt.libhover.texinfoparsers;
+import java.io.BufferedReader;
+import java.io.BufferedWriter;
+import java.io.File;
+import java.io.FileReader;
+import java.io.FileWriter;
+import java.io.FilenameFilter;
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+//This file contains a texinfo parser that can be
+//run to create the Autotools glibc.xml file.
+//Usage is as follows:
+//1. compile this file using javac
+//2. run this file using java, passing the
+//arguments: ${glibc_source_path}/manual glibc.xml
+
+public class ParseAutoconfTexinfo {
+
+ static final boolean DEBUG = false;
+
+ static final String ATcmd = "(@\\w*)";
+
+ // 0
+ static final String Defmac = "@defmac";
+ static final String Defmacx = "@defmacx";
+
+ // 1
+ static final String MacroName = "(\\w*)";
+ static final int MacroNameIndex = 1;
+
+ // 2 3
+ static final String Parms = "(\\((.*)\\))";
+ static final int ParmsIndex = 2;
+
+ static final String rest = ".*";
+
+ static final String WhiteSpace = "\\s*";
+
+ static final Pattern MacroPattern
+ = Pattern.compile("^" + Defmac + WhiteSpace +
+ MacroName + WhiteSpace +
+ Parms +
+ rest, Pattern.MULTILINE + Pattern.CASE_INSENSITIVE);
+
+ static final Pattern MacroPattern2
+ = Pattern.compile("^" + Defmac + WhiteSpace + MacroName + rest,
+ Pattern.MULTILINE + Pattern.CASE_INSENSITIVE);
+
+ static final Pattern MacroPatternx
+ = Pattern.compile("^" + Defmacx + WhiteSpace +
+ MacroName + WhiteSpace +
+ Parms +
+ rest, Pattern.MULTILINE + Pattern.CASE_INSENSITIVE);
+
+ static final Pattern MacroPatternx2
+ = Pattern.compile("^" + Defmacx + WhiteSpace + MacroName + rest,
+ Pattern.MULTILINE + Pattern.CASE_INSENSITIVE);
+
+ static final Pattern ParmBracketPattern = Pattern.compile("\\((.*)\\)");
+ static final Pattern IndexPattern = Pattern.compile("@\\w*index\\s+[a-zA-Z0-9_@\\{\\}]*");
+ static final Pattern IndexPattern2 = Pattern.compile("@\\w*index\\{[a-zA-Z0-9_@\\{\\}]*\\}");
+ static final Pattern ExamplePattern = Pattern.compile("@example");
+ static final Pattern EndExamplePattern = Pattern.compile("@end\\s+example");
+ static final Pattern EnumeratePattern = Pattern.compile("@enumerate");
+ static final Pattern EndEnumeratePattern = Pattern.compile("@end\\s+enumerate");
+ static final Pattern VerbatimPattern = Pattern.compile("@verbatim");
+ static final Pattern ItemPattern = Pattern.compile("@item");
+ static final Pattern NoIndentPattern = Pattern.compile("@noindent");
+ static final Pattern BRPattern = Pattern.compile("<br>");
+ static final Pattern EOLPattern = Pattern.compile("<eol>");
+ static final Pattern EndVerbatimPattern = Pattern.compile("@end\\s+verbatim");
+ static final Pattern TableSampItemPattern = Pattern.compile("(@table\\s*@samp.*)@item\\s*([a-zA-Z_0-9+\\-<>/ ]*)<eol>(.*@end\\s*table)", Pattern.DOTALL);
+ static final Pattern TableAsisItemPattern = Pattern.compile("(@table\\s*@asis.*)@item\\s*([a-zA-Z_0-9+\\-,<>/ ]*)<eol>(.*@end\\s*table)", Pattern.DOTALL);
+ static final Pattern TableSampPattern = Pattern.compile("@table\\s*@samp", Pattern.MULTILINE);
+ static final Pattern TableAsisPattern = Pattern.compile("@table\\s*@asis", Pattern.MULTILINE);
+ static final Pattern EndTablePattern = Pattern.compile("@end\\s+table");
+ static final Pattern DotsPattern = Pattern.compile("@dots\\{\\}");
+ static final Pattern ItemizeMinusPattern= Pattern.compile("@itemize\\s+ at minus" + "(.*)" + "@end\\s+itemize", Pattern.MULTILINE);
+ static final Pattern ItemizeBulletPattern= Pattern.compile("@itemize\\s+ at bullet" + "(.*)" + "@end\\s+itemize", Pattern.MULTILINE);
+ static final Pattern XrefPattern = Pattern.compile("@xref\\{[^\\}]*\\}", Pattern.MULTILINE);
+ static final Pattern CommandPattern = Pattern.compile("@command\\{([^\\}]*)\\}");
+ static final Pattern KbdPattern = Pattern.compile("@kbd\\{([^\\}]*)\\}");
+ static final Pattern RPattern = Pattern.compile("@r\\{([^\\}]*)\\}");
+ static final Pattern FilePattern = Pattern.compile("@file\\{([^\\}]*)\\}");
+ static final Pattern VarPattern = Pattern.compile("@var\\{([^\\}]*)\\}");
+ static final Pattern OVarPattern = Pattern.compile("@ovar\\{([^\\}]*)\\}");
+ static final Pattern DVarPattern = Pattern.compile("@dvar\\{([^\\},\\,]*),([^\\}]*)\\}");
+ static final Pattern CodePattern = Pattern.compile("@code\\{([^\\}]*)\\}");
+ static final Pattern EmphPattern = Pattern.compile("@emph\\{([^\\}]*)\\}");
+ static final Pattern SampPattern = Pattern.compile("@samp\\{([^\\}]*)\\}");
+ static final Pattern OptionPattern = Pattern.compile("@option\\{([^\\}]*)\\}");
+ static final Pattern TagPattern = Pattern.compile("@\\w*\\{([^\\}]*)\\}");
+ static final Pattern AmpersandPattern = Pattern.compile("&");
+ static final Pattern LeftAnglePattern = Pattern.compile("<");
+ static final Pattern RightAnglePattern = Pattern.compile(">");
+
+
+ private static Map macroMap;
+
+ static class MacroParms {
+ String[] parms;
+ MacroParms nextParms = null;
+
+ public MacroParms(String[] parms) {
+ this.parms = parms;
+ }
+ }
+
+ static class MacroDef {
+ String MacroName;
+ MacroParms Parameters;
+ }
+
+ static class TPElement {
+ String Content;
+ String Synopsis;
+ }
+
+ static class TPDef {
+ String TPType;
+ String TPName;
+ String TPSynopsis;
+ TPElement[] TPElements;
+ Object[] IncludeList;
+ }
+
+ private static String killTagsParms(String tt) {
+ Matcher mm;
+
+ mm = ParmBracketPattern.matcher(tt);
+ tt= mm.replaceAll("$1");
+
+ mm = OVarPattern.matcher(tt);
+ tt = mm.replaceAll("[$1]");
+
+ mm = DVarPattern.matcher(tt);
+ tt = mm.replaceAll("[$1=$2]");
+
+ mm = VarPattern.matcher(tt);
+ tt = mm.replaceAll("$1");
+
+ mm = RPattern.matcher(tt);
+ tt = mm.replaceAll("$1");
+
+ mm = DotsPattern.matcher(tt);
+ tt = mm.replaceAll("...");
+
+ return tt;
+ }
+
+
+ private static String killTags(String tt) {
+ Matcher mm;
+ String ss = "";
+
+ while (ss != tt) {
+ mm = XrefPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = IndexPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = IndexPattern2.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = NoIndentPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = VarPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<VAR>$1</VAR>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = DotsPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<small>...</small>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = CommandPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<CODE>$1</CODE>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = CodePattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<CODE>$1</CODE>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = KbdPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<KBD>$1</KBD>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = EmphPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<EM>$1</EM>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = FilePattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<TT>$1</TT>");
+ }
+
+
+ ss = "";
+ while (ss != tt) {
+ mm = VerbatimPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<CODE>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = EndVerbatimPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("</CODE>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = SampPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<samp>$1</samp>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = OptionPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<samp>$1</samp>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = ExamplePattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<TABLE><tr><td> </td><td class=example><pre>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = EndExamplePattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("</pre></td></tr></table>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = EnumeratePattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<OL>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = EndEnumeratePattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("</OL>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = TableSampItemPattern.matcher(tt);
+ ss = tt;
+ if (mm.matches()) {
+ System.out.println("group 1 is " + mm.group(1));
+ System.out.println("group 2 is " + mm.group(2));
+ System.out.println("group 3 is " + mm.group(3));
+ }
+ tt = mm.replaceAll("$1<DT>'<SAMP>$2</SAMP>'\n<DD>$3");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = TableAsisItemPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("$1<DT>$2\n<DD>$3");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = TableSampPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<DL>\n");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = TableAsisPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<DL>\n");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = EndTablePattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("</DL>");
+ }
+
+ //FIXME: if there ever is a @itemize @bullet within a
+ // @itemize @minus or vice-versa, the following
+ // logic will get it wrong.
+ ss = "";
+ while (ss != tt) {
+ mm = ItemizeMinusPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<UL>$1</UL>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = ItemizeBulletPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<OL>$1</OL>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = ItemPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<LI>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = TagPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("$1");
+ }
+
+ mm = AmpersandPattern.matcher(tt);
+ tt = mm.replaceAll("&");
+
+ mm = LeftAnglePattern.matcher(tt);
+ tt = mm.replaceAll("<");
+
+ mm = RightAnglePattern.matcher(tt);
+ tt = mm.replaceAll(">");
+
+ // Clean up the eol markers we used to mark end of line for items
+ mm = EOLPattern.matcher(tt);
+ tt = mm.replaceAll("");
+
+ return tt;
+ }
+
+ private static MacroDef BuildMacroDef(Matcher m) {
+ MacroDef md = new MacroDef();
+
+ md.MacroName = m.group(MacroNameIndex);
+
+ if (null != m.group(ParmsIndex)) {
+ String tt = killTagsParms(m.group(ParmsIndex));
+ String[] parms = tt.split(",\\s");
+ md.Parameters = new MacroParms(parms);
+ }
+ return md;
+ }
+
+ private static MacroParms AddMacroDefxParms(MacroParms mp, Matcher mx) {
+ if (null != mx.group(ParmsIndex)) {
+ String tt = killTagsParms(mx.group(ParmsIndex));
+ String[] parms = tt.split(",\\s");
+ MacroParms mpnew = new MacroParms(parms);
+ mp.nextParms = mpnew;
+ return mpnew;
+ }
+ return null;
+ }
+
+ private static MacroDef HandleMacroDef(BufferedReader is, String s) throws IOException {
+ MacroDef fd = null;
+
+ Matcher m = MacroPattern.matcher(s);
+
+ if (m.matches()) {
+ fd = BuildMacroDef(m);
+ }
+ else { // assume the line got split and retry
+ is.mark(100);
+ String il = is.readLine();
+ m = MacroPattern.matcher(s + il);
+ if (m.matches()) fd = BuildMacroDef(m);
+ else {
+ is.reset();
+ m = MacroPattern2.matcher(s);
+ if (m.matches()) {
+ fd = new MacroDef();
+ fd.MacroName = m.group(MacroNameIndex);
+ fd.Parameters = new MacroParms(new String[0]);
+ }
+ }
+ }
+
+ if (fd != null) {
+ // Look for @defmacx which are alternate prototypes for the macro
+ is.mark(100);
+ String il = is.readLine();
+ if (il != null) {
+ Matcher mx = MacroPatternx.matcher(il);
+ Matcher mx2 = MacroPatternx2.matcher(il);
+ MacroParms mp = fd.Parameters;
+ while (mx.matches() || mx2.matches()) {
+ if (mx.matches())
+ mp = AddMacroDefxParms(mp, mx);
+ else {
+ MacroParms mpnew = new MacroParms(new String[0]);
+ mp.nextParms = mpnew;
+ mp = mpnew;
+ }
+ is.mark(100);
+ il = is.readLine();
+ if (il != null) {
+ mx = MacroPatternx.matcher(il);
+ mx2 = MacroPatternx2.matcher(il);
+ }
+ }
+ is.reset();
+ }
+
+ if (macroMap.get(fd.MacroName) != null)
+ return null;
+ macroMap.put(fd.MacroName, fd);
+ }
+
+ return fd;
+ }
+
+ private static void WriteString(BufferedWriter os, String s) throws IOException {
+ // System.out.println(s);
+ os.write(s+"\n", 0, 1+s.length());
+ }
+
+ private static void CreateHeader(BufferedWriter os) throws IOException {
+ WriteString(os, "<!-- This file automatically generated by ParseAutoconfTexinfo utility -->");
+ WriteString(os, "<!-- cvs -d:pserver:anonymous at sources.redhat.com:/cvs/eclipse \\ -->");
+ WriteString(os, "<!-- co autotools/ParseTexinfo -->");
+ WriteString(os, "<!DOCTYPE macros [");
+ WriteString(os, "");
+ WriteString(os, " <!ELEMENT macros (macro)*>");
+ WriteString(os, "");
+ WriteString(os, " <!ELEMENT macro (prototype*,synopsis)>");
+ WriteString(os, " <!ATTLIST macro");
+ WriteString(os, " id ID #REQUIRED");
+ WriteString(os, " >");
+ WriteString(os, "");
+ WriteString(os, " <!ELEMENT synopsis (#PCDATA)*>");
+ WriteString(os, "");
+ WriteString(os, " <!ELEMENT prototype (parameter+)?>");
+ WriteString(os, "");
+ WriteString(os, " <!ELEMENT parameter (#PCDATA)*>");
+ WriteString(os, " <!ATTLIST parameter");
+ WriteString(os, " content CDATA #REQUIRED");
+ WriteString(os, " >");
+ WriteString(os, "");
+ WriteString(os, "]>");
+ WriteString(os, "");
+ }
+
+
+
+ private static void CreateTrailer(BufferedWriter os) throws IOException {
+ WriteString(os, "</macros>");
+ }
+
+ private static void WriteSynopsis(BufferedWriter os, String Synopsis, boolean indent) throws IOException {
+ String ss = killTags(Synopsis);
+ String[] tt = ss.split("\\s");
+ String aa = "";
+ String spaces = indent ? " " : " ";
+ WriteString(os, spaces + "<synopsis>");
+ if (null != Synopsis) {
+ for (int pp = 0; pp < tt.length; pp++) {
+ if (tt[pp].equals("<br>")) {
+ WriteString(os, spaces + aa + "</P><P>\n");
+ aa = "";
+ }
+ else {
+ if ((aa.length() + tt[pp].length()) > 64) {
+ WriteString(os, spaces + aa);
+ aa = "";
+ }
+ aa = aa + " " + tt[pp];
+ }
+ }
+ }
+ if (aa.length() > 0) WriteString(os, " " + aa);
+ WriteString(os, spaces + "</synopsis>");
+ }
+
+ private static void HandleDefmacro(BufferedWriter os, BufferedReader is, String s) throws IOException {
+ String il;
+ MacroDef md;
+ List FDefs = new ArrayList();
+ String Synopsis = null;
+
+ if (null != (md = HandleMacroDef(is, s))) FDefs.add(md);
+
+ while (null != (il = is.readLine())) {
+ if (il.startsWith("@defmac")) {
+ if (null != (md = HandleMacroDef(is, il))) FDefs.add(md);
+ }
+ else if (il.startsWith("@comment") ||
+ il.startsWith("@c ")) { // comment -- ignore it
+ }
+ else if (il.startsWith("@end defmac")) {
+ for (int kk = 0; kk < FDefs.size(); kk++) {
+ md = (MacroDef)FDefs.get(kk);
+
+ WriteString(os, " <macro id=\"" + md.MacroName + "\">");
+
+ MacroParms mp = md.Parameters;
+ do {
+ WriteString(os, " <prototype>");
+ String[] parms = mp.parms;
+ for (int i = 0; i < parms.length; i++) {
+ String p = parms[i].replaceAll("\"", """);
+ WriteString(os, " <parameter content=\"" + p + "\"/>");
+ }
+ WriteString(os, " </prototype>");
+ mp = mp.nextParms;
+ } while (mp != null);
+
+ if (null != Synopsis) WriteSynopsis(os, Synopsis, false);
+
+ WriteString(os, " </macro>");
+ }
+ return;
+ }
+ else {
+ Synopsis = ((Synopsis == null) ? "" : Synopsis + " " ) + ((il.length() == 0) ? "<br>" :
+ il.startsWith("@item") ? il + "<eol>" : il);
+
+ }
+ }
+ FDefs.clear();
+
+ }
+
+ private static class OnlyTexi implements FilenameFilter {
+ public boolean accept(File dir, String s) {
+ return (s.endsWith(".texi")) ? true : false;
+ }
+ }
+
+ public static void BuildXMLFromTexinfo(String srcdir, String dstdir) {
+ try {
+ macroMap = new HashMap();
+ BufferedWriter os = new BufferedWriter(new FileWriter(dstdir));
+
+ CreateHeader(os);
+// CreateLicense(os);
+
+ WriteString(os, "<macros>");
+
+ try {
+ String[] dir = new java.io.File(srcdir).list(new OnlyTexi());
+ for (int i = 0; i < dir.length; i++) {
+ String qFile = srcdir.endsWith("/")
+ ? srcdir + dir[i]
+ : srcdir + "/" + dir[i];
+
+ try {
+ BufferedReader is = new BufferedReader(new FileReader(qFile));
+ String il;
+
+ while (null != (il = is.readLine())) {
+ if (il.startsWith("@defmac")) { // handle @defmac x]
+ HandleDefmacro(os, is, il);
+ }
+ }
+ is.close();
+ }
+ catch (IOException e) {
+ System.out.println("Input File IOException: " + e);
+ return;
+ }
+ }
+ }
+ catch (NullPointerException e) {
+ System.out.println("NullPointerException: " + e);
+ return;
+ }
+
+ CreateTrailer(os);
+
+ os.close();
+ }
+ catch (IOException e) {
+ System.out.println("Output File IOException: " + e);
+ return;
+ }
+ }
+
+ public static void main(String[] args) {
+ // arg[0] is input directory containing .texi documents to read
+ // arg[1] is output xml file to create
+ BuildXMLFromTexinfo(args[0], args[1]);
+ }
+
+}
diff --git a/debian/docs/src/parsers/src/org/eclipse/linuxtools/cdt/libhover/texinfoparsers/ParseAutomakeTexinfo.java b/debian/docs/src/parsers/src/org/eclipse/linuxtools/cdt/libhover/texinfoparsers/ParseAutomakeTexinfo.java
new file mode 100644
index 0000000..123e979
--- /dev/null
+++ b/debian/docs/src/parsers/src/org/eclipse/linuxtools/cdt/libhover/texinfoparsers/ParseAutomakeTexinfo.java
@@ -0,0 +1,661 @@
+/*******************************************************************************
+ * Copyright (c) 2007 Red Hat Inc..
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ * Red Hat Incorporated - initial API and implementation
+ *******************************************************************************/
+package org.eclipse.linuxtools.cdt.libhover.texinfoparsers;
+import java.io.BufferedReader;
+import java.io.BufferedWriter;
+import java.io.File;
+import java.io.FileReader;
+import java.io.FileWriter;
+import java.io.FilenameFilter;
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+//This file contains a texinfo parser that can be
+//run to create the Autotools glibc.xml file.
+//Usage is as follows:
+//1. compile this file using javac
+//2. run this file using java, passing the
+//arguments: dir_to_automake_texi_files output_xml_file_name
+
+public class ParseAutomakeTexinfo {
+
+ static final boolean DEBUG = false;
+
+ static final String ATcmd = "(@\\w*)";
+
+ // Currently in automake docs, the macro section starts with
+ // a subsection as below and a table which contains macros which
+ // are item and itemx entries.
+ static final String MacrosStart = "@subsection\\sPublic\\sMacros";
+ static final String OldMacrosStart = "@section\\sAutoconf\\sMacros.*";
+ static final Pattern MacroSection1 = Pattern.compile(MacrosStart);
+ static final Pattern MacroSection2 = Pattern.compile(OldMacrosStart);
+ // 0
+ static final String Defmac = "@item";
+ static final String Defmacx = "@itemx";
+
+ // 1
+ static final String MacroName = "(\\w*)";
+ static final int MacroNameIndex = 1;
+
+ // 2 3
+ static final String Parms = "(\\((.*)\\))";
+ static final int ParmsIndex = 2;
+
+ static final String rest = ".*";
+
+ static final String WhiteSpace = "\\s*";
+
+ static final Pattern MacroPattern
+ = Pattern.compile("^" + Defmac + WhiteSpace +
+ MacroName + WhiteSpace +
+ Parms +
+ rest, Pattern.MULTILINE + Pattern.CASE_INSENSITIVE);
+
+ static final Pattern MacroPattern2
+ = Pattern.compile("^" + Defmac + WhiteSpace + MacroName + rest,
+ Pattern.MULTILINE + Pattern.CASE_INSENSITIVE);
+
+ static final Pattern MacroPatternx
+ = Pattern.compile("^" + Defmacx + WhiteSpace +
+ MacroName + WhiteSpace +
+ Parms +
+ rest, Pattern.MULTILINE + Pattern.CASE_INSENSITIVE);
+
+ static final Pattern MacroPatternx2
+ = Pattern.compile("^" + Defmacx + WhiteSpace + MacroName + rest,
+ Pattern.MULTILINE + Pattern.CASE_INSENSITIVE);
+
+ static final Pattern ParmBracketPattern = Pattern.compile("\\((.*)\\)");
+ static final Pattern IndexPattern = Pattern.compile("@\\w*index.*");
+ static final Pattern IndexPattern2 = Pattern.compile("@\\w*index\\{[a-zA-Z0-9_@\\{\\}]*\\}");
+ static final Pattern ExamplePattern = Pattern.compile("@example");
+ static final Pattern EndExamplePattern = Pattern.compile("@end\\s+example");
+ static final Pattern EnumeratePattern = Pattern.compile("@enumerate");
+ static final Pattern EndEnumeratePattern = Pattern.compile("@end\\s+enumerate");
+ static final Pattern VerbatimPattern = Pattern.compile("@verbatim");
+ static final Pattern ItemPattern = Pattern.compile("@item");
+ static final Pattern NoIndentPattern = Pattern.compile("@noindent");
+ static final Pattern BRPattern = Pattern.compile("<br>");
+ static final Pattern EOLPattern = Pattern.compile("<eol>");
+ static final Pattern EndVerbatimPattern = Pattern.compile("@end\\s+verbatim");
+ static final Pattern TableSampItemPattern = Pattern.compile("(@table\\s*@samp.*)@item\\s*([a-zA-Z_0-9+\\-<>/ ]*)<eol>(.*@end\\s*table)", Pattern.DOTALL);
+ static final Pattern TableAsisItemPattern = Pattern.compile("(@table\\s*@asis.*)@item\\s*([a-zA-Z_0-9+\\-,<>/ ]*)<eol>(.*@end\\s*table)", Pattern.DOTALL);
+ static final Pattern TableSampPattern = Pattern.compile("@table\\s*@samp", Pattern.MULTILINE);
+ static final Pattern TableAsisPattern = Pattern.compile("@table\\s*@asis", Pattern.MULTILINE);
+ static final Pattern EndTablePattern = Pattern.compile("@end\\s+table");
+ static final Pattern DotsPattern = Pattern.compile("@dots\\{\\}");
+ static final Pattern ItemizeMinusPattern= Pattern.compile("@itemize\\s+ at minus" + "(.*)" + "@end\\s+itemize", Pattern.MULTILINE);
+ static final Pattern ItemizeBulletPattern= Pattern.compile("@itemize\\s+ at bullet" + "(.*)" + "@end\\s+itemize", Pattern.MULTILINE);
+ static final Pattern XrefPattern = Pattern.compile("@xref\\{[^\\}]*\\}", Pattern.MULTILINE);
+ static final Pattern CommandPattern = Pattern.compile("@command\\{([^\\}]*)\\}");
+ static final Pattern KbdPattern = Pattern.compile("@kbd\\{([^\\}]*)\\}");
+ static final Pattern RPattern = Pattern.compile("@r\\{([^\\}]*)\\}");
+ static final Pattern FilePattern = Pattern.compile("@file\\{([^\\}]*)\\}");
+ static final Pattern VarPattern = Pattern.compile("@var\\{([^\\}]*)\\}");
+ static final Pattern OVarPattern = Pattern.compile("@ovar\\{([^\\}]*)\\}");
+ static final Pattern DVarPattern = Pattern.compile("@dvar\\{([^\\},\\,]*),([^\\}]*)\\}");
+ static final Pattern CodePattern = Pattern.compile("@code\\{([^\\}]*)\\}");
+ static final Pattern EmphPattern = Pattern.compile("@emph\\{([^\\}]*)\\}");
+ static final Pattern SampPattern = Pattern.compile("@samp\\{([^\\}]*)\\}");
+ static final Pattern OptionPattern = Pattern.compile("@option\\{([^\\}]*)\\}");
+ static final Pattern UrefPattern = Pattern.compile("@uref\\{([^,]*),\\s+([^\\}]*)\\}");
+ static final Pattern TagPattern = Pattern.compile("@\\w*\\{([^\\}]*)\\}");
+ static final Pattern AmpersandPattern = Pattern.compile("&");
+ static final Pattern LeftAnglePattern = Pattern.compile("<");
+ static final Pattern RightAnglePattern = Pattern.compile(">");
+
+
+ private static Map macroMap;
+
+ static class MacroParms {
+ String[] parms;
+ MacroParms nextParms = null;
+
+ public MacroParms(String[] parms) {
+ this.parms = parms;
+ }
+ }
+
+ static class MacroDef {
+ String MacroName;
+ MacroParms Parameters;
+ String Synopsis;
+ }
+
+ static class TPElement {
+ String Content;
+ String Synopsis;
+ }
+
+ static class TPDef {
+ String TPType;
+ String TPName;
+ String TPSynopsis;
+ TPElement[] TPElements;
+ Object[] IncludeList;
+ }
+
+ private static String killTagsParms(String tt) {
+ Matcher mm;
+
+ mm = ParmBracketPattern.matcher(tt);
+ tt= mm.replaceAll("$1");
+
+ mm = OVarPattern.matcher(tt);
+ tt = mm.replaceAll("[$1]");
+
+ mm = DVarPattern.matcher(tt);
+ tt = mm.replaceAll("[$1=$2]");
+
+ mm = VarPattern.matcher(tt);
+ tt = mm.replaceAll("$1");
+
+ mm = RPattern.matcher(tt);
+ tt = mm.replaceAll("$1");
+
+ mm = DotsPattern.matcher(tt);
+ tt = mm.replaceAll("...");
+
+ return tt;
+ }
+
+
+ private static String killTags(String tt) {
+ Matcher mm;
+ String ss = "";
+
+ while (ss != tt) {
+ mm = XrefPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = IndexPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = IndexPattern2.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = NoIndentPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = VarPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<VAR>$1</VAR>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = DotsPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<small>...</small>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = CommandPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<CODE>$1</CODE>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = CodePattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<CODE>$1</CODE>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = UrefPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<A HREF=\"$1>$2</A>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = KbdPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<KBD>$1</KBD>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = EmphPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<EM>$1</EM>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = FilePattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<TT>$1</TT>");
+ }
+
+
+ ss = "";
+ while (ss != tt) {
+ mm = VerbatimPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<CODE>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = EndVerbatimPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("</CODE>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = SampPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<samp>$1</samp>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = OptionPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<samp>$1</samp>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = ExamplePattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<TABLE><tr><td> </td><td class=example><pre>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = EndExamplePattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("</pre></td></tr></table>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = EnumeratePattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<OL>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = EndEnumeratePattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("</OL>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = TableSampItemPattern.matcher(tt);
+ ss = tt;
+ if (mm.matches()) {
+ System.out.println("group 1 is " + mm.group(1));
+ System.out.println("group 2 is " + mm.group(2));
+ System.out.println("group 3 is " + mm.group(3));
+ }
+ tt = mm.replaceAll("$1<DT>'<SAMP>$2</SAMP>'\n<DD>$3");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = TableAsisItemPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("$1<DT>$2\n<DD>$3");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = TableSampPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<DL>\n");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = TableAsisPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<DL>\n");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = EndTablePattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("</DL>");
+ }
+
+ //FIXME: if there ever is a @itemize @bullet within a
+ // @itemize @minus or vice-versa, the following
+ // logic will get it wrong.
+ ss = "";
+ while (ss != tt) {
+ mm = ItemizeMinusPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<UL>$1</UL>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = ItemizeBulletPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<OL>$1</OL>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = ItemPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("<LI>");
+ }
+
+ ss = "";
+ while (ss != tt) {
+ mm = TagPattern.matcher(tt);
+ ss = tt;
+ tt = mm.replaceAll("$1");
+ }
+
+ mm = AmpersandPattern.matcher(tt);
+ tt = mm.replaceAll("&");
+
+ mm = LeftAnglePattern.matcher(tt);
+ tt = mm.replaceAll("<");
+
+ mm = RightAnglePattern.matcher(tt);
+ tt = mm.replaceAll(">");
+
+ // Clean up the eol markers we used to mark end of line for items
+ mm = EOLPattern.matcher(tt);
+ tt = mm.replaceAll("");
+
+ return tt;
+ }
+
+ private static MacroDef BuildMacroDef(Matcher m) {
+ MacroDef md = new MacroDef();
+
+ md.MacroName = m.group(MacroNameIndex);
+
+ if (null != m.group(ParmsIndex)) {
+ String tt = killTagsParms(m.group(ParmsIndex));
+ String[] parms = tt.split(",\\s");
+ md.Parameters = new MacroParms(parms);
+ }
+ return md;
+ }
+
+ private static MacroParms AddMacroDefxParms(MacroParms mp, Matcher mx) {
+ if (null != mx.group(ParmsIndex)) {
+ String tt = killTagsParms(mx.group(ParmsIndex));
+ String[] parms = tt.split(",\\s");
+ MacroParms mpnew = new MacroParms(parms);
+ mp.nextParms = mpnew;
+ return mpnew;
+ }
+ return null;
+ }
+
+ private static MacroDef HandleMacroDef(BufferedReader is, String s) throws IOException {
+ MacroDef fd = null;
+
+ Matcher m = MacroPattern.matcher(s);
+
+ if (m.matches()) {
+ fd = BuildMacroDef(m);
+ }
+ else { // assume the line got split and retry
+ is.mark(100);
+ String il = is.readLine();
+ m = MacroPattern.matcher(s + il);
+ if (m.matches()) fd = BuildMacroDef(m);
+ else {
+ is.reset();
+ m = MacroPattern2.matcher(s);
+ if (m.matches()) {
+ fd = new MacroDef();
+ fd.MacroName = m.group(MacroNameIndex);
+ fd.Parameters = new MacroParms(new String[0]);
+ }
+ }
+ }
+
+ if (fd != null) {
+ // Look for @defmacx which are alternate prototypes for the macro
+ is.mark(100);
+ String il = is.readLine();
+ if (il != null) {
+ Matcher mx = MacroPatternx.matcher(il);
+ Matcher mx2 = MacroPatternx2.matcher(il);
+ MacroParms mp = fd.Parameters;
+ while (mx.matches() || mx2.matches()) {
+ if (mx.matches())
+ mp = AddMacroDefxParms(mp, mx);
+ else {
+ MacroParms mpnew = new MacroParms(new String[0]);
+ mp.nextParms = mpnew;
+ mp = mpnew;
+ }
+ is.mark(100);
+ il = is.readLine();
+ if (il != null) {
+ mx = MacroPatternx.matcher(il);
+ mx2 = MacroPatternx2.matcher(il);
+ }
+ }
+ is.reset();
+ }
+
+ if (macroMap.get(fd.MacroName) != null)
+ return null;
+ macroMap.put(fd.MacroName, fd);
+ }
+
+ return fd;
+ }
+
+ private static void WriteString(BufferedWriter os, String s) throws IOException {
+ // System.out.println(s);
+ os.write(s+"\n", 0, 1+s.length());
+ }
+
+ private static void CreateHeader(BufferedWriter os) throws IOException {
+ WriteString(os, "<!-- This file automatically generated by ParseAutomakeTexinfo utility -->");
+ WriteString(os, "<!-- cvs -d:pserver:anonymous at sources.redhat.com:/cvs/eclipse \\ -->");
+ WriteString(os, "<!-- co autotools/ParseTexinfo -->");
+ WriteString(os, "<!DOCTYPE macros [");
+ WriteString(os, "");
+ WriteString(os, " <!ELEMENT macros (macro)*>");
+ WriteString(os, "");
+ WriteString(os, " <!ELEMENT macro (prototype*,synopsis)>");
+ WriteString(os, " <!ATTLIST macro");
+ WriteString(os, " id ID #REQUIRED");
+ WriteString(os, " >");
+ WriteString(os, "");
+ WriteString(os, " <!ELEMENT synopsis (#PCDATA)*>");
+ WriteString(os, "");
+ WriteString(os, " <!ELEMENT prototype (parameter+)?>");
+ WriteString(os, "");
+ WriteString(os, " <!ELEMENT parameter (#PCDATA)*>");
+ WriteString(os, " <!ATTLIST parameter");
+ WriteString(os, " content CDATA #REQUIRED");
+ WriteString(os, " >");
+ WriteString(os, "");
+ WriteString(os, "]>");
+ WriteString(os, "");
+ }
+
+
+
+ private static void CreateTrailer(BufferedWriter os) throws IOException {
+ WriteString(os, "</macros>");
+ }
+
+ private static void WriteSynopsis(BufferedWriter os, String Synopsis, boolean indent) throws IOException {
+ String ss = Synopsis;
+ String[] tt = ss.split("\\s");
+ String aa = "";
+ String spaces = indent ? " " : " ";
+ WriteString(os, spaces + "<synopsis>");
+ if (null != Synopsis) {
+ for (int pp = 0; pp < tt.length; pp++) {
+ if (tt[pp].equals("<br>")) {
+ WriteString(os, spaces + aa + "</P><P>\n");
+ aa = "";
+ }
+ else {
+ if ((aa.length() + tt[pp].length()) > 64) {
+ WriteString(os, spaces + aa);
+ aa = "";
+ }
+ aa = aa + " " + tt[pp];
+ }
+ }
+ }
+ if (aa.length() > 0) WriteString(os, " " + aa);
+ WriteString(os, spaces + "</synopsis>");
+ }
+
+ private static void HandleDefmacro(BufferedWriter os, BufferedReader is, String s) throws IOException {
+ String il;
+ MacroDef md = null;
+ List FDefs = new ArrayList();
+
+ while (null != (il = is.readLine())) {
+ if (il.startsWith(Defmac)) {
+ if (null != (md = HandleMacroDef(is, il))) FDefs.add(md);
+ }
+ else if (il.startsWith("@comment") ||
+ il.startsWith("@c ")) { // comment -- ignore it
+ }
+ else if (il.startsWith("@subsection") ||
+ il.startsWith("@section")) {
+ for (int kk = 0; kk < FDefs.size(); kk++) {
+ md = (MacroDef)FDefs.get(kk);
+
+ WriteString(os, " <macro id=\"" + md.MacroName + "\">");
+
+ MacroParms mp = md.Parameters;
+ do {
+ WriteString(os, " <prototype>");
+ String[] parms = mp.parms;
+ for (int i = 0; i < parms.length; i++) {
+ WriteString(os, " <parameter content=\"" + parms[i] + "\"/>");
+ }
+ WriteString(os, " </prototype>");
+ mp = mp.nextParms;
+ } while (mp != null);
+
+ if (null != md.Synopsis) WriteSynopsis(os, md.Synopsis, false);
+
+ WriteString(os, " </macro>");
+ }
+ return;
+ }
+ else {
+ if (md != null)
+ md.Synopsis = ((md.Synopsis == null) ? "" : md.Synopsis + " " ) + ((il.length() == 0) ? "<br><br>" :
+ il.startsWith("@item") ? killTags(il) + "<eol>" : killTags(il));
+ }
+ }
+ FDefs.clear();
+
+ }
+
+ private static class OnlyTexi implements FilenameFilter {
+ public boolean accept(File dir, String s) {
+ return (s.endsWith(".texi")) ? true : false;
+ }
+ }
+
+ public static void BuildXMLFromTexinfo(String srcdir, String dstdir) {
+ try {
+ macroMap = new HashMap();
+ BufferedWriter os = new BufferedWriter(new FileWriter(dstdir));
+
+ CreateHeader(os);
+// CreateLicense(os);
+
+ WriteString(os, "<macros>");
+
+ try {
+ String[] dir = new java.io.File(srcdir).list(new OnlyTexi());
+ for (int i = 0; i < dir.length; i++) {
+ String qFile = srcdir.endsWith("/")
+ ? srcdir + dir[i]
+ : srcdir + "/" + dir[i];
+
+ try {
+ BufferedReader is = new BufferedReader(new FileReader(qFile));
+ String il;
+
+ while (null != (il = is.readLine())) {
+ Matcher mm1 = MacroSection1.matcher(il);
+ Matcher mm2 = MacroSection2.matcher(il);
+ if (mm1.matches() || mm2.matches()) {
+ HandleDefmacro(os, is, il);
+ }
+ }
+ is.close();
+ }
+ catch (IOException e) {
+ System.out.println("Input File IOException: " + e);
+ return;
+ }
+ }
+ }
+ catch (NullPointerException e) {
+ System.out.println("NullPointerException: " + e);
+ return;
+ }
+
+ CreateTrailer(os);
+
+ os.close();
+ }
+ catch (IOException e) {
+ System.out.println("Output File IOException: " + e);
+ return;
+ }
+ }
+
+ public static void main(String[] args) {
+ // arg[0] is input directory containing .texi documents to read
+ // arg[1] is output xml file to create
+ BuildXMLFromTexinfo(args[0], args[1]);
+ }
+
+}
diff --git a/debian/docs/updateTexinfoSource.sh b/debian/docs/updateTexinfoSource.sh
new file mode 100755
index 0000000..947e1ce
--- /dev/null
+++ b/debian/docs/updateTexinfoSource.sh
@@ -0,0 +1,39 @@
+#!/bin/sh
+
+mkdir -p tmp
+cd tmp
+
+echo "Downloading source packages..."
+
+apt-get source autoconf automake > /dev/null
+
+# Pick autoconf documentation sources
+
+AC_SRCDIR=$(find -maxdepth 1 -type d -name 'autoconf-*')
+AC_VERSION=$(dpkg-parsechangelog -l$AC_SRCDIR/debian/changelog | sed -ne 's/^Version: \(.*\)-.*/\1/p')
+AC_DESTDIR=../src/autoconf/$AC_VERSION
+
+rm -rf $AC_DESTDIR
+mkdir -p $AC_DESTDIR
+
+mv $AC_SRCDIR/doc/*.texi $AC_DESTDIR
+
+echo Downloaded Autoconf doc source into src/autoconf/$AC_VERSION
+
+# Pick automake documentation sources
+
+AM_SRCDIR=$(find -maxdepth 1 -type d -name 'automake*')
+AM_VERSION=$(dpkg-parsechangelog -l$AM_SRCDIR/debian/changelog | sed -ne 's/^Version: \([0-9]\+\:\)\?\(.*\)-.*/\2/p')
+AM_DESTDIR=../src/automake/$AM_VERSION
+
+rm -rf $AM_DESTDIR
+mkdir -p $AM_DESTDIR
+
+mv $AM_SRCDIR/doc/*.texi $AM_DESTDIR
+
+echo Downloaded Automake doc source into src/automake/$AM_VERSION
+
+echo "Don't forget to update autotools-add-distro-version-to-list.patch if Autoconf or Automake version changed."
+
+cd ..
+rm -rf tmp
diff --git a/debian/eclipse-cdt-autotools.eh-install b/debian/eclipse-cdt-autotools.eh-install
new file mode 100644
index 0000000..a510a67
--- /dev/null
+++ b/debian/eclipse-cdt-autotools.eh-install
@@ -0,0 +1 @@
+org.eclipse.cdt.autotools
diff --git a/debian/eclipse.environment b/debian/eclipse.environment
index 3efe851..e275947 100644
--- a/debian/eclipse.environment
+++ b/debian/eclipse.environment
@@ -79,3 +79,8 @@ visualizer/org.eclipse.cdt.visualizer*
# Needed for feature org.eclipse.cdt.testsrunner.feature
testsrunner/org.eclipse.cdt.testsrunner*
+
+# Needed for org.eclipse.cdt.autotools
+
+build/org.eclipse.cdt.autotools*
+build/org.eclipse.linuxtools*
diff --git a/debian/eclipse.features b/debian/eclipse.features
index f0b1d17..ca58cc9 100644
--- a/debian/eclipse.features
+++ b/debian/eclipse.features
@@ -9,3 +9,4 @@ org.eclipse.cdt.launch.remote rse
org.eclipse.cdt.visualizer
org.eclipse.cdt.gnu.multicorevisualizer
org.eclipse.cdt.testsrunner.feature
+org.eclipse.cdt.autotools
diff --git a/debian/patches/autotools-add-distro-version-to-list.patch b/debian/patches/autotools-add-distro-version-to-list.patch
new file mode 100644
index 0000000..37167e1
--- /dev/null
+++ b/debian/patches/autotools-add-distro-version-to-list.patch
@@ -0,0 +1,47 @@
+From: Jakub Adam <jakub.adam at ktknet.cz>
+Date: Thu, 28 Jun 2012 17:51:15 +0200
+Subject: autotools-add-distro-version-to-list
+
+---
+ .../cdt/internal/autotools/core/AutotoolsPropertyConstants.java | 4 ++--
+ .../autotools/ui/preferences/AutoconfEditorPreferencePage.java | 4 ++--
+ 2 files changed, 4 insertions(+), 4 deletions(-)
+
+diff --git a/build/org.eclipse.cdt.autotools.core/src/org/eclipse/cdt/internal/autotools/core/AutotoolsPropertyConstants.java b/build/org.eclipse.cdt.autotools.core/src/org/eclipse/cdt/internal/autotools/core/AutotoolsPropertyConstants.java
+index 5755bfb..5496bc3 100644
+--- a/build/org.eclipse.cdt.autotools.core/src/org/eclipse/cdt/internal/autotools/core/AutotoolsPropertyConstants.java
++++ b/build/org.eclipse.cdt.autotools.core/src/org/eclipse/cdt/internal/autotools/core/AutotoolsPropertyConstants.java
+@@ -39,14 +39,14 @@ public class AutotoolsPropertyConstants {
+ public static final QualifiedName OPEN_INCLUDE_P = new QualifiedName(PREFIX, "PersistentIncludeResourceMapping"); //$NON-NLS-1$
+ public static final QualifiedName SCANNER_INFO_DIRTY = new QualifiedName(PREFIX, "ScannerInfoDirty"); // $NON-NLSp-1$
+
+- public static final String[] fACVersions = {"2.13", "2.59", "2.61", "2.68"}; // $NON-NLS-1$
++ public static final String[] fACVersions = {"2.13", "2.59", "2.61", "2.68", "2.69"}; // $NON-NLS-1$
+ public static final String AC_VERSION_2_13 = fACVersions[0];
+ public static final String AC_VERSION_2_59 = fACVersions[1];
+ public static final String AC_VERSION_2_61 = fACVersions[2];
+ public static final String AC_VERSION_2_68 = fACVersions[3];
+ public static final String LATEST_AC_VERSION = fACVersions[fACVersions.length - 1];
+
+- public static final String[] fAMVersions = {"1.4-p6", "1.9.5", "1.9.6", "1.11.1"}; // $NON-NLS-1$
++ public static final String[] fAMVersions = {"1.4-p6", "1.9.5", "1.9.6", "1.11.1", "1.11.5"}; // $NON-NLS-1$
+ public static final String LATEST_AM_VERSION = fAMVersions[fAMVersions.length - 1];
+
+ public static final String CLEAN_MAKE_TARGET_DEFAULT = "distclean"; // $NON-NLS-1$
+diff --git a/build/org.eclipse.cdt.autotools.ui/src/org/eclipse/cdt/internal/autotools/ui/preferences/AutoconfEditorPreferencePage.java b/build/org.eclipse.cdt.autotools.ui/src/org/eclipse/cdt/internal/autotools/ui/preferences/AutoconfEditorPreferencePage.java
+index 3fda416..b65a848 100644
+--- a/build/org.eclipse.cdt.autotools.ui/src/org/eclipse/cdt/internal/autotools/ui/preferences/AutoconfEditorPreferencePage.java
++++ b/build/org.eclipse.cdt.autotools.ui/src/org/eclipse/cdt/internal/autotools/ui/preferences/AutoconfEditorPreferencePage.java
+@@ -53,10 +53,10 @@ import org.eclipse.ui.model.WorkbenchViewerComparator;
+ */
+ public class AutoconfEditorPreferencePage extends AbstractEditorPreferencePage {
+
+- private static String[] fACVersions = {"2.13", "2.59", "2.61", "2.68"};
++ private static String[] fACVersions = {"2.13", "2.59", "2.61", "2.68", "2.69"};
+ public static final String LATEST_AC_VERSION = fACVersions[fACVersions.length - 1];
+
+- private static String[] fAMVersions = {"1.4-p6", "1.9.5", "1.9.6", "1.11.1"};
++ private static String[] fAMVersions = {"1.4-p6", "1.9.5", "1.9.6", "1.11.1", "1.11.5"};
+ public static final String LATEST_AM_VERSION = fAMVersions[fAMVersions.length - 1];
+
+ /** The keys of the overlay store. */
diff --git a/debian/patches/series b/debian/patches/series
index 0e73811..b996045 100644
--- a/debian/patches/series
+++ b/debian/patches/series
@@ -1,2 +1,3 @@
use-default-cppflags.patch
ebug-382496.patch
+autotools-add-distro-version-to-list.patch
diff --git a/debian/rules b/debian/rules
index 5451efc..938cac4 100755
--- a/debian/rules
+++ b/debian/rules
@@ -38,6 +38,13 @@ override_dh_auto_clean:
override_dh_auto_build:
# Do not use the auto-build with ant.
+MACROS_DIR=debian/.eclipse-build/org.eclipse.cdt.autotools.ui/macros
+override_jh_setupenvironment:
+ jh_setupenvironment
+ mkdir -p $(MACROS_DIR)
+ cd debian/docs && ./regenerateFromTexinfo.sh
+ cp debian/docs/acmacros-*.xml debian/docs/ammacros-*.xml $(MACROS_DIR)
+
override_jh_compilefeatures-arch:
cd $(BUILD_DIR)/org.eclipse.cdt.core.linux/library && \
make JAVA_HOME="$(JAVA_HOME)" ARCH=$(ECLIPSE_BUILD_ARCH) CC='gcc -D_GNU_SOURCE' CFLAGS="$(CFLAGS) -fPIC" LDFLAGS="$(LDFLAGS) -fPIC"
@@ -55,5 +62,9 @@ override_jh_installeclipse-indep:
jh_installeclipse
rm -f debian/eclipse-cdt/usr/share/eclipse/dropins/cdt/eclipse/plugins/org.eclipse.cdt.launch.remote.source*.jar
+override_dh_clean:
+ dh_clean
+ rm -rf debian/docs/*.xml
+
get-orig-source:
debian/fetch-cdt.sh
--
eclipse-cdt - Plug-in for eclipse to handle C/C++ - Debian package.
More information about the pkg-java-commits
mailing list