[SCM] eclipse-linuxtools packaging branch, master, updated. upstream/1.0.0-28-ge040b5c
Jakub Adam
jakub.adam at ktknet.cz
Thu Jun 28 17:39:22 UTC 2012
The following commit has been merged in the master branch:
commit 3788bc7a4d90823af36f265b64ec0e73b9ec7dc5
Author: Jakub Adam <jakub.adam at ktknet.cz>
Date: Wed Jun 27 22:56:17 2012 +0200
Remove eclipse-cdt-autotools binary package
Autotools integration code moved to CDT.
diff --git a/debian/changelog b/debian/changelog
index 063be48..e5a2f15 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,6 +1,8 @@
eclipse-linuxtools (1.0.0-1) UNRELEASED; urgency=low
* New upstream release.
+ * Remove eclipse-cdt-autotools binary package.
+ - The code moved to Eclipse CDT.
-- Jakub Adam <jakub.adam at ktknet.cz> Wed, 27 Jun 2012 22:49:46 +0200
diff --git a/debian/control b/debian/control
index 664a453..8fdd447 100644
--- a/debian/control
+++ b/debian/control
@@ -14,35 +14,6 @@ Build-Depends: debhelper (>= 8~),
Standards-Version: 3.9.3
Homepage: http://www.eclipse.org/linuxtools/
-Package: eclipse-cdt-autotools
-Architecture: all
-Depends: eclipse-cdt (>= 8.0.0),
- autoconf,
- automake,
- ${misc:Depends},
- ${orbit:Depends}
-Description: Autotools support for Eclipse CDT
- The Linux Distributions Autotools suite of plugins add support to
- the CDT (C/C++ Development Tools) 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
- * Help for autoconf and automake
-
Package: eclipse-cdt-valgrind
Architecture: all
Depends: eclipse-cdt,
diff --git a/debian/copyright b/debian/copyright
index fcc5841..6943862 100644
--- a/debian/copyright
+++ b/debian/copyright
@@ -38,14 +38,6 @@ Files: debian/*
Copyright: 2011, Debian Java Maintainers <pkg-java-maintainers at lists.alioth.debian.org>
License: EPL-1.0
-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: EPL-1.0
Eclipse Public License - v 1.0
.
@@ -262,10 +254,3 @@ 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
deleted file mode 100755
index dec9598..0000000
--- a/debian/docs/regenerateFromTexinfo.sh
+++ /dev/null
@@ -1,38 +0,0 @@
-#!/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 ../../../libhover/org.eclipse.linuxtools.cdt.libhover.texinfoparsers/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
deleted file mode 100644
index 34ca213..0000000
--- a/debian/docs/src/autoconf/2.69/autoconf.texi
+++ /dev/null
@@ -1,26667 +0,0 @@
-\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
deleted file mode 100644
index cb71f05..0000000
--- a/debian/docs/src/autoconf/2.69/fdl.texi
+++ /dev/null
@@ -1,505 +0,0 @@
- 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
deleted file mode 100644
index ecbd59b..0000000
--- a/debian/docs/src/autoconf/2.69/gnu-oids.texi
+++ /dev/null
@@ -1,55 +0,0 @@
- 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
deleted file mode 100644
index 4c2ffb5..0000000
--- a/debian/docs/src/autoconf/2.69/install.texi
+++ /dev/null
@@ -1,437 +0,0 @@
- 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
deleted file mode 100644
index cdcbb68..0000000
--- a/debian/docs/src/autoconf/2.69/make-stds.texi
+++ /dev/null
@@ -1,1159 +0,0 @@
- 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
deleted file mode 100644
index 69a400e..0000000
--- a/debian/docs/src/autoconf/2.69/standards.texi
+++ /dev/null
@@ -1,4256 +0,0 @@
-\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
deleted file mode 100644
index b9e94c9..0000000
--- a/debian/docs/src/autoconf/2.69/version.texi
+++ /dev/null
@@ -1,4 +0,0 @@
- 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
deleted file mode 100644
index 10b605e..0000000
--- a/debian/docs/src/automake/1.11.5/automake.texi
+++ /dev/null
@@ -1,13615 +0,0 @@
-\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
deleted file mode 100644
index 8805f1a..0000000
--- a/debian/docs/src/automake/1.11.5/fdl.texi
+++ /dev/null
@@ -1,506 +0,0 @@
- 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
deleted file mode 100644
index 94729ff..0000000
--- a/debian/docs/src/automake/1.11.5/version.texi
+++ /dev/null
@@ -1,4 +0,0 @@
- 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/updateTexinfoSource.sh b/debian/docs/updateTexinfoSource.sh
deleted file mode 100755
index 947e1ce..0000000
--- a/debian/docs/updateTexinfoSource.sh
+++ /dev/null
@@ -1,39 +0,0 @@
-#!/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
deleted file mode 100644
index e063c14..0000000
--- a/debian/eclipse-cdt-autotools.eh-install
+++ /dev/null
@@ -1 +0,0 @@
-org.eclipse.linuxtools.cdt.autotools
diff --git a/debian/eclipse.environment b/debian/eclipse.environment
index 6d8f70b..a69ce16 100644
--- a/debian/eclipse.environment
+++ b/debian/eclipse.environment
@@ -1,3 +1,2 @@
-autotools/org.eclipse.linuxtools.cdt.autotools*
profiling/org.eclipse.linuxtools*
valgrind/org.eclipse.linuxtools.valgrind*
diff --git a/debian/eclipse.features b/debian/eclipse.features
index ae0456a..5456a8e 100644
--- a/debian/eclipse.features
+++ b/debian/eclipse.features
@@ -1,5 +1,4 @@
-org.eclipse.linuxtools.cdt.autotools cdt
-org.eclipse.linuxtools.tools.launch
+org.eclipse.linuxtools.tools.launch cdt
org.eclipse.linuxtools.profiling
org.eclipse.linuxtools.valgrind cdt
org.eclipse.linuxtools.profiling.remote rse
diff --git a/debian/patches/autotools-add-distro-version-to-list.patch b/debian/patches/autotools-add-distro-version-to-list.patch
deleted file mode 100644
index 5bb9f93..0000000
--- a/debian/patches/autotools-add-distro-version-to-list.patch
+++ /dev/null
@@ -1,47 +0,0 @@
-From: Jakub Adam <jakub.adam at ktknet.cz>
-Date: Sat, 2 Jun 2012 23:13:43 +0200
-Subject: autotools-add-distro-version-to-list
-
----
- .../internal/cdt/autotools/core/AutotoolsPropertyConstants.java | 4 ++--
- .../cdt/autotools/ui/preferences/AutoconfEditorPreferencePage.java | 4 ++--
- 2 files changed, 4 insertions(+), 4 deletions(-)
-
-diff --git a/autotools/org.eclipse.linuxtools.cdt.autotools.core/src/org/eclipse/linuxtools/internal/cdt/autotools/core/AutotoolsPropertyConstants.java b/autotools/org.eclipse.linuxtools.cdt.autotools.core/src/org/eclipse/linuxtools/internal/cdt/autotools/core/AutotoolsPropertyConstants.java
-index 55ef8d3..c5aba65 100644
---- a/autotools/org.eclipse.linuxtools.cdt.autotools.core/src/org/eclipse/linuxtools/internal/cdt/autotools/core/AutotoolsPropertyConstants.java
-+++ b/autotools/org.eclipse.linuxtools.cdt.autotools.core/src/org/eclipse/linuxtools/internal/cdt/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/autotools/org.eclipse.linuxtools.cdt.autotools.ui/src/org/eclipse/linuxtools/internal/cdt/autotools/ui/preferences/AutoconfEditorPreferencePage.java b/autotools/org.eclipse.linuxtools.cdt.autotools.ui/src/org/eclipse/linuxtools/internal/cdt/autotools/ui/preferences/AutoconfEditorPreferencePage.java
-index 40df9b0..cd3f66f 100644
---- a/autotools/org.eclipse.linuxtools.cdt.autotools.ui/src/org/eclipse/linuxtools/internal/cdt/autotools/ui/preferences/AutoconfEditorPreferencePage.java
-+++ b/autotools/org.eclipse.linuxtools.cdt.autotools.ui/src/org/eclipse/linuxtools/internal/cdt/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 988545b..b38c0d7 100644
--- a/debian/patches/series
+++ b/debian/patches/series
@@ -3,4 +3,3 @@ valgrind-remove-unused-emf-dependency.patch
valgrind-remote-unversioned-rse-dependency.patch
remote-profiling-disable-rdt-proxy.patch
libhover-fix-automake-texinfo-parser.patch
-autotools-add-distro-version-to-list.patch
diff --git a/debian/rules b/debian/rules
index c55f40c..427482f 100755
--- a/debian/rules
+++ b/debian/rules
@@ -8,13 +8,6 @@ BUILD_ID:=dist
%:
dh $@ --with eclipse-helper
-MACROS_DIR=debian/.eclipse-build/org.eclipse.linuxtools.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:
jh_compilefeatures --build-opts="-DjavacTarget=1.6 -DjavacSource=1.6 -DbuildId=$(BUILD_ID) -DforceContextQualifier=$(BUILD_ID)";
@@ -22,7 +15,3 @@ override_jh_compilefeatures:
# logs and causes crash during build
override_dh_installchangelogs:
dh_installchangelogs -Xchangelog
-
-override_dh_clean:
- dh_clean
- rm -f debian/docs/*.xml
--
eclipse-linuxtools packaging
More information about the pkg-java-commits
mailing list