mirror of
git://git.sv.gnu.org/autoconf
synced 2024-12-03 02:00:36 +08:00
30fe91493d
Documents OSF1/Tru64 make behavior. Replace `VPATH = ../src' by `VPATH = ../pkg/src' in examples to make the OSF1/Tru64 make explanation clearer.
15836 lines
540 KiB
Plaintext
15836 lines
540 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
|
@comment ========================================================
|
|
@comment %**start of header
|
|
@setfilename autoconf.info
|
|
@include version.texi
|
|
@settitle Autoconf
|
|
@setchapternewpage odd
|
|
@setcontentsaftertitlepage
|
|
@finalout
|
|
|
|
@c @ovar(ARG, DEFAULT)
|
|
@c -------------------
|
|
@c The ARG is an optional argument. To be used for macro arguments in
|
|
@c their documentation (@defmac).
|
|
@macro ovar{varname}
|
|
@r{[}@var{\varname\}@r{]}
|
|
@end macro
|
|
|
|
@c @dvar(ARG, DEFAULT)
|
|
@c -------------------
|
|
@c The ARG is an optional argument, defaulting to DEFAULT. To be used
|
|
@c for macro arguments in their documentation (@defmac).
|
|
@macro dvar{varname, default}
|
|
@r{[}@var{\varname\} = @samp{\default\}@r{]}
|
|
@end macro
|
|
|
|
@c @href(URL, TITLE)
|
|
@c -----------------
|
|
@c A replacement for @uref that puts the URL in the footnotes when
|
|
@c not in HTML.
|
|
@ifhtml
|
|
@macro href{url, title}
|
|
@uref{\url\, \title\}
|
|
@end macro
|
|
@end ifhtml
|
|
@ifnothtml
|
|
@macro href{url, title}
|
|
\title\@footnote{\title\, @url{\url\}.}
|
|
@end macro
|
|
@end ifnothtml
|
|
|
|
@c Handling the indexes with Texinfo yields several different problems.
|
|
@c
|
|
@c Because we want to drop out the AC_ part of the macro names in the
|
|
@c printed manual, but not in the other outputs, we need a layer above
|
|
@c the usual @acindex etc. That's why we first define indexes such as
|
|
@c acx meant to become the macro @acindex. First of all, using ``ac_''
|
|
@c does not work with makeinfo, and using ``ac1'' doesn't work with TeX.
|
|
@c So use something more regular ``acx''. Then you finish with a printed
|
|
@c index saying ``index is not existent''. Of course: you ought to use
|
|
@c two letters :( So you use capitals.
|
|
@c
|
|
@c Second, when defining a macro in the TeX world, following spaces are
|
|
@c eaten. But then, since we embed @acxindex commands that use the end
|
|
@c of line as an end marker, the whole things wrecks itself. So make
|
|
@c sure you do *force* an additional end of line, add a ``@c''.
|
|
@c
|
|
@c Finally, you might want to get rid of TeX expansion, using --expand
|
|
@c with texi2dvi. But then you wake up an old problem: we use macros
|
|
@c in @defmac etc. where TeX does perform the expansion, but not makeinfo.
|
|
|
|
@c Define an environment variable index.
|
|
@defcodeindex ev
|
|
@c Define an output variable index.
|
|
@defcodeindex ov
|
|
@c Define a CPP variable index.
|
|
@defcodeindex cv
|
|
@c Define an Autoconf macro index that @defmac doesn't write to.
|
|
@defcodeindex AC
|
|
@c Define an Autotest macro index that @defmac doesn't write to.
|
|
@defcodeindex AT
|
|
@c Define an M4sugar macro index that @defmac doesn't write to.
|
|
@defcodeindex MS
|
|
@c Define an index for *foreign* programs: `mv' etc. Used for the
|
|
@c portability sections and so on.
|
|
@defindex pr
|
|
|
|
@c shortindexflag
|
|
@c --------------
|
|
@c Shall we factor AC_ out of the Autoconf macro index etc.?
|
|
@iftex
|
|
@set shortindexflag
|
|
@end iftex
|
|
|
|
@c @acindex{MACRO}
|
|
@c ---------------
|
|
@c Registering an AC_\MACRO\.
|
|
@ifset shortindexflag
|
|
@macro acindex{macro}
|
|
@ACindex \macro\
|
|
@c
|
|
@end macro
|
|
@end ifset
|
|
@ifclear shortindexflag
|
|
@macro acindex{macro}
|
|
@ACindex AC_\macro\
|
|
@end macro
|
|
@end ifclear
|
|
|
|
@c @ahindex{MACRO}
|
|
@c ---------------
|
|
@c Registering an AH_\MACRO\.
|
|
@macro ahindex{macro}
|
|
@ACindex AH_\macro\
|
|
@c
|
|
@end macro
|
|
|
|
@c @asindex{MACRO}
|
|
@c ---------------
|
|
@c Registering an AS_\MACRO\.
|
|
@ifset shortindexflag
|
|
@macro asindex{macro}
|
|
@MSindex \macro\
|
|
@c
|
|
@end macro
|
|
@end ifset
|
|
@ifclear shortindexflag
|
|
@macro asindex{macro}
|
|
@MSindex AS_\macro\
|
|
@end macro
|
|
@end ifclear
|
|
|
|
@c @atindex{MACRO}
|
|
@c ---------------
|
|
@c Registering an AT_\MACRO\.
|
|
@ifset shortindexflag
|
|
@macro atindex{macro}
|
|
@ATindex \macro\
|
|
@c
|
|
@end macro
|
|
@end ifset
|
|
@ifclear shortindexflag
|
|
@macro atindex{macro}
|
|
@ATindex AT_\macro\
|
|
@end macro
|
|
@end ifclear
|
|
|
|
@c @hdrindex{MACRO}
|
|
@c ---------------
|
|
@c Indexing a header.
|
|
@macro hdrindex{macro}
|
|
@prindex @file{\macro\}
|
|
@c
|
|
@end macro
|
|
|
|
@c @msindex{MACRO}
|
|
@c ---------------
|
|
@c Registering an m4_\MACRO\.
|
|
@ifset shortindexflag
|
|
@macro msindex{macro}
|
|
@MSindex \macro\
|
|
@c
|
|
@end macro
|
|
@end ifset
|
|
@ifclear shortindexflag
|
|
@macro msindex{macro}
|
|
@MSindex m4_\macro\
|
|
@end macro
|
|
@end ifclear
|
|
|
|
|
|
@c Define an index for functions: `alloca' etc. Used for the
|
|
@c portability sections and so on. We can't use `fn' (aka `fnindex),
|
|
@c since `@defmac' goes into it => we'd get all the macros too.
|
|
|
|
@c FIXME: Aaarg! It seems there are too many indices for TeX :(
|
|
@c
|
|
@c ! No room for a new @write .
|
|
@c l.112 @defcodeindex fu
|
|
@c
|
|
@c so don't define yet another one :( Just put some tags before each
|
|
@c @prindex which is actually a @funindex.
|
|
@c
|
|
@c @defcodeindex fu
|
|
@c
|
|
@c
|
|
@c @c Put the programs and functions into their own index.
|
|
@c @syncodeindex fu pr
|
|
|
|
@comment %**end of header
|
|
@comment ========================================================
|
|
|
|
@copying
|
|
|
|
This manual is for @acronym{GNU} Autoconf
|
|
(version @value{VERSION}, @value{UPDATED}),
|
|
a package for creating scripts to configure source code packages using
|
|
templates and an M4 macro package.
|
|
|
|
Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000,
|
|
2001, 2002, 2003 Free Software Foundation, Inc.
|
|
|
|
@quotation
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the @acronym{GNU} Free Documentation License,
|
|
Version 1.1 or any later version published by the Free Software
|
|
Foundation; with no Invariant Sections, with the Front-Cover texts
|
|
being ``A @acronym{GNU} Manual,'' and with the Back-Cover Texts as in
|
|
(a) below. A copy of the license is included in the section entitled
|
|
``@acronym{GNU} Free Documentation License.''
|
|
|
|
(a) The FSF's Back-Cover Text is: ``You have freedom to copy and
|
|
modify this @acronym{GNU} Manual, like @acronym{GNU} software. Copies
|
|
published by the Free Software Foundation raise funds for
|
|
@acronym{GNU} development.''
|
|
@end quotation
|
|
@end copying
|
|
|
|
|
|
|
|
@dircategory Software development
|
|
@direntry
|
|
* Autoconf: (autoconf). Create source code configuration scripts.
|
|
@end direntry
|
|
|
|
@dircategory Individual utilities
|
|
@direntry
|
|
* autoscan: (autoconf)autoscan Invocation.
|
|
Semi-automatic @file{configure.ac} writing
|
|
* ifnames: (autoconf)ifnames Invocation. Listing conditionals in source.
|
|
* autoconf: (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.
|
|
@end direntry
|
|
|
|
@titlepage
|
|
@title Autoconf
|
|
@subtitle Creating Automatic Configuration Scripts
|
|
@subtitle for version @value{VERSION}, @value{UPDATED}
|
|
@author David MacKenzie
|
|
@author Ben Elliston
|
|
@author Akim Demaille
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
@insertcopying
|
|
@end titlepage
|
|
|
|
@contents
|
|
|
|
|
|
@ifnottex
|
|
@node Top
|
|
@top Autoconf
|
|
@insertcopying
|
|
@end ifnottex
|
|
|
|
@c The master menu, created with texinfo-master-menu, goes here.
|
|
|
|
@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
|
|
* Writing Autoconf Macros:: Adding new macros to Autoconf
|
|
* Portable Shell:: Shell script 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
|
|
* Copying This Manual:: How to make copies of this manual
|
|
* Indices:: Indices of symbols, concepts, etc.
|
|
|
|
@detailmenu
|
|
--- The Detailed Node Listing ---
|
|
|
|
The @acronym{GNU} Build System
|
|
|
|
* Automake:: Escaping Makefile hell
|
|
* Libtool:: Building libraries portably
|
|
* Pointers:: More info on the @acronym{GNU} build system
|
|
|
|
Making @command{configure} Scripts
|
|
|
|
* Writing configure.ac:: 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
|
|
* configure.ac Layout:: Standard organization of @file{configure.ac}
|
|
|
|
Initialization and Output Files
|
|
|
|
* Initializing configure:: Option processing etc.
|
|
* 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 @file{Makefile}s
|
|
* 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
|
|
* 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
|
|
* UNIX Variants:: Special kludges for specific UNIX variants
|
|
|
|
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
|
|
* Fortran Compiler:: Likewise
|
|
|
|
Writing Tests
|
|
|
|
* Language Choice:: Selecting which language to use for testing
|
|
* Writing Test Programs:: Forging source files for compilers
|
|
* Running the Preprocessor:: Detecting preprocessor symbols
|
|
* Running the Compiler:: Detecting language or header features
|
|
* Running the Linker:: Detecting library features
|
|
* Run Time:: Testing for run-time 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
|
|
* 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
|
|
* Programming in M4sh:: Common shell Constructs
|
|
|
|
M4 Quotation
|
|
|
|
* Active Characters:: Characters that change the behavior of M4
|
|
* One Macro Call:: Quotation and one macro call
|
|
* Quotation and Nested Macros:: Macros calling macros
|
|
* Changequote is Evil:: Worse than INTERCAL: M4 + changequote
|
|
* Quadrigraphs:: Another way to escape special characters
|
|
* Quotation Rule Of Thumb:: One parenthesis, one quote
|
|
|
|
Using @command{autom4te}
|
|
|
|
* autom4te Invocation:: A @acronym{GNU} M4 wrapper
|
|
* Customizing autom4te:: Customizing the Autoconf package
|
|
|
|
Programming in M4sugar
|
|
|
|
* Redefined M4 Macros:: M4 builtins changed in M4sugar
|
|
* Evaluation Macros:: More quotation and evaluation control
|
|
* Forbidden Patterns:: Catching unexpanded macros
|
|
|
|
Writing Autoconf Macros
|
|
|
|
* Macro Definitions:: Basic format of an Autoconf macro
|
|
* Macro Names:: What to call your new macros
|
|
* Reporting Messages:: Notifying @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
|
|
|
|
Portable Shell Programming
|
|
|
|
* Shellology:: A zoology of shells
|
|
* Here-Documents:: Quirks and tricks
|
|
* File Descriptors:: FDs and redirections
|
|
* File System Conventions:: File- and pathnames
|
|
* Shell Substitutions:: Variable and command expansions
|
|
* Assignments:: Varying side effects of assignments
|
|
* Parentheses:: Parentheses in shell scripts
|
|
* Special Shell Variables:: Variables you should not change
|
|
* Limitations of Builtins:: Portable use of not so portable /bin/sh
|
|
* Limitations of Usual Tools:: Portable use of portable tools
|
|
* Limitations of Make:: Portable Makefiles
|
|
|
|
Manual Configuration
|
|
|
|
* Specifying Names:: Specifying the system type
|
|
* Canonicalizing:: Getting the canonical system type
|
|
* Using System Type:: What to do with the system type
|
|
|
|
Site Configuration
|
|
|
|
* External Software:: Working with other optional software
|
|
* Package Options:: Selecting optional features
|
|
* Pretty Help Strings:: Formatting help string
|
|
* 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:: @file{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
|
|
* 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:: Different calling convention
|
|
* acconfig.h:: 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_FOO_IFELSE vs AC_TRY_FOO:: A more generic scheme for testing sources
|
|
|
|
Generating Test Suites with Autotest
|
|
|
|
* Using an Autotest Test Suite:: Autotest and the user
|
|
* Writing testsuite.at:: 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 @acronym{GNU} M4 require each other?
|
|
* Why Not Imake:: Why @acronym{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
|
|
|
|
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
|
|
|
|
Copying This Manual
|
|
|
|
* GNU Free Documentation License:: License for copying this manual
|
|
|
|
Indices
|
|
|
|
* Environment Variable Index:: Index of environment variables used
|
|
* Output Variable Index:: Index of variables set in output files
|
|
* Preprocessor Symbol Index:: Index of C preprocessor symbols defined
|
|
* Autoconf Macro Index:: Index of Autoconf macros
|
|
* M4 Macro Index:: Index of M4, M4sugar, and M4sh macros
|
|
* Autotest Macro Index:: Index of Autotest macros
|
|
* Program & Function Index:: Index of those with portability problems
|
|
* Concept Index:: General index
|
|
|
|
@end detailmenu
|
|
@end menu
|
|
|
|
@c ============================================================= Introduction.
|
|
|
|
@node Introduction
|
|
@chapter Introduction
|
|
|
|
@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@dots{}'' ``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@dots{}'' The computer scientist
|
|
shouted: ``And the Chaos, where do you think it was coming from, hmm?''
|
|
|
|
---Anonymous
|
|
@end flushright
|
|
@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
|
|
@sc{unix}-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 @sc{unix} variants. There is
|
|
no need to maintain files that list the features supported by each
|
|
release of each variant of @sc{unix}.
|
|
|
|
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.
|
|
|
|
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 @acronym{GNU} build tools like Automake and
|
|
Libtool. These other tools take on jobs like the creation of a
|
|
portable, recursive @file{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
|
|
@code{#if} in C programs (@pxref{Preprocessor Symbol Index}).
|
|
|
|
Autoconf requires @acronym{GNU} M4 in order to generate the scripts. It uses
|
|
features that some @sc{unix} versions of M4, including @acronym{GNU} M4 1.3,
|
|
do not have. You must use version 1.4 or later of @acronym{GNU} M4.
|
|
|
|
@xref{Autoconf 1}, for information about upgrading from version 1.
|
|
@xref{History}, for the story of Autoconf's development. @xref{FAQ},
|
|
for answers to some common questions about Autoconf.
|
|
|
|
|
|
See the @href{http://www.gnu.org/software/autoconf/autoconf.html,
|
|
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}.
|
|
|
|
Bug reports should be preferably submitted to the
|
|
@href{http://bugs.gnu.org/cgi-bin/gnatsweb.pl?database=autoconf,
|
|
Autoconf Gnats database}, or sent to @email{bug-autoconf@@gnu.org, the
|
|
Autoconf Bugs mailing list}. 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 @acronym{CVS}; see the Autoconf
|
|
web page for details. There is also a
|
|
@href{http://subversions.gnu.org/cgi-bin/cvsweb/autoconf/, @acronym{CVS}web
|
|
interface to the Autoconf development tree}. Patches relative to the
|
|
current @acronym{CVS} version can be sent for review to the
|
|
@email{autoconf-patches@@gnu.org, Autoconf Patches mailing list}.
|
|
|
|
Because of its mission, Autoconf 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
|
|
@href{http://www.gnu.org/software/ac-archive/, Autoconf Macro
|
|
Archive}, which is kindly run by @email{simons@@computer.org,
|
|
Peter Simons}.
|
|
|
|
|
|
@c ================================================= The GNU Build System
|
|
|
|
@node The GNU Build System
|
|
@chapter The @acronym{GNU} Build System
|
|
|
|
Autoconf solves an important problem---reliable discovery of
|
|
system-specific build and run-time information---but this is only one
|
|
piece of the puzzle for the development of portable software. To this
|
|
end, the @acronym{GNU} project has developed a suite of integrated
|
|
utilities to finish the job Autoconf started: the @acronym{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 @acronym{GNU} build system for your software.
|
|
|
|
@menu
|
|
* Automake:: Escaping Makefile hell
|
|
* Libtool:: Building libraries portably
|
|
* Pointers:: More info on the @acronym{GNU} build system
|
|
@end menu
|
|
|
|
@node Automake
|
|
@section Automake
|
|
|
|
The ubiquity of @command{make} means that a @file{Makefile} is almost the
|
|
only viable way to distribute automatic build rules for software, but
|
|
one quickly runs into @command{make}'s numerous limitations. Its lack of
|
|
support for automatic dependency tracking, recursive builds in
|
|
subdirectories, reliable timestamps (e.g., for network filesystems), 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},
|
|
@code{make uninstall}, etc.). Since you are, of course, using Autoconf,
|
|
you also have to insert repetitive code in your @code{Makefile.in} to
|
|
recognize @code{@@CC@@}, @code{@@CFLAGS@@}, and other substitutions
|
|
provided by @command{configure}. Into this mess steps @dfn{Automake}.
|
|
@cindex Automake
|
|
|
|
Automake allows you to specify your build needs in a @code{Makefile.am}
|
|
file with a vastly simpler and more powerful syntax than that of a plain
|
|
@code{Makefile}, and then generates a portable @code{Makefile.in} for
|
|
use with Autoconf. For example, the @code{Makefile.am} to build and
|
|
install a simple ``Hello world'' program might look like:
|
|
|
|
@example
|
|
bin_PROGRAMS = hello
|
|
hello_SOURCES = hello.c
|
|
@end example
|
|
|
|
@noindent
|
|
The resulting @code{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} will
|
|
build the @code{hello} program, and @code{make install} will install it
|
|
in @file{/usr/local/bin} (or whatever prefix was given to
|
|
@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@enddots{}
|
|
|
|
@node Libtool
|
|
@section Libtool
|
|
|
|
Very 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, @acronym{GNU} provides a solution:
|
|
@dfn{Libtool}.
|
|
@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 @code{Makefile} 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 on its own, 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.
|
|
|
|
@node Pointers
|
|
@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 will otherwise
|
|
quickly find yourself putting lots of effort into reinventing the
|
|
services that the @acronym{GNU} build tools provide, and making the
|
|
same mistakes that they once made and overcame. (Besides, since
|
|
you're already learning Autoconf, Automake will be a piece of cake.)
|
|
|
|
There are a number of places that you can go to for more information on
|
|
the @acronym{GNU} build tools.
|
|
|
|
@itemize @minus
|
|
|
|
@item Web
|
|
|
|
The home pages for
|
|
@href{http://www.gnu.org/software/autoconf/,Autoconf},
|
|
@href{http://www.gnu.org/software/automake/,Automake}, and
|
|
@href{http://www.gnu.org/software/libtool/,Libtool}.
|
|
|
|
@item Automake Manual
|
|
|
|
@xref{Top,,Automake,automake,@acronym{GNU} Automake}, for more
|
|
information on Automake.
|
|
|
|
@item Books
|
|
|
|
The book @cite{@acronym{GNU} Autoconf, Automake and
|
|
Libtool}@footnote{@cite{@acronym{GNU} Autoconf, Automake and Libtool},
|
|
by G. V. Vaughan, B. Elliston, T. Tromey, and I. L. Taylor. New
|
|
Riders, 2000, ISBN 1578701902.} describes the complete @acronym{GNU}
|
|
build environment. You can also find the entire book on-line at
|
|
@href{http://sources.redhat.com/autobook/,``The Goat Book'' home
|
|
page}.
|
|
|
|
@item Tutorials and Examples
|
|
|
|
The @href{http://sources.redhat.com/autoconf/,Autoconf Developer Page}
|
|
maintains links to a number of Autoconf/Automake tutorials online, and
|
|
also links to the @href{http://www.gnu.org/software/ac-archive/,
|
|
Autoconf Macro Archive}.
|
|
|
|
@end itemize
|
|
|
|
@c ================================================= Making configure Scripts.
|
|
|
|
@node Making configure Scripts
|
|
@chapter Making @command{configure} Scripts
|
|
@cindex @file{aclocal.m4}
|
|
@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:
|
|
|
|
@itemize @minus
|
|
@item
|
|
one or more @file{Makefile} files, usually one in each subdirectory of the
|
|
package (@pxref{Makefile Substitutions});
|
|
|
|
@item
|
|
optionally, a C header file, the name of which is configurable,
|
|
containing @code{#define} directives (@pxref{Configuration Headers});
|
|
|
|
@item
|
|
a shell script called @file{config.status} that, when run, will recreate
|
|
the files listed above (@pxref{config.status Invocation});
|
|
|
|
@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});
|
|
|
|
@item
|
|
a file called @file{config.log} containing any messages produced by
|
|
compilers, to help debugging if @command{configure} makes a mistake.
|
|
@end itemize
|
|
|
|
@cindex @file{configure.in}
|
|
@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
|
|
@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
|
|
@command{autoheader}, and you will distribute the generated file
|
|
@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
|
|
@samp{*}. Optional files are enclosed in square brackets (@samp{[]}).
|
|
@command{autoconf} and @command{autoheader} also read the installed Autoconf
|
|
macro files (by reading @file{autoconf.m4}).
|
|
|
|
@noindent
|
|
Files used in preparing a software package for distribution:
|
|
@example
|
|
your source files --> [autoscan*] --> [configure.scan] --> configure.ac
|
|
|
|
@group
|
|
configure.ac --.
|
|
| .------> autoconf* -----> configure
|
|
[aclocal.m4] --+---+
|
|
| `-----> [autoheader*] --> [config.h.in]
|
|
[acsite.m4] ---'
|
|
@end group
|
|
|
|
Makefile.in -------------------------------> Makefile.in
|
|
@end example
|
|
|
|
@noindent
|
|
Files used in configuring a software package:
|
|
@example
|
|
@group
|
|
.-------------> [config.cache]
|
|
configure* ------------+-------------> config.log
|
|
|
|
|
[config.h.in] -. v .-> [config.h] -.
|
|
+--> config.status* -+ +--> make*
|
|
Makefile.in ---' `-> Makefile ---'
|
|
@end group
|
|
@end example
|
|
|
|
@menu
|
|
* Writing configure.ac:: 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
|
|
@end menu
|
|
|
|
@node Writing configure.ac
|
|
@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
|
|
@ref{Existing Tests}, for their descriptions. For most other features,
|
|
you can use Autoconf template macros to produce custom checks; see
|
|
@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}. 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
|
|
@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.
|
|
|
|
@menu
|
|
* Shell Script Compiler:: Autoconf as solution of a problem
|
|
* Autoconf Language:: Programming in Autoconf
|
|
* configure.ac Layout:: Standard organization of @file{configure.ac}
|
|
@end menu
|
|
|
|
@node Shell Script Compiler
|
|
@subsection A Shell Script Compiler
|
|
|
|
Just as for any other computer language, in order to properly program
|
|
@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
|
|
@command{autoconf}? A set of properly written shell functions is enough to
|
|
make it easy to write @command{configure} scripts by hand. Sigh!
|
|
Unfortunately, shell functions do not belong to the least common
|
|
denominator; therefore, where you would like to define a function and
|
|
use it ten times, you would instead need to copy its body ten times.
|
|
|
|
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 very 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
|
|
@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.
|
|
|
|
|
|
@node Autoconf Language
|
|
@subsection The Autoconf Language
|
|
@cindex quotation
|
|
|
|
The Autoconf language is very different from many other computer
|
|
languages because it treats actual code the same as plain text. Whereas
|
|
in C, for instance, data and instructions have very 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 blank
|
|
space between the macro name and the open parenthesis. Arguments should
|
|
be enclosed within the M4 quote characters @samp{[} and @samp{]}, and be
|
|
separated by commas. Any leading spaces in arguments are ignored,
|
|
unless they are quoted. You may safely leave out the quotes when the
|
|
argument is simple text, but @emph{always} quote complex arguments such
|
|
as other macro calls. This rule applies recursively for every macro
|
|
call, including macros called from other macros.
|
|
|
|
For instance:
|
|
|
|
@example
|
|
AC_CHECK_HEADER([stdio.h],
|
|
[AC_DEFINE([HAVE_STDIO_H])],
|
|
[AC_MSG_ERROR([Sorry, can't do anything for you])])
|
|
@end example
|
|
|
|
@noindent
|
|
is quoted properly. You may safely simplify its quotation to:
|
|
|
|
@example
|
|
AC_CHECK_HEADER(stdio.h,
|
|
[AC_DEFINE(HAVE_STDIO_H)],
|
|
[AC_MSG_ERROR([Sorry, can't do anything for you])])
|
|
@end example
|
|
|
|
@noindent
|
|
Notice that the argument of @code{AC_MSG_ERROR} is still quoted;
|
|
otherwise, its comma would have been interpreted as an argument separator.
|
|
|
|
The following example is wrong and dangerous, as it is underquoted:
|
|
|
|
@example
|
|
AC_CHECK_HEADER(stdio.h,
|
|
AC_DEFINE(HAVE_STDIO_H),
|
|
AC_MSG_ERROR([Sorry, can't do anything for you]))
|
|
@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:
|
|
|
|
@example
|
|
echo "Hard rock was here! --[AC_DC]"
|
|
@end example
|
|
|
|
@noindent
|
|
which will result in
|
|
|
|
@example
|
|
echo "Hard rock was here! --AC_DC"
|
|
@end example
|
|
|
|
@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}:
|
|
|
|
@example
|
|
AC_MSG_WARN([[AC_DC stinks --Iron Maiden]])
|
|
@end example
|
|
|
|
You are now able to understand one of the constructs of Autoconf that
|
|
has been continually misunderstood@dots{} The rule of thumb is that
|
|
@emph{whenever you expect macro expansion, expect quote expansion};
|
|
i.e., expect one level of quotes to be lost. For instance:
|
|
|
|
@example
|
|
AC_COMPILE_IFELSE([char b[10];],, [AC_MSG_ERROR([you lose])])
|
|
@end example
|
|
|
|
@noindent
|
|
is incorrect: here, the first argument of @code{AC_COMPILE_IFELSE} is
|
|
@samp{char b[10];} and will be expanded once, which results in
|
|
@samp{char b10;}. (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:
|
|
|
|
@example
|
|
AC_COMPILE_IFELSE([[char b[10];]],, [AC_MSG_ERROR([you lose])])
|
|
@end example
|
|
|
|
@noindent
|
|
Voil@`a, you actually produce @samp{char b[10];} this time!
|
|
|
|
The careful reader will notice that, according to these guidelines, the
|
|
``properly'' quoted @code{AC_CHECK_HEADER} example above is actually
|
|
lacking three pairs of quotes! Nevertheless, for the sake of readability,
|
|
double quotation of literals is used only where needed in this manual.
|
|
|
|
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:
|
|
|
|
@example
|
|
AC_CHECK_HEADERS(stdio.h, [], [], [])
|
|
AC_CHECK_HEADERS(stdio.h,,,)
|
|
AC_CHECK_HEADERS(stdio.h)
|
|
@end example
|
|
|
|
It is best to put each macro call on its own line in
|
|
@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
|
|
@file{configure.ac} files with a line like this:
|
|
|
|
@example
|
|
# Process this file with autoconf to produce a configure script.
|
|
@end example
|
|
|
|
@node configure.ac Layout
|
|
@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
|
|
@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.
|
|
|
|
@display
|
|
@group
|
|
Autoconf requirements
|
|
@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
|
|
@code{AC_CONFIG_FILES(@r{[}@var{file@dots{}}@r{]})}
|
|
@code{AC_OUTPUT}
|
|
@end group
|
|
@end display
|
|
|
|
|
|
@node autoscan Invocation
|
|
@section Using @command{autoscan} to Create @file{configure.ac}
|
|
@cindex @command{autoscan}
|
|
|
|
The @command{autoscan} program can help you create and/or maintain a
|
|
@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
|
|
@file{configure.ac}; it will probably need 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
|
|
@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} will
|
|
contain detailed information on why a macro is requested.
|
|
|
|
@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, whitespace, and the Autoconf macro to
|
|
output if that symbol is encountered. Lines starting with @samp{#} are
|
|
comments.
|
|
|
|
@command{autoscan} accepts the following options:
|
|
|
|
@table @option
|
|
@item --help
|
|
@itemx -h
|
|
Print a summary of the command line options and exit.
|
|
|
|
@item --version
|
|
@itemx -V
|
|
Print the version number of Autoconf and exit.
|
|
|
|
@item --verbose
|
|
@itemx -v
|
|
Print the names of the files it examines and the potentially interesting
|
|
symbols it finds in them. This output can be voluminous.
|
|
|
|
@item --include=@var{dir}
|
|
@itemx -I @var{dir}
|
|
Append @var{dir} to the include path. Multiple invocations accumulate.
|
|
|
|
@item --prepend-include=@var{dir}
|
|
@item -B @var{dir}
|
|
Prepend @var{dir} to the include path. Multiple invocations accumulate.
|
|
@end table
|
|
|
|
@node ifnames Invocation
|
|
@section Using @command{ifnames} to List Conditionals
|
|
@cindex @command{ifnames}
|
|
|
|
@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
|
|
@command{configure} needs to check for. It may help fill in some gaps in a
|
|
@file{configure.ac} generated by @command{autoscan} (@pxref{autoscan
|
|
Invocation}).
|
|
|
|
@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.
|
|
|
|
@noindent
|
|
@command{ifnames} accepts the following options:
|
|
|
|
@table @option
|
|
@item --help
|
|
@itemx -h
|
|
Print a summary of the command line options and exit.
|
|
|
|
@item --version
|
|
@itemx -V
|
|
Print the version number of Autoconf and exit.
|
|
@end table
|
|
|
|
@node autoconf Invocation
|
|
@section Using @command{autoconf} to Create @command{configure}
|
|
@cindex @command{autoconf}
|
|
|
|
To create @command{configure} from @file{configure.ac}, run the
|
|
@command{autoconf} program with no arguments. @command{autoconf} processes
|
|
@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
|
|
@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
|
|
@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.
|
|
|
|
@command{autoconf} accepts the following options:
|
|
|
|
@table @option
|
|
@item --help
|
|
@itemx -h
|
|
Print a summary of the command line options and exit.
|
|
|
|
@item --version
|
|
@itemx -V
|
|
Print the version number of Autoconf and exit.
|
|
|
|
@item --verbose
|
|
@itemx -v
|
|
Report processing steps.
|
|
|
|
@item --debug
|
|
@itemx -d
|
|
Don't remove the temporary files.
|
|
|
|
@item --force
|
|
@itemx -f
|
|
Remake @file{configure} even if newer than its input files.
|
|
|
|
@item --include=@var{dir}
|
|
@itemx -I @var{dir}
|
|
Append @var{dir} to the include path. Multiple invocations accumulate.
|
|
|
|
@item --prepend-include=@var{dir}
|
|
@item -B @var{dir}
|
|
Prepend @var{dir} to the include path. Multiple invocations accumulate.
|
|
|
|
@item --output=@var{file}
|
|
@itemx -o @var{file}
|
|
Save output (script or trace) to @var{file}. The file @option{-} stands
|
|
for the standard output.
|
|
|
|
@item --warnings=@var{category}
|
|
@itemx -W @var{category}
|
|
@evindex WARNINGS
|
|
Report the warnings related to @var{category} (which can actually be a
|
|
comma separated list). @xref{Reporting Messages}, macro
|
|
@code{AC_DIAGNOSE}, for a comprehensive list of categories. Special
|
|
values include:
|
|
|
|
@table @samp
|
|
@item all
|
|
report all the warnings
|
|
|
|
@item none
|
|
report none
|
|
|
|
@item error
|
|
treats warnings as errors
|
|
|
|
@item no-@var{category}
|
|
disable warnings falling into @var{category}
|
|
@end table
|
|
|
|
Warnings about @samp{syntax} are enabled by default, and the environment
|
|
variable @code{WARNINGS}, a comma separated list of categories, is
|
|
honored. Passing @samp{-W @var{category}} will actually behave as if
|
|
you had passed @samp{--warnings=syntax,$WARNINGS,@var{category}}. If
|
|
you want to disable the defaults and @code{WARNINGS}, but (for example)
|
|
enable the warnings about obsolete constructs, you would use @option{-W
|
|
none,obsolete}.
|
|
|
|
@cindex Back trace
|
|
@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.
|
|
|
|
@item --trace=@var{macro}[:@var{format}]
|
|
@itemx -t @var{macro}[:@var{format}]
|
|
Do not create the @command{configure} script, but list the calls to
|
|
@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
|
|
@ref{autom4te Invocation}, for details on the @var{format}.
|
|
|
|
@item --initialization
|
|
@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.
|
|
@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
|
|
@file{configure.ac}. For instance, to find the list of variables that
|
|
are substituted, use:
|
|
|
|
@example
|
|
@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
|
|
@i{More traces deleted}
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
The example below highlights the difference between @samp{$@@},
|
|
@samp{$*}, and @strong{$%}.
|
|
|
|
@example
|
|
@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]
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
The @var{format} gives you a lot of freedom:
|
|
|
|
@example
|
|
@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";
|
|
@i{More traces deleted}
|
|
@end group
|
|
@end example
|
|
|
|
@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):
|
|
|
|
@example
|
|
@group
|
|
$ @kbd{autoconf -t 'AM_MISSING_PROG:$@{|:::::|@}*'}
|
|
ACLOCAL|:::::|aclocal|:::::|$missing_dir
|
|
AUTOCONF|:::::|autoconf|:::::|$missing_dir
|
|
AUTOMAKE|:::::|automake|:::::|$missing_dir
|
|
@i{More traces deleted}
|
|
@end group
|
|
@end example
|
|
|
|
@node autoreconf Invocation
|
|
@section Using @command{autoreconf} to Update @command{configure} Scripts
|
|
@cindex @command{autoreconf}
|
|
|
|
Installing the various components of the @acronym{GNU} Build System can be
|
|
tedious: running @command{autopoint} for Gettext, @command{automake} for
|
|
@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 @acronym{GNU} Build
|
|
System in a fresh tree.
|
|
|
|
@command{autoreconf} runs @command{autoconf}, @command{autoheader},
|
|
@command{aclocal}, @command{automake}, @command{libtoolize}, and
|
|
@command{autopoint} (when appropriate) repeatedly to update the
|
|
@acronym{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.
|
|
|
|
If you install a new version of some tool, you can make
|
|
@command{autoreconf} remake @emph{all} of the files by giving it the
|
|
@option{--force} option.
|
|
|
|
@xref{Automatic Remaking}, for @file{Makefile} rules to automatically
|
|
remake @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
|
|
@option{--localdir=@var{dir}}.
|
|
|
|
@noindent
|
|
@command{autoreconf} accepts the following options:
|
|
|
|
@table @option
|
|
@item --help
|
|
@itemx -h
|
|
Print a summary of the command line options and exit.
|
|
|
|
@item --version
|
|
@itemx -V
|
|
Print the version number of Autoconf and exit.
|
|
|
|
@item --verbose
|
|
Print the name of each directory where @command{autoreconf} runs
|
|
@command{autoconf} (and @command{autoheader}, if appropriate).
|
|
|
|
@item --debug
|
|
@itemx -d
|
|
Don't remove the temporary files.
|
|
|
|
@item --force
|
|
@itemx -f
|
|
Remake even @file{configure} scripts and configuration headers that are
|
|
newer than their input files (@file{configure.ac} and, if present,
|
|
@file{aclocal.m4}).
|
|
|
|
@item --install
|
|
@itemx -i
|
|
Install the missing auxiliary files in the package. By default, files
|
|
are copied; this can be changed with @option{--symlink}.
|
|
|
|
This option triggers calls to @samp{automake --add-missing},
|
|
@samp{libtoolize}, @samp{autopoint}, etc.
|
|
|
|
@item --symlink
|
|
@itemx -s
|
|
When used with @option{--install}, install symbolic links to the missing
|
|
auxiliary files instead of copying them.
|
|
|
|
@item --make
|
|
@itemx -m
|
|
When the directories were configured, update the configuration by
|
|
running @samp{./config.status --recheck && ./config.status}, and then
|
|
run @samp{make}.
|
|
|
|
@item --include=@var{dir}
|
|
@itemx -I @var{dir}
|
|
Append @var{dir} to the include path. Multiple invocations accumulate.
|
|
|
|
@item --prepend-include=@var{dir}
|
|
@item -B @var{dir}
|
|
Prepend @var{dir} to the include path. Multiple invocations accumulate.
|
|
|
|
@item --warnings=@var{category}
|
|
@itemx -W @var{category}
|
|
@evindex WARNINGS
|
|
Report the warnings related to @var{category} (which can actually be a
|
|
comma separated list).
|
|
|
|
@table @samp
|
|
@item cross
|
|
related to cross compilation issues.
|
|
|
|
@item obsolete
|
|
report the uses of obsolete constructs.
|
|
|
|
@item portability
|
|
portability issues
|
|
|
|
@item syntax
|
|
dubious syntactic constructs.
|
|
|
|
@item all
|
|
report all the warnings
|
|
|
|
@item none
|
|
report none
|
|
|
|
@item error
|
|
treats warnings as errors
|
|
|
|
@item no-@var{category}
|
|
disable warnings falling into @var{category}
|
|
@end table
|
|
|
|
Warnings about @samp{syntax} are enabled by default, and the environment
|
|
variable @code{WARNINGS}, a comma separated list of categories, is
|
|
honored. Passing @samp{-W @var{category}} will actually behave as if
|
|
you had passed @samp{--warnings=syntax,$WARNINGS,@var{category}}. If
|
|
you want to disable the defaults and @code{WARNINGS}, but (for example)
|
|
enable the warnings about obsolete constructs, you would use @option{-W
|
|
none,obsolete}.
|
|
@end table
|
|
|
|
|
|
@c ========================================= Initialization and Output Files.
|
|
|
|
@node Setup
|
|
@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.
|
|
|
|
@menu
|
|
* Initializing configure:: Option processing etc.
|
|
* 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 @file{Makefile}s
|
|
* 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
|
|
@end menu
|
|
|
|
@node Initializing configure
|
|
@section Initializing @command{configure}
|
|
|
|
Every @command{configure} script must call @code{AC_INIT} before doing
|
|
anything else. The only other required macro is @code{AC_OUTPUT}
|
|
(@pxref{Output}).
|
|
|
|
@defmac AC_INIT (@var{package}, @var{version}, @ovar{bug-report}, @ovar{tarname})
|
|
@acindex{INIT}
|
|
Process any command-line arguments and perform various initializations
|
|
and verifications.
|
|
|
|
Set the name of the @var{package} and its @var{version}. These are
|
|
typically used in @option{--version} support, including that of
|
|
@command{configure}. The optional argument @var{bug-report} should be
|
|
the email to which users should send bug reports. The package
|
|
@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
|
|
@var{package} with @samp{GNU } stripped, lower-cased, and all characters
|
|
other than alphanumerics and underscores are changed to @samp{-}.
|
|
|
|
It is preferable that the arguments of @code{AC_INIT} be static, i.e.,
|
|
there should not be any shell computation, but they can be computed by
|
|
M4.
|
|
|
|
The following M4 macros (e.g., @code{AC_PACKAGE_NAME}), output variables
|
|
(e.g., @code{PACKAGE_NAME}), and preprocessor symbols (e.g.,
|
|
@code{PACKAGE_NAME}) are defined by @code{AC_INIT}:
|
|
|
|
@table @asis
|
|
@item @code{AC_PACKAGE_NAME}, @code{PACKAGE_NAME}
|
|
@acindex{PACKAGE_NAME}
|
|
@ovindex PACKAGE_NAME
|
|
@cvindex PACKAGE_NAME
|
|
Exactly @var{package}.
|
|
|
|
@item @code{AC_PACKAGE_TARNAME}, @code{PACKAGE_TARNAME}
|
|
@acindex{PACKAGE_TARNAME}
|
|
@ovindex PACKAGE_TARNAME
|
|
@cvindex PACKAGE_TARNAME
|
|
Exactly @var{tarname}.
|
|
|
|
@item @code{AC_PACKAGE_VERSION}, @code{PACKAGE_VERSION}
|
|
@acindex{PACKAGE_VERSION}
|
|
@ovindex PACKAGE_VERSION
|
|
@cvindex PACKAGE_VERSION
|
|
Exactly @var{version}.
|
|
|
|
@item @code{AC_PACKAGE_STRING}, @code{PACKAGE_STRING}
|
|
@acindex{PACKAGE_STRING}
|
|
@ovindex PACKAGE_STRING
|
|
@cvindex PACKAGE_STRING
|
|
Exactly @samp{@var{package} @var{version}}.
|
|
|
|
@item @code{AC_PACKAGE_BUGREPORT}, @code{PACKAGE_BUGREPORT}
|
|
@acindex{PACKAGE_BUGREPORT}
|
|
@ovindex PACKAGE_BUGREPORT
|
|
@cvindex PACKAGE_BUGREPORT
|
|
Exactly @var{bug-report}.
|
|
@end table
|
|
@end defmac
|
|
|
|
|
|
@node Notices
|
|
@section Notices in @command{configure}
|
|
|
|
The following macros manage version numbers for @command{configure}
|
|
scripts. Using them is optional.
|
|
|
|
@c FIXME: AC_PREREQ should not be here
|
|
@defmac AC_PREREQ (@var{version})
|
|
@acindex{PREREQ}
|
|
@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:
|
|
|
|
@example
|
|
AC_PREREQ(@value{VERSION})
|
|
@end example
|
|
|
|
This macro is the only macro that may be used before @code{AC_INIT}, but
|
|
for consistency, you are invited not to do so.
|
|
@end defmac
|
|
|
|
@defmac AC_COPYRIGHT (@var{copyright-notice})
|
|
@acindex{COPYRIGHT}
|
|
@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
|
|
@var{copyright-notice}.
|
|
|
|
The @var{copyright-notice} will show up in both the head of
|
|
@command{configure} and in @samp{configure --version}.
|
|
@end defmac
|
|
|
|
|
|
@defmac AC_REVISION (@var{revision-info})
|
|
@acindex{REVISION}
|
|
@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 @acronym{RCS} or @acronym{CVS} changing it when you check in
|
|
@command{configure}. That way, you can determine easily which revision of
|
|
@file{configure.ac} a particular @command{configure} corresponds to.
|
|
|
|
For example, this line in @file{configure.ac}:
|
|
|
|
@c The asis prevents RCS from changing the example in the manual.
|
|
@example
|
|
AC_REVISION($@asis{Revision: 1.30 }$)
|
|
@end example
|
|
|
|
@noindent
|
|
produces this in @command{configure}:
|
|
|
|
@example
|
|
#! /bin/sh
|
|
# From configure.ac Revision: 1.30
|
|
@end example
|
|
@end defmac
|
|
|
|
|
|
@node Input
|
|
@section Finding @command{configure} Input
|
|
|
|
|
|
@defmac AC_CONFIG_SRCDIR (@var{unique-file-in-source-dir})
|
|
@acindex{CONFIG_SRCDIR}
|
|
@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.
|
|
@end defmac
|
|
|
|
|
|
@c FIXME: Remove definitively once --install explained.
|
|
@c
|
|
@c Small packages may store all their macros in @code{aclocal.m4}. As the
|
|
@c set of macros grows, or for maintenance reasons, a maintainer may prefer
|
|
@c to split the macros in several files. In this case, Autoconf must be
|
|
@c told which files to load, and in which order.
|
|
@c
|
|
@c @defmac AC_INCLUDE (@var{file}@dots{})
|
|
@c @acindex{INCLUDE}
|
|
@c @c FIXME: There is no longer shell globbing.
|
|
@c Read the macro definitions that appear in the listed files. A list of
|
|
@c space-separated filenames or shell globbing patterns is expected. The
|
|
@c files will be read in the order they're listed.
|
|
@c
|
|
@c Because the order of definition of macros is important (only the last
|
|
@c definition of a macro is used), beware that it is @code{AC_INIT} that
|
|
@c loads @file{acsite.m4} and @file{aclocal.m4}. Note that
|
|
@c @code{AC_INCLUDE}ing a file before @code{AC_INIT} or within
|
|
@c @file{aclocal.m4} is different from doing so after @code{AC_INIT}: in
|
|
@c the latter case, non-macro lines from included files may end up in the
|
|
@c @file{configure} script, whereas in the former case, they'd be discarded
|
|
@c just like any text that appear before @code{AC_INIT}.
|
|
@c @end defmac
|
|
|
|
Packages that do manual configuration or use the @code{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.
|
|
|
|
@defmac AC_CONFIG_AUX_DIR (@var{dir})
|
|
@acindex{CONFIG_AUX_DIR}
|
|
Use the auxiliary build tools (e.g., @file{install-sh},
|
|
@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
|
|
@file{@var{srcdir}} or @file{@var{srcdir}/..} or
|
|
@file{@var{srcdir}/../..}, whichever is the first that contains
|
|
@file{install-sh}. The other files are not checked for, so that using
|
|
@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 @code{make} have a rule that creates
|
|
@file{install} from it if there is no @file{Makefile}.
|
|
|
|
The auxiliary directory should not be named @file{aux} for portability
|
|
to MS-DOS, because the filename @file{aux} is reserved under MS-DOS.
|
|
@end defmac
|
|
|
|
Similarly, packages that use @command{aclocal} should declare where
|
|
local macros can be found using @code{AC_CONFIG_MACRO_DIR}.
|
|
|
|
@defmac AC_CONFIG_MACRO_DIR (@var{dir})
|
|
@acindex{CONFIG_MACRO_DIR}
|
|
Future versions of @command{autopoint}, @command{libtoolize},
|
|
@command{aclocal} and @command{autoreconf} will use directory
|
|
@var{dir} as the location of additional local Autoconf macros. Be
|
|
sure to call this macro directly from @file{configure.ac} so that
|
|
tools that install macros for @command{aclocal} can find the
|
|
declaration before @option{--trace} can be called safely.
|
|
@end defmac
|
|
|
|
|
|
@node Output
|
|
@section 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
|
|
@file{config.status}, which will create the @file{Makefile}s and any
|
|
other files resulting from configuration. This is the only required
|
|
macro besides @code{AC_INIT} (@pxref{Input}).
|
|
|
|
@defmac AC_OUTPUT
|
|
@acindex{OUTPUT}
|
|
@cindex Instantiation
|
|
Generate @file{config.status} and launch it. Call this macro once, at
|
|
the end of @file{configure.ac}.
|
|
|
|
@file{config.status} will perform all the configuration actions: all the
|
|
output files (see @ref{Configuration Files}, macro
|
|
@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
|
|
@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 will be
|
|
executed by @code{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
|
|
@ref{Configuration Commands, , Running Arbitrary Configuration
|
|
Commands}.
|
|
@end defmac
|
|
|
|
Historically, the usage of @code{AC_OUTPUT} was somewhat different.
|
|
@xref{Obsolete Macros}, for a description of the arguments that
|
|
@code{AC_OUTPUT} used to support.
|
|
|
|
|
|
If you run @command{make} in subdirectories, you should run it using the
|
|
@code{make} variable @code{MAKE}. Most versions of @command{make} set
|
|
@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.
|
|
|
|
@defmac AC_PROG_MAKE_SET
|
|
@acindex{PROG_MAKE_SET}
|
|
@ovindex SET_MAKE
|
|
If @command{make} predefines the Make variable @code{MAKE}, define
|
|
output variable @code{SET_MAKE} to be empty. Otherwise, define
|
|
@code{SET_MAKE} to contain @samp{MAKE=make}. Calls @code{AC_SUBST} for
|
|
@code{SET_MAKE}.
|
|
@end defmac
|
|
|
|
If you use this macro, place a line like this in each @file{Makefile.in}
|
|
that runs @code{MAKE} on other directories:
|
|
|
|
@example
|
|
@@SET_MAKE@@
|
|
@end example
|
|
|
|
|
|
|
|
@node Configuration Actions
|
|
@section Performing Configuration Actions
|
|
|
|
@file{configure} is designed so that it appears to do everything itself,
|
|
but there is actually a hidden slave: @file{config.status}.
|
|
@file{configure} is in charge of examining your system, but it is
|
|
@file{config.status} that actually takes the proper actions based on the
|
|
results of @file{configure}. The most typical task of
|
|
@file{config.status} is to @emph{instantiate} files.
|
|
|
|
This section describes the common behavior of the four standard
|
|
instantiating macros: @code{AC_CONFIG_FILES}, @code{AC_CONFIG_HEADERS},
|
|
@code{AC_CONFIG_COMMANDS} and @code{AC_CONFIG_LINKS}. They all
|
|
have this prototype:
|
|
|
|
@c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
|
|
@c awful.
|
|
@example
|
|
AC_CONFIG_FOOS(@var{tag}@dots{}, [@var{commands}], [@var{init-cmds}])
|
|
@end example
|
|
|
|
@noindent
|
|
where the arguments are:
|
|
|
|
@table @var
|
|
@item @var{tag}@dots{}
|
|
A whitespace-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
|
|
|
|
@example
|
|
@dots{} && my_foos="$my_foos fooo"
|
|
@dots{} && my_foos="$my_foos foooo"
|
|
AC_CONFIG_FOOS($my_foos)
|
|
@end example
|
|
|
|
@noindent
|
|
and use this instead:
|
|
|
|
@example
|
|
@dots{} && AC_CONFIG_FOOS(fooo)
|
|
@dots{} && AC_CONFIG_FOOS(foooo)
|
|
@end example
|
|
|
|
The macros @code{AC_CONFIG_FILES} and @code{AC_CONFIG_HEADERS} use
|
|
special @var{tag}s: they may have the form @samp{@var{output}} or
|
|
@samp{@var{output}:@var{inputs}}. The file @var{output} is instantiated
|
|
from its templates, @var{inputs} (defaulting to @samp{@var{output}.in}).
|
|
|
|
For instance
|
|
@samp{AC_CONFIG_FILES(Makefile:boiler/top.mk:boiler/bot.mk)} asks for
|
|
the creation of @file{Makefile} that will be the expansion of the
|
|
output variables in the concatenation of @file{boiler/top.mk} and
|
|
@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
|
|
@var{inputs}. You most probably don't need to use this in
|
|
@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 filenames. In the latter
|
|
case they are first looked for in the build tree, and then in the source
|
|
tree.
|
|
|
|
@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 the commands to run. The commands are run each time a @var{tag}
|
|
request is given to @file{config.status}, typically each time the file
|
|
@file{@var{tag}} is created.
|
|
|
|
The variables set during the execution of @command{configure} are
|
|
@emph{not} available here: you first need to set them via the
|
|
@var{init-cmds}. Nonetheless the following variables are precomputed:
|
|
|
|
@table @code
|
|
@item srcdir
|
|
The path from the top build directory to the top source directory. This
|
|
is what @command{configure}'s option @option{--srcdir} sets.
|
|
|
|
@item ac_top_srcdir
|
|
The path from the current build directory to the top source directory.
|
|
|
|
|
|
@item ac_top_builddir
|
|
The path from the current build directory to the top build directory.
|
|
It can be empty, or else ends with a slash, so that you may concatenate
|
|
it.
|
|
|
|
@item ac_srcdir
|
|
The path from the current build directory to the corresponding source
|
|
directory.
|
|
@end table
|
|
|
|
@noindent
|
|
The @dfn{current} directory refers to the directory (or
|
|
pseudo-directory) containing the input part of @var{tags}. For
|
|
instance, running
|
|
|
|
@example
|
|
AC_CONFIG_COMMANDS([deep/dir/out:in/in.in], [@dots{}], [@dots{}])
|
|
@end example
|
|
|
|
@noindent
|
|
with @option{--srcdir=../package} produces the following values:
|
|
|
|
@example
|
|
# Argument of --srcdir
|
|
srcdir='../package'
|
|
# Reversing deep/dir
|
|
ac_top_builddir='../../'
|
|
# Concatenation of $ac_top_builddir and srcdir
|
|
ac_top_srcdir='../../../package'
|
|
# Concatenation of $ac_top_srcdir and deep/dir
|
|
ac_srcdir='../../../package/deep/dir'
|
|
@end example
|
|
|
|
@noindent
|
|
independently of @samp{in/in.in}.
|
|
|
|
@item init-cmds
|
|
Shell commands output @emph{unquoted} near the beginning of
|
|
@file{config.status}, and executed each time @file{config.status} runs
|
|
(regardless of the tag). Because they are unquoted, for example,
|
|
@samp{$var} will be 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
|
|
@var{init-cmds} share the same name space and may overwrite each other
|
|
in unpredictable ways. Sorry@enddots{}
|
|
@end table
|
|
|
|
All these macros can be called multiple times, with different
|
|
@var{tag}s, of course!
|
|
|
|
|
|
@node Configuration Files
|
|
@section Creating Configuration Files
|
|
|
|
Be sure to read the previous section, @ref{Configuration Actions}.
|
|
|
|
@defmac AC_CONFIG_FILES (@var{file}@dots{}, @ovar{cmds}, @ovar{init-cmds})
|
|
@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.
|
|
@c Before we used to have this feature, which was later rejected
|
|
@c because it complicates the write of Makefiles:
|
|
@c If the file would be unchanged, it is left untouched, to preserve
|
|
@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, @file{Makefile}s 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:
|
|
|
|
@example
|
|
AC_CONFIG_FILES([Makefile src/Makefile man/Makefile X/Imakefile])
|
|
AC_CONFIG_FILES([autoconf], [chmod +x autoconf])
|
|
@end example
|
|
|
|
You can override an input file name by appending to @var{file} a
|
|
colon-separated list of input files. Examples:
|
|
|
|
@example
|
|
AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk]
|
|
[lib/Makefile:boiler/lib.mk])
|
|
@end example
|
|
|
|
@noindent
|
|
Doing this allows you to keep your file names acceptable to MS-DOS, or
|
|
to prepend and/or append boilerplate to the file.
|
|
@end defmac
|
|
|
|
|
|
|
|
@node Makefile Substitutions
|
|
@section Substitutions in Makefiles
|
|
|
|
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} will create a @file{Makefile} in that directory.
|
|
To create a @file{Makefile}, @command{configure} performs a simple variable
|
|
substitution, replacing occurrences of @samp{@@@var{variable}@@} in
|
|
@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
|
|
@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 @file{Makefile}; that
|
|
way, the user has to properly configure the package for the local system
|
|
before compiling it.
|
|
|
|
@xref{Makefile Conventions,, Makefile Conventions, standards, The
|
|
@acronym{GNU} Coding Standards}, for more information on what to put in
|
|
@file{Makefile}s.
|
|
|
|
@menu
|
|
* Preset Output Variables:: Output variables that are always set
|
|
* Installation Directory Variables:: Other preset output variables
|
|
* Build Directories:: Supporting multiple concurrent compiles
|
|
* Automatic Remaking:: Makefile rules for configuring
|
|
@end menu
|
|
|
|
@node Preset Output Variables
|
|
@subsection Preset 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. They all are
|
|
precious variables (@pxref{Setting Output Variables},
|
|
@code{AC_ARG_VAR}).
|
|
|
|
@c Just say no to ASCII sorting! We're humans, not computers.
|
|
@c These variables are listed as they would be in a dictionary:
|
|
@c actor
|
|
@c Actress
|
|
@c actress
|
|
|
|
@defvar CFLAGS
|
|
@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 programs to test for C features.
|
|
@end defvar
|
|
|
|
@defvar configure_input
|
|
@ovindex configure_input
|
|
A comment saying that the file was generated automatically by
|
|
@command{configure} and giving the name of the input file.
|
|
@code{AC_OUTPUT} adds a comment line containing this variable to the top
|
|
of every @file{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:
|
|
|
|
@example
|
|
#! /bin/sh
|
|
# @@configure_input@@
|
|
@end example
|
|
|
|
@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.
|
|
@end defvar
|
|
|
|
@defvar CPPFLAGS
|
|
@ovindex CPPFLAGS
|
|
Header file search directory (@option{-I@var{dir}}) and any other
|
|
miscellaneous options for the C and 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 compiling or
|
|
preprocessing programs to test for C and C++ features.
|
|
@end defvar
|
|
|
|
@defvar CXXFLAGS
|
|
@ovindex CXXFLAGS
|
|
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_CXX} (or empty if you don't).
|
|
@command{configure} uses this variable when compiling programs to test for
|
|
C++ features.
|
|
@end defvar
|
|
|
|
@defvar DEFS
|
|
@ovindex DEFS
|
|
@option{-D} options to pass to the C compiler. If @code{AC_CONFIG_HEADERS}
|
|
is called, @command{configure} replaces @samp{@@DEFS@@} with
|
|
@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.
|
|
@end defvar
|
|
|
|
@defvar ECHO_C
|
|
@defvarx ECHO_N
|
|
@defvarx ECHO_T
|
|
@ovindex ECHO_C
|
|
@ovindex ECHO_N
|
|
@ovindex ECHO_T
|
|
How does one suppress the trailing newline from @code{echo} for
|
|
question-answer message pairs? These variables provide a way:
|
|
|
|
@example
|
|
echo $ECHO_N "And the winner is... $ECHO_C"
|
|
sleep 100000000000
|
|
echo "$@{ECHO_T@}dead."
|
|
@end example
|
|
|
|
@noindent
|
|
Some old and uncommon @code{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.
|
|
@end defvar
|
|
|
|
@defvar FCFLAGS
|
|
@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).
|
|
@command{configure} uses this variable when compiling programs to test for
|
|
Fortran features.
|
|
@end defvar
|
|
|
|
@defvar FFLAGS
|
|
@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).
|
|
@command{configure} uses this variable when compiling programs to test for
|
|
Fortran 77 features.
|
|
@end defvar
|
|
|
|
@defvar LDFLAGS
|
|
@ovindex LDFLAGS
|
|
Stripping (@option{-s}), path (@option{-L}), and any other miscellaneous
|
|
options for the linker. Don't use this variable to pass library names
|
|
(@option{-l}) to the linker, use @code{LIBS} instead. If it is not set
|
|
in the environment when @command{configure} runs, the default value is empty.
|
|
@command{configure} uses this variable when linking programs to test for
|
|
C, C++, and Fortran features.
|
|
@end defvar
|
|
|
|
@defvar LIBS
|
|
@ovindex LIBS
|
|
@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
|
|
@ref{Libraries}. @command{configure} uses this variable when linking
|
|
programs to test for C, C++, and Fortran features.
|
|
@end defvar
|
|
|
|
@defvar builddir
|
|
@ovindex builddir
|
|
Rigorously equal to @samp{.}. Added for symmetry only.
|
|
@end defvar
|
|
|
|
@defvar abs_builddir
|
|
@ovindex abs_builddir
|
|
Absolute path of @code{builddir}.
|
|
@end defvar
|
|
|
|
@defvar top_builddir
|
|
@ovindex top_builddir
|
|
The relative path to the top-level of the current build tree. In the
|
|
top-level directory, this is the same as @code{builddir}.
|
|
@end defvar
|
|
|
|
@defvar abs_top_builddir
|
|
@ovindex abs_top_builddir
|
|
Absolute path of @code{top_builddir}.
|
|
@end defvar
|
|
|
|
@defvar srcdir
|
|
@ovindex srcdir
|
|
The relative path to the directory that contains the source code for
|
|
that @file{Makefile}.
|
|
@end defvar
|
|
|
|
@defvar abs_srcdir
|
|
@ovindex abs_srcdir
|
|
Absolute path of @code{srcdir}.
|
|
@end defvar
|
|
|
|
@defvar top_srcdir
|
|
@ovindex top_srcdir
|
|
The relative path to the top-level source code directory for the
|
|
package. In the top-level directory, this is the same as @code{srcdir}.
|
|
@end defvar
|
|
|
|
@defvar abs_top_srcdir
|
|
@ovindex abs_top_srcdir
|
|
Absolute path of @code{top_srcdir}.
|
|
@end defvar
|
|
|
|
@node Installation Directory Variables
|
|
@subsection Installation Directory Variables
|
|
|
|
The following variables specify the directories where the package will
|
|
be installed, see @ref{Directory Variables,, Variables for
|
|
Installation Directories, standards, The @acronym{GNU} Coding
|
|
Standards}, for more information. See the end of this section for
|
|
details on when and how to use these variables.
|
|
|
|
@defvar bindir
|
|
@ovindex bindir
|
|
The directory for installing executables that users run.
|
|
@end defvar
|
|
|
|
@defvar datadir
|
|
@ovindex datadir
|
|
The directory for installing read-only architecture-independent data.
|
|
@end defvar
|
|
|
|
@defvar exec_prefix
|
|
@ovindex exec_prefix
|
|
The installation prefix for architecture-dependent files. By default
|
|
it's the same as @var{prefix}. You should avoid installing anything
|
|
directly to @var{exec_prefix}. However, the default value for
|
|
directories containing architecture-dependent files should be relative
|
|
to @var{exec_prefix}.
|
|
@end defvar
|
|
|
|
@defvar includedir
|
|
@ovindex includedir
|
|
The directory for installing C header files.
|
|
@end defvar
|
|
|
|
@defvar infodir
|
|
@ovindex infodir
|
|
The directory for installing documentation in Info format.
|
|
@end defvar
|
|
|
|
@defvar libdir
|
|
@ovindex libdir
|
|
The directory for installing object code libraries.
|
|
@end defvar
|
|
|
|
@defvar libexecdir
|
|
@ovindex libexecdir
|
|
The directory for installing executables that other programs run.
|
|
@end defvar
|
|
|
|
@defvar localstatedir
|
|
@ovindex localstatedir
|
|
The directory for installing modifiable single-machine data.
|
|
@end defvar
|
|
|
|
@defvar mandir
|
|
@ovindex mandir
|
|
The top-level directory for installing documentation in man format.
|
|
@end defvar
|
|
|
|
@defvar oldincludedir
|
|
@ovindex oldincludedir
|
|
The directory for installing C header files for non-GCC compilers.
|
|
@end defvar
|
|
|
|
@defvar prefix
|
|
@ovindex prefix
|
|
The common installation prefix for all files. If @var{exec_prefix}
|
|
is defined to a different value, @var{prefix} is used only for
|
|
architecture-independent files.
|
|
@end defvar
|
|
|
|
@defvar sbindir
|
|
@ovindex sbindir
|
|
The directory for installing executables that system
|
|
administrators run.
|
|
@end defvar
|
|
|
|
@defvar sharedstatedir
|
|
@ovindex sharedstatedir
|
|
The directory for installing modifiable architecture-independent data.
|
|
@end defvar
|
|
|
|
@defvar sysconfdir
|
|
@ovindex sysconfdir
|
|
The directory for installing read-only single-machine data.
|
|
@end defvar
|
|
|
|
|
|
Most of these variables have values that rely on @code{prefix} or
|
|
@code{exec_prefix}. It is deliberate that the directory output
|
|
variables keep them unexpanded: typically @samp{@@datadir@@} will be
|
|
replaced by @samp{$@{prefix@}/share}, not @samp{/usr/local/share}.
|
|
|
|
This behavior is mandated by the @acronym{GNU} coding standards, so that when
|
|
the user runs:
|
|
|
|
@table @samp
|
|
@item make
|
|
she can still specify a different prefix from the one specified to
|
|
@command{configure}, in which case, if needed, the package shall hard
|
|
code dependencies corresponding to the make-specified prefix.
|
|
|
|
@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.
|
|
@end table
|
|
|
|
In order to support these features, it is essential that @code{datadir}
|
|
remains being defined as @samp{$@{prefix@}/share} to depend upon 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")}, you should add
|
|
@samp{-DDATADIR="$(datadir)"} to your @code{CPPFLAGS}.
|
|
|
|
Similarly you should not rely on @code{AC_OUTPUT_FILES} to replace
|
|
@code{datadir} and friends in your shell scripts and other files, rather
|
|
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:
|
|
|
|
@example
|
|
@group
|
|
edit = sed \
|
|
-e 's,@@datadir\@@,$(pkgdatadir),g' \
|
|
-e 's,@@prefix\@@,$(prefix),g'
|
|
@end group
|
|
|
|
@group
|
|
autoconf: Makefile $(srcdir)/autoconf.in
|
|
rm -f autoconf autoconf.tmp
|
|
$(edit) $(srcdir)/autoconf.in >autoconf.tmp
|
|
chmod +x autoconf.tmp
|
|
mv autoconf.tmp autoconf
|
|
@end group
|
|
|
|
@group
|
|
autoheader: Makefile $(srcdir)/autoheader.in
|
|
rm -f autoheader autoheader.tmp
|
|
$(edit) $(srcdir)/autoconf.in >autoheader.tmp
|
|
chmod +x autoheader.tmp
|
|
mv autoheader.tmp autoheader
|
|
@end group
|
|
@end example
|
|
|
|
Some details are noteworthy:
|
|
|
|
@table @samp
|
|
@item @@datadir\@@
|
|
The backslash prevents @command{configure} from replacing
|
|
@samp{@@datadir@@} in the sed expression itself.
|
|
|
|
@item $(pkgdatadir)
|
|
Don't use @samp{@@pkgdatadir@@}! Use the matching makefile variable
|
|
instead.
|
|
|
|
@item ,
|
|
Don't use @samp{/} in the sed expression(s) since most likely the
|
|
variables you use, such as @samp{$(pkgdatadir)}, will contain
|
|
some.
|
|
|
|
@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}.
|
|
|
|
@item Separated dependencies and Single Suffix Rules
|
|
You can't use them! The above snippet cannot be (portably) rewritten
|
|
as:
|
|
|
|
@example
|
|
autoconf autoheader: Makefile
|
|
@group
|
|
.in:
|
|
rm -f $@@ $@@.tmp
|
|
$(edit) $< >$@@.tmp
|
|
chmod +x $@@.tmp
|
|
mv $@@.tmp $@@
|
|
@end group
|
|
@end example
|
|
|
|
@xref{Limitations of Make}, for details.
|
|
|
|
@item @samp{$(srcdir)}
|
|
Be sure to specify the path to the sources, otherwise the package won't
|
|
support separated builds.
|
|
@end table
|
|
|
|
|
|
@node Build Directories
|
|
@subsection Build Directories
|
|
|
|
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. @acronym{GNU} Make
|
|
and most other recent @command{make} programs can do this. Older
|
|
@command{make} programs do not support @code{VPATH}; when using them, the
|
|
source code must be in the same directory as the object files.
|
|
|
|
To support @code{VPATH}, each @file{Makefile.in} should contain two
|
|
lines that look like:
|
|
|
|
@example
|
|
srcdir = @@srcdir@@
|
|
VPATH = @@srcdir@@
|
|
@end example
|
|
|
|
Do not set @code{VPATH} to the value of another variable, for example
|
|
@samp{VPATH = $(srcdir)}, because some versions of @command{make} do not do
|
|
variable substitutions on the value of @code{VPATH}.
|
|
|
|
@command{configure} substitutes the correct value for @code{srcdir} when
|
|
it produces @file{Makefile}.
|
|
|
|
Do not use the @code{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, @file{Makefile} command lines should always refer to source
|
|
files by prefixing them with @samp{$(srcdir)/}. For example:
|
|
|
|
@example
|
|
time.info: time.texinfo
|
|
$(MAKEINFO) $(srcdir)/time.texinfo
|
|
@end example
|
|
|
|
@node Automatic Remaking
|
|
@subsection Automatic Remaking
|
|
|
|
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
|
|
@code{VPATH} mechanism.
|
|
|
|
The @file{stamp-} files are necessary because the timestamps of
|
|
@file{config.h.in} and @file{config.h} will not be changed if remaking
|
|
them does not change their contents. This feature avoids unnecessary
|
|
recompilation. You should include the file @file{stamp-h.in} your
|
|
package's distribution, so @command{make} will consider
|
|
@file{config.h.in} up to date. Don't use @command{touch}
|
|
(@pxref{Limitations of Usual Tools}), rather use @command{echo} (using
|
|
@command{date} would cause needless differences, hence @acronym{CVS}
|
|
conflicts etc.).
|
|
|
|
@example
|
|
@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
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
(Be careful if you copy these lines directly into your Makefile, as you
|
|
will need to convert the indented lines to start with the tab character.)
|
|
|
|
In addition, you should use @samp{AC_CONFIG_FILES([stamp-h], [echo
|
|
timestamp > stamp-h])} so @file{config.status} will ensure that
|
|
@file{config.h} is considered up to date. @xref{Output}, for more
|
|
information about @code{AC_OUTPUT}.
|
|
|
|
@xref{config.status Invocation}, for more examples of handling
|
|
configuration-related dependencies.
|
|
|
|
@node Configuration Headers
|
|
@section Configuration Header Files
|
|
@cindex Configuration Header
|
|
@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
|
|
@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. It should be called 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}). Use @samp{#include <config.h>}
|
|
instead of @samp{#include "config.h"}, and pass the C compiler a
|
|
@option{-I.} option (or @option{-I..}; whichever directory contains
|
|
@file{config.h}). That way, even if the source directory is configured
|
|
itself (perhaps to make a distribution), other build directories can
|
|
also be configured without finding the @file{config.h} from the source
|
|
directory.
|
|
|
|
@defmac AC_CONFIG_HEADERS (@var{header} @dots{}, @ovar{cmds}, @ovar{init-cmds})
|
|
@acindex{CONFIG_HEADERS}
|
|
@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
|
|
whitespace-separated list @var{header} containing C preprocessor
|
|
@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
|
|
@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. Examples:
|
|
|
|
@example
|
|
AC_CONFIG_HEADERS([config.h:config.hin])
|
|
AC_CONFIG_HEADERS([defines.h:defs.pre:defines.h.in:defs.post])
|
|
@end example
|
|
|
|
@noindent
|
|
Doing this allows you to keep your file names acceptable to MS-DOS, or
|
|
to prepend and/or append boilerplate to the file.
|
|
@end defmac
|
|
|
|
@xref{Configuration Actions}, for more details on @var{header}.
|
|
|
|
@menu
|
|
* Header Templates:: Input for the configuration headers
|
|
* autoheader Invocation:: How to create configuration templates
|
|
* Autoheader Macros:: How to specify CPP templates
|
|
@end menu
|
|
|
|
@node Header Templates
|
|
@subsection Configuration Header Templates
|
|
@cindex Configuration Header Template
|
|
@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
|
|
@file{configure.ac} makes these calls:
|
|
|
|
@example
|
|
AC_CONFIG_HEADERS([conf.h])
|
|
AC_CHECK_HEADERS([unistd.h])
|
|
@end example
|
|
|
|
@noindent
|
|
Then you could have code like the following in @file{conf.h.in}. On
|
|
systems that have @file{unistd.h}, @command{configure} will @samp{#define}
|
|
@samp{HAVE_UNISTD_H} to 1. On other systems, the whole line will be
|
|
commented out (in case the system predefines that symbol).
|
|
|
|
@example
|
|
@group
|
|
/* Define as 1 if you have unistd.h. */
|
|
#undef HAVE_UNISTD_H
|
|
@end group
|
|
@end example
|
|
|
|
Pay attention that @samp{#undef} is in the first column, and there is
|
|
nothing behind @samp{HAVE_UNISTD_H}, not even white spaces. You can
|
|
then decode the configuration header using the preprocessor directives:
|
|
|
|
@example
|
|
@group
|
|
#include <conf.h>
|
|
|
|
#if HAVE_UNISTD_H
|
|
# include <unistd.h>
|
|
#else
|
|
/* We are in trouble. */
|
|
#endif
|
|
@end group
|
|
@end example
|
|
|
|
The use of old form templates, with @samp{#define} instead of
|
|
@samp{#undef} is strongly discouraged. Similarly with old templates
|
|
with comments on the same line as the @samp{#undef}. Anyway, putting
|
|
comments in preprocessor macros has never been a good idea.
|
|
|
|
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}.
|
|
|
|
|
|
@node autoheader Invocation
|
|
@subsection Using @command{autoheader} to Create @file{config.h.in}
|
|
@cindex @command{autoheader}
|
|
|
|
The @command{autoheader} program can create a template file of C
|
|
@samp{#define} statements for @command{configure} to use. If
|
|
@file{configure.ac} invokes @code{AC_CONFIG_HEADERS(@var{file})},
|
|
@command{autoheader} creates @file{@var{file}.in}; if multiple file
|
|
arguments are given, the first one is used. Otherwise,
|
|
@command{autoheader} creates @file{config.h.in}.
|
|
|
|
In order to do its job, @command{autoheader} needs you to document all
|
|
of the symbols that you might use; i.e., there must be at least one
|
|
@code{AC_DEFINE} or one @code{AC_DEFINE_UNQUOTED} call with a third
|
|
argument for each symbol (@pxref{Defining Symbols}). An additional
|
|
constraint is that the first argument of @code{AC_DEFINE} must be a
|
|
literal. Note that all symbols defined by Autoconf's builtin tests are
|
|
already documented properly; you only need to document 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
|
|
@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
|
|
@emph{check} that @file{config.h} makes sense. The fact that there is a
|
|
well-defined list of symbols that should be @code{#define}'d (or not) is
|
|
also important for people who are porting packages to environments where
|
|
@command{configure} cannot be run: they just have to @emph{fill in the
|
|
blanks}.
|
|
|
|
But let's come back to the point: @command{autoheader}'s invocation@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
|
|
@file{configure.ac} and writes the header file to the standard output.
|
|
|
|
@command{autoheader} accepts the following options:
|
|
|
|
@table @option
|
|
@item --help
|
|
@itemx -h
|
|
Print a summary of the command line options and exit.
|
|
|
|
@item --version
|
|
@itemx -V
|
|
Print the version number of Autoconf and exit.
|
|
|
|
@item --verbose
|
|
@itemx -v
|
|
Report processing steps.
|
|
|
|
@item --debug
|
|
@itemx -d
|
|
Don't remove the temporary files.
|
|
|
|
@item --force
|
|
@itemx -f
|
|
Remake the template file even if newer than its input files.
|
|
|
|
@item --include=@var{dir}
|
|
@itemx -I @var{dir}
|
|
Append @var{dir} to include path. Multiple invocations accumulate.
|
|
|
|
@item --prepend-include=@var{dir}
|
|
@item -B @var{dir}
|
|
Prepend @var{dir} to include path. Multiple invocations accumulate.
|
|
|
|
@item --warnings=@var{category}
|
|
@itemx -W @var{category}
|
|
@evindex WARNINGS
|
|
Report the warnings related to @var{category} (which can actually be a
|
|
comma separated list). Current categories include:
|
|
|
|
@table @samp
|
|
@item obsolete
|
|
report the uses of obsolete constructs
|
|
|
|
@item all
|
|
report all the warnings
|
|
|
|
@item none
|
|
report none
|
|
|
|
@item error
|
|
treats warnings as errors
|
|
|
|
@item no-@var{category}
|
|
disable warnings falling into @var{category}
|
|
@end table
|
|
|
|
@end table
|
|
|
|
|
|
|
|
@node Autoheader Macros
|
|
@subsection Autoheader Macros
|
|
|
|
@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},
|
|
@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 simplest way to create a template for a @var{symbol} is to supply
|
|
the @var{description} argument to an @samp{AC_DEFINE(@var{symbol})}; see
|
|
@ref{Defining Symbols}. You may also use one of the following macros.
|
|
|
|
@defmac AH_VERBATIM (@var{key}, @var{template})
|
|
@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 @code{AC_DEFINE}'d.
|
|
|
|
For example:
|
|
|
|
@example
|
|
AH_VERBATIM([_GNU_SOURCE],
|
|
[/* Enable GNU extensions on systems that have them. */
|
|
#ifndef _GNU_SOURCE
|
|
# define _GNU_SOURCE
|
|
#endif])
|
|
@end example
|
|
@end defmac
|
|
|
|
|
|
@defmac AH_TEMPLATE (@var{key}, @var{description})
|
|
@ahindex{TEMPLATE}
|
|
Tell @command{autoheader} to generate a template for @var{key}. This macro
|
|
generates standard templates just like @code{AC_DEFINE} when a
|
|
@var{description} is given.
|
|
|
|
For example:
|
|
|
|
@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.])
|
|
@end example
|
|
|
|
@noindent
|
|
will generate the following template, with the description properly
|
|
justified.
|
|
|
|
@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
|
|
@end example
|
|
@end defmac
|
|
|
|
|
|
@defmac AH_TOP (@var{text})
|
|
@ahindex{TOP}
|
|
Include @var{text} at the top of the header template file.
|
|
@end defmac
|
|
|
|
|
|
@defmac AH_BOTTOM (@var{text})
|
|
@ahindex{BOTTOM}
|
|
Include @var{text} at the bottom of the header template file.
|
|
@end defmac
|
|
|
|
|
|
@node Configuration Commands
|
|
@section Running Arbitrary Configuration Commands
|
|
|
|
You can execute arbitrary commands before, during, and after
|
|
@file{config.status} is run. The three following macros accumulate the
|
|
commands to run when they are called multiple times.
|
|
@code{AC_CONFIG_COMMANDS} replaces the obsolete macro
|
|
@code{AC_OUTPUT_COMMANDS}; see @ref{Obsolete Macros}, for details.
|
|
|
|
@defmac AC_CONFIG_COMMANDS (@var{tag}@dots{}, @ovar{cmds}, @ovar{init-cmds})
|
|
@acindex{CONFIG_COMMANDS}
|
|
Specify additional shell commands to run at the end of
|
|
@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
|
|
@var{tag} is created. This macro is one of the instantiating macros;
|
|
see @ref{Configuration Actions}.
|
|
|
|
Here is an unrealistic example:
|
|
@example
|
|
fubar=42
|
|
AC_CONFIG_COMMANDS([fubar],
|
|
[echo this is extra $fubar, and so on.],
|
|
[fubar=$fubar])
|
|
@end example
|
|
|
|
Here is a better one:
|
|
@example
|
|
AC_CONFIG_COMMANDS([time-stamp], [date >time-stamp])
|
|
@end example
|
|
@end defmac
|
|
|
|
@defmac AC_CONFIG_COMMANDS_PRE (@var{cmds})
|
|
@acindex{OUTPUT_COMMANDS_PRE}
|
|
Execute the @var{cmds} right before creating @file{config.status}.
|
|
@end defmac
|
|
|
|
@defmac AC_CONFIG_COMMANDS_POST (@var{cmds})
|
|
@acindex{OUTPUT_COMMANDS_POST}
|
|
Execute the @var{cmds} right after creating @file{config.status}.
|
|
@end defmac
|
|
|
|
|
|
|
|
|
|
@node Configuration Links
|
|
@section Creating Configuration Links
|
|
|
|
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.
|
|
|
|
@defmac AC_CONFIG_LINKS (@var{dest}:@var{source}@dots{}, @ovar{cmds}, @ovar{init-cmds})
|
|
@acindex{CONFIG_LINKS}
|
|
@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
|
|
@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:
|
|
|
|
@example
|
|
AC_CONFIG_LINKS(host.h:config/$machine.h
|
|
object.h:config/$obj_format.h)
|
|
@end example
|
|
|
|
@noindent
|
|
creates in the current directory @file{host.h} as a link to
|
|
@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:
|
|
@example
|
|
./config.status host.h object.h
|
|
@end example
|
|
@noindent
|
|
to create the links.
|
|
@end defmac
|
|
|
|
|
|
|
|
@node Subdirectories
|
|
@section Configuring Other Packages in Subdirectories
|
|
|
|
In most situations, calling @code{AC_OUTPUT} is sufficient to produce
|
|
@file{Makefile}s in subdirectories. However, @command{configure} scripts
|
|
that control more than one independent package can use
|
|
@code{AC_CONFIG_SUBDIRS} to run @command{configure} scripts for other
|
|
packages in subdirectories.
|
|
|
|
@defmac AC_CONFIG_SUBDIRS (@var{dir} @dots{})
|
|
@acindex{CONFIG_SUBDIRS}
|
|
@ovindex subdirs
|
|
Make @code{AC_OUTPUT} run @command{configure} in each subdirectory
|
|
@var{dir} in the given whitespace-separated list. Each @var{dir} should
|
|
be a literal, i.e., please do not use:
|
|
|
|
@example
|
|
if test "$package_foo_enabled" = yes; then
|
|
$my_subdirs="$my_subdirs foo"
|
|
fi
|
|
AC_CONFIG_SUBDIRS($my_subdirs)
|
|
@end example
|
|
|
|
@noindent
|
|
because this prevents @samp{./configure --help=recursive} from
|
|
displaying the options of the package @code{foo}. Rather, you should
|
|
write:
|
|
|
|
@example
|
|
if test "$package_foo_enabled" = yes; then
|
|
AC_CONFIG_SUBDIRS(foo)
|
|
fi
|
|
@end example
|
|
|
|
If a given @var{dir} is not found, an error is reported: if the
|
|
subdirectory is optional, write:
|
|
|
|
@example
|
|
if test -d $srcdir/foo; then
|
|
AC_CONFIG_SUBDIRS(foo)
|
|
fi
|
|
@end example
|
|
|
|
@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 filesystems. Likewise, if a @var{dir} contains
|
|
@file{configure.in} but no @command{configure}, the Cygnus
|
|
@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:
|
|
|
|
@itemize @minus
|
|
@item
|
|
adjusting a relative path for the cache file;
|
|
|
|
@item
|
|
adjusting a relative path for the source directory;
|
|
|
|
@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
|
|
@file{configure} differ.
|
|
@end itemize
|
|
|
|
This macro also sets the output variable @code{subdirs} to the list of
|
|
directories @samp{@var{dir} @dots{}}. @file{Makefile} rules can use
|
|
this variable to determine which subdirectories to recurse into.
|
|
|
|
This macro may be called multiple times.
|
|
@end defmac
|
|
|
|
@node Default Prefix
|
|
@section Default Prefix
|
|
|
|
By default, @command{configure} sets the prefix for files it installs to
|
|
@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
|
|
@command{configure}, and when running it.
|
|
|
|
Some software packages might want to install in a directory other than
|
|
@file{/usr/local} by default. To accomplish that, use the
|
|
@code{AC_PREFIX_DEFAULT} macro.
|
|
|
|
@defmac AC_PREFIX_DEFAULT (@var{prefix})
|
|
@acindex{PREFIX_DEFAULT}
|
|
Set the default installation prefix to @var{prefix} instead of
|
|
@file{/usr/local}.
|
|
@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
|
|
@code{AC_PREFIX_PROGRAM}.
|
|
|
|
@defmac AC_PREFIX_PROGRAM (@var{program})
|
|
@acindex{PREFIX_PROGRAM}
|
|
If the user did not specify an installation prefix (using the
|
|
@option{--prefix} option), guess a value for it by looking for
|
|
@var{program} in @code{PATH}, the way the shell does. If @var{program}
|
|
is found, set the prefix to the parent of the directory containing
|
|
@var{program}, else default the prefix as described above
|
|
(@file{/usr/local} or @code{AC_PREFIX_DEFAULT}). For example, if
|
|
@var{program} is @code{gcc} and the @code{PATH} contains
|
|
@file{/usr/local/gnu/bin/gcc}, set the prefix to @file{/usr/local/gnu}.
|
|
@end defmac
|
|
|
|
|
|
|
|
@c ======================================================== Existing tests
|
|
|
|
@node Existing Tests
|
|
@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
|
|
@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
|
|
@var{name}'' is used below as a shorthand to mean ``define C
|
|
preprocessor symbol @var{name} to the value 1''. @xref{Defining
|
|
Symbols}, for how to get those symbol definitions into your program.
|
|
|
|
@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
|
|
* UNIX Variants:: Special kludges for specific UNIX variants
|
|
@end menu
|
|
|
|
@node Common Behavior
|
|
@section Common 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.
|
|
|
|
@menu
|
|
* Standard Symbols:: Symbols defined by the macros
|
|
* Default Includes:: Includes used by the generic macros
|
|
@end menu
|
|
|
|
@node Standard Symbols
|
|
@subsection Standard Symbols
|
|
|
|
All the generic macros that @code{AC_DEFINE} a symbol as a result of
|
|
their test transform their @var{argument}s 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,
|
|
|
|
@example
|
|
AC_CHECK_TYPES(struct $Expensive*)
|
|
@end example
|
|
|
|
@noindent
|
|
will define the symbol @samp{HAVE_STRUCT__EXPENSIVEP} if the check
|
|
succeeds.
|
|
|
|
|
|
@node Default Includes
|
|
@subsection Default Includes
|
|
@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:
|
|
|
|
@example
|
|
@group
|
|
#if TIME_WITH_SYS_TIME
|
|
# include <sys/time.h>
|
|
# include <time.h>
|
|
#else
|
|
# if HAVE_SYS_TIME_H
|
|
# include <sys/time.h>
|
|
# else
|
|
# include <time.h>
|
|
# endif
|
|
#endif
|
|
@end group
|
|
@end example
|
|
|
|
@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:
|
|
|
|
@defmac AC_INCLUDES_DEFAULT (@ovar{include-directives})
|
|
@acindex{INCLUDES_DEFAULT}
|
|
Expand to @var{include-directives} if defined, otherwise to:
|
|
|
|
@example
|
|
@group
|
|
#include <stdio.h>
|
|
#if HAVE_SYS_TYPES_H
|
|
# include <sys/types.h>
|
|
#endif
|
|
#if HAVE_SYS_STAT_H
|
|
# include <sys/stat.h>
|
|
#endif
|
|
#if STDC_HEADERS
|
|
# include <stdlib.h>
|
|
# include <stddef.h>
|
|
#else
|
|
# if HAVE_STDLIB_H
|
|
# include <stdlib.h>
|
|
# endif
|
|
#endif
|
|
#if HAVE_STRING_H
|
|
# if !STDC_HEADERS && HAVE_MEMORY_H
|
|
# include <memory.h>
|
|
# endif
|
|
# include <string.h>
|
|
#endif
|
|
#if HAVE_STRINGS_H
|
|
# include <strings.h>
|
|
#endif
|
|
#if HAVE_INTTYPES_H
|
|
# include <inttypes.h>
|
|
#else
|
|
# if HAVE_STDINT_H
|
|
# include <stdint.h>
|
|
# endif
|
|
#endif
|
|
#if HAVE_UNISTD_H
|
|
# include <unistd.h>
|
|
#endif
|
|
@end group
|
|
@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
|
|
@code{AC_HEADERS_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} will be defined, but
|
|
@code{HAVE_STRINGS_H} won't.
|
|
@end defmac
|
|
|
|
@node Alternative Programs
|
|
@section Alternative Programs
|
|
@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.
|
|
|
|
@menu
|
|
* Particular Programs:: Special handling to find certain programs
|
|
* Generic Programs:: How to find other programs
|
|
@end menu
|
|
|
|
@node Particular Programs
|
|
@subsection Particular Program Checks
|
|
|
|
These macros check for particular programs---whether they exist, and
|
|
in some cases whether they support certain features.
|
|
|
|
@defmac AC_PROG_AWK
|
|
@acindex{PROG_AWK}
|
|
@ovindex 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.
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_EGREP
|
|
@acindex{PROG_EGREP}
|
|
@ovindex EGREP
|
|
Check for @code{grep -E} and @code{egrep}, in that order, and set
|
|
output variable @code{EGREP} to the first one that is found.
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_FGREP
|
|
@acindex{PROG_FGREP}
|
|
@ovindex FGREP
|
|
Check for @code{grep -F} and @code{fgrep}, in that order, and set
|
|
output variable @code{FGREP} to the first one that is found.
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_INSTALL
|
|
@acindex{PROG_INSTALL}
|
|
@ovindex INSTALL
|
|
@ovindex INSTALL_PROGRAM
|
|
@ovindex INSTALL_DATA
|
|
@ovindex INSTALL_SCRIPT
|
|
Set output variable @code{INSTALL} to the path of a @acronym{BSD}-compatible
|
|
@code{install} program, if one is found in the current @code{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
|
|
@samp{$@{INSTALL@}} and @code{INSTALL_DATA} to @samp{$@{INSTALL@} -m 644}.
|
|
|
|
This macro screens out various instances of @code{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 @file{Makefile}.
|
|
|
|
Autoconf comes with a copy of @file{install-sh} that you can use. If
|
|
you use @code{AC_PROG_INSTALL}, you must include either
|
|
@file{install-sh} or @file{install.sh} in your distribution, or
|
|
@command{configure} will produce an error message saying it can't find
|
|
them---even if the system you're on has a good @code{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 @acronym{BSD}-compatible @code{install} program.
|
|
|
|
If you need to use your own installation program because it has features
|
|
not found in standard @code{install} programs, there is no reason to use
|
|
@code{AC_PROG_INSTALL}; just put the file name of your program into your
|
|
@file{Makefile.in} files.
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_LEX
|
|
@acindex{PROG_LEX}
|
|
@ovindex LEX
|
|
@ovindex LEXLIB
|
|
@cvindex YYTEXT_POINTER
|
|
@ovindex LEX_OUTPUT_ROOT
|
|
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
|
|
@option{-ll}.
|
|
|
|
Define @code{YYTEXT_POINTER} if @code{yytext} is a @samp{char *} instead
|
|
of a @samp{char []}. Also set output variable @code{LEX_OUTPUT_ROOT} to
|
|
the base of the file name that the lexer generates; usually
|
|
@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:
|
|
|
|
@example
|
|
AC_PROG_LEX
|
|
if test "$LEX" != flex; then
|
|
LEX="$SHELL $missing_dir/missing flex"
|
|
AC_SUBST(LEX_OUTPUT_ROOT, lex.yy)
|
|
AC_SUBST(LEXLIB, '')
|
|
fi
|
|
@end example
|
|
|
|
The shell script @command{missing} can be found in the Automake
|
|
distribution.
|
|
|
|
To ensure backward compatibility, Automake's @code{AM_PROG_LEX} invokes
|
|
(indirectly) this macro twice, which will cause 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}.
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_LN_S
|
|
@acindex{PROG_LN_S}
|
|
@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
|
|
@code{LN_S} to @samp{ln -s}; otherwise, if @samp{ln} works, set
|
|
@code{LN_S} to @samp{ln}, and otherwise set it to @samp{cp -p}.
|
|
|
|
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:
|
|
@example
|
|
$(LN_S) foo /x/bar
|
|
@end example
|
|
|
|
Instead, do:
|
|
|
|
@example
|
|
(cd /x && $(LN_S) foo bar)
|
|
@end example
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_RANLIB
|
|
@acindex{PROG_RANLIB}
|
|
@ovindex RANLIB
|
|
Set output variable @code{RANLIB} to @samp{ranlib} if @code{ranlib}
|
|
is found, and otherwise to @samp{:} (do nothing).
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_YACC
|
|
@acindex{PROG_YACC}
|
|
@ovindex 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
|
|
@samp{byacc}. Otherwise set @code{YACC} to @samp{yacc}.
|
|
@end defmac
|
|
|
|
@node Generic Programs
|
|
@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 @code{PATH}. If you need to check for a program that might not
|
|
be in the user's @code{PATH}, you can pass a modified path to use
|
|
instead, like this:
|
|
|
|
@example
|
|
AC_PATH_PROG([INETD], [inetd], [/usr/libexec/inetd],
|
|
[$PATH:/usr/libexec:/usr/sbin:/usr/etc:etc])
|
|
@end example
|
|
|
|
You are strongly encouraged to declare the @var{variable} passed to
|
|
@code{AC_CHECK_PROG} etc.@: as precious, @xref{Setting Output Variables},
|
|
@code{AC_ARG_VAR}, for more details.
|
|
|
|
@defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @var{value-if-found}, @ovar{value-if-not-found}, @ovar{path}, @ovar{reject})
|
|
@acindex{CHECK_PROG}
|
|
Check whether program @var{prog-to-check-for} exists in @code{PATH}. If
|
|
it is found, set @var{variable} to @var{value-if-found}, otherwise to
|
|
@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
|
|
@var{prog-to-check-for} found that is not @var{reject}. If
|
|
@var{variable} was already set, do nothing. Calls @code{AC_SUBST} for
|
|
@var{variable}.
|
|
@end defmac
|
|
|
|
@defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
|
|
@acindex{CHECK_PROGS}
|
|
Check for each program in the whitespace-separated list
|
|
@var{progs-to-check-for} existing in the @code{PATH}. If one is found, set
|
|
@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
|
|
@var{value-if-not-found} is not specified, the value of @var{variable}
|
|
is not changed. Calls @code{AC_SUBST} for @var{variable}.
|
|
@end defmac
|
|
|
|
@defmac AC_CHECK_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
|
|
@acindex{CHECK_TOOL}
|
|
Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
|
|
with a prefix of the host type as determined by
|
|
@code{AC_CANONICAL_HOST}, followed by a dash (@pxref{Canonicalizing}).
|
|
For example, if the user runs @samp{configure --host=i386-gnu}, then
|
|
this call:
|
|
@example
|
|
AC_CHECK_TOOL(RANLIB, ranlib, :)
|
|
@end example
|
|
@noindent
|
|
sets @code{RANLIB} to @file{i386-gnu-ranlib} if that program exists in
|
|
@code{PATH}, or otherwise to @samp{ranlib} if that program exists in
|
|
@code{PATH}, or to @samp{:} if neither program exists.
|
|
@end defmac
|
|
|
|
@defmac AC_CHECK_TOOLS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
|
|
@acindex{CHECK_TOOLS}
|
|
Like @code{AC_CHECK_TOOL}, each of the tools in the list
|
|
@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
|
|
@var{value-if-not-found} is not specified, the value of @var{variable}
|
|
is not changed. Calls @code{AC_SUBST} for @var{variable}.
|
|
@end defmac
|
|
|
|
@defmac AC_PATH_PROG (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
|
|
@acindex{PATH_PROG}
|
|
Like @code{AC_CHECK_PROG}, but set @var{variable} to the entire
|
|
path of @var{prog-to-check-for} if found.
|
|
@end defmac
|
|
|
|
@defmac AC_PATH_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
|
|
@acindex{PATH_PROGS}
|
|
Like @code{AC_CHECK_PROGS}, but if any of @var{progs-to-check-for}
|
|
are found, set @var{variable} to the entire path of the program
|
|
found.
|
|
@end defmac
|
|
|
|
@defmac AC_PATH_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
|
|
@acindex{PATH_TOOL}
|
|
Like @code{AC_CHECK_TOOL}, but set @var{variable} to the entire
|
|
path of the program if it is found.
|
|
@end defmac
|
|
|
|
|
|
@node Files
|
|
@section Files
|
|
@cindex File, checking
|
|
|
|
You might also need to check for the existence of files. Before using
|
|
these macros, ask yourself whether a run-time 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.
|
|
|
|
@defmac AC_CHECK_FILE (@var{file}, @ovar{action-if-found}, @ovar{action-if-not-found})
|
|
@acindex{CHECK_FILE}
|
|
Check whether file @var{file} exists on the native system. If it is
|
|
found, execute @var{action-if-found}, otherwise do
|
|
@var{action-if-not-found}, if given.
|
|
@end defmac
|
|
|
|
@defmac AC_CHECK_FILES (@var{files}, @ovar{action-if-found}, @ovar{action-if-not-found})
|
|
@acindex{CHECK_FILES}
|
|
Executes @code{AC_CHECK_FILE} once for each file listed in @var{files}.
|
|
Additionally, defines @samp{HAVE_@var{file}} (@pxref{Standard Symbols})
|
|
for each file found.
|
|
@end defmac
|
|
|
|
|
|
@node Libraries
|
|
@section Library Files
|
|
@cindex Library, checking
|
|
|
|
The following macros check for the presence of certain C, C++, or Fortran
|
|
library archive files.
|
|
|
|
@defmac AC_CHECK_LIB (@var{library}, @var{function}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
|
|
@acindex{CHECK_LIB}
|
|
Depending on the current language(@pxref{Language Choice}), try to
|
|
ensure that the C, C++, or Fortran function @var{function} is
|
|
available by checking whether a test program can be linked with the
|
|
library @var{library} to get the function. @var{library} is the base
|
|
name of the library; e.g., to check for @option{-lmp}, use @samp{mp} as
|
|
the @var{library} argument.
|
|
|
|
@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 will prepend @option{-l@var{library}} to
|
|
@code{LIBS} and define @samp{HAVE_LIB@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. Some linkers are very 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 will fail to detect
|
|
that @var{library} is present, because linking the test program will
|
|
always 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}.
|
|
@end defmac
|
|
|
|
|
|
@defmac AC_SEARCH_LIBS (@var{function}, @var{search-libs}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
|
|
@acindex{SEARCH_LIBS}
|
|
Search for a library defining @var{function} if it's not already
|
|
available. This equates to calling
|
|
@samp{AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])])} first with
|
|
no libraries, then for each library listed in @var{search-libs}.
|
|
|
|
Add @option{-l@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 will fail to detect
|
|
that @var{function} is present, because linking the test program will
|
|
always fail with unresolved symbols.
|
|
@end defmac
|
|
|
|
|
|
|
|
@node Library Functions
|
|
@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.
|
|
|
|
@menu
|
|
* Function Portability:: Pitfalls with usual functions
|
|
* Particular Functions:: Special handling to find certain functions
|
|
* Generic Functions:: How to find other functions
|
|
@end menu
|
|
|
|
@node Function Portability
|
|
@subsection Portability of C Functions
|
|
|
|
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 will always require
|
|
additions. Please help us keeping it as complete as possible.
|
|
|
|
@table @asis
|
|
@item @code{exit}
|
|
@c @fuindex exit
|
|
@prindex @code{exit}
|
|
Did you know that, on some older hosts, @code{exit} returns @code{int}?
|
|
This is because @code{exit} predates @code{void}, and there was a long
|
|
tradition of it returning @code{int}.
|
|
|
|
@item @code{putenv}
|
|
@c @fuindex putenv
|
|
@prindex @code{putenv}
|
|
POSIX specifies that @code{putenv} puts the given string directly in
|
|
@code{environ}, but some systems make a copy of it instead (eg.@:
|
|
glibc 2.0, or BSD). And when a copy is made, @code{unsetenv} might
|
|
not free it, causing a memory leak (eg.@: FreeBSD 4).
|
|
|
|
POSIX specifies that @code{putenv("FOO")} removes @samp{FOO} from the
|
|
environment, but on some systems (eg.@: FreeBSD 4) this is not the
|
|
case and instead @code{unsetenv} must be used.
|
|
|
|
On MINGW, a call @code{putenv("FOO=")} removes @samp{FOO} from the
|
|
environment, rather than inserting it with an empty value.
|
|
|
|
@item @code{signal} handler
|
|
@c @fuindex signal
|
|
@prindex @code{signal}
|
|
Normally @code{signal} takes a handler function with a return type of
|
|
@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 take @code{void}. Presumably
|
|
@code{int} was to support K&R C, where of course @code{void} is not
|
|
available. @code{AC_TYPE_SIGNAL} (@pxref{Particular Types}) can be
|
|
used to establish the correct type in all cases.
|
|
|
|
@item @code{snprintf}
|
|
@c @fuindex snprintf
|
|
@prindex @code{snprintf}
|
|
@c @fuindex vsnprintf
|
|
@prindex @code{vsnprintf}
|
|
The ISO 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.,
|
|
@acronym{GNU} C Library 2.0.x or @sc{irix} 6.5), some a negative value
|
|
(e.g., earlier @acronym{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).
|
|
|
|
@item @code{sprintf}
|
|
@c @fuindex sprintf
|
|
@prindex @code{sprintf}
|
|
@c @fuindex vsprintf
|
|
@prindex @code{vsprintf}
|
|
The ISO C standard says @code{sprintf} and @code{vsprintf} return the
|
|
number of bytes written, but on some old systems (SunOS 4 for
|
|
instance) they return the buffer pointer instead.
|
|
|
|
@item @code{sscanf}
|
|
@c @fuindex sscanf
|
|
@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 @acronym{GNU} Compiler Collection}). Apparently in some cases even
|
|
having format strings read-only can be a problem.
|
|
|
|
@item @code{strnlen}
|
|
@c @fuindex strnlen
|
|
@prindex @code{strnlen}
|
|
@acronym{AIX} 4.3 provides a broken version which produces the
|
|
following results:
|
|
|
|
@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
|
|
@end example
|
|
|
|
@item @code{sysconf}
|
|
@c @fuindex sysconf
|
|
@prindex @code{sysconf}
|
|
@code{_SC_PAGESIZE} is standard, but some older systems (eg.@: HP-UX
|
|
9) have @code{_SC_PAGE_SIZE} instead. This can be tested with
|
|
@code{#ifdef}.
|
|
|
|
@item @code{unlink}
|
|
@c @fuindex unlink
|
|
@prindex @code{unlink}
|
|
The @acronym{POSIX} spec says that @code{unlink} causes the given file to be
|
|
removed only after there are no more open file handles for it. Not all
|
|
OS's support this behavior though. So even on systems that provide
|
|
@code{unlink}, you cannot portably assume it is OK to call it on files
|
|
that are open. For example, on Windows 9x and ME, such a call would fail;
|
|
on DOS it could even lead to file system corruption, as the file might end
|
|
up being written to after the OS has removed it.
|
|
|
|
@item @code{unsetenv}
|
|
@c @fuindex unsetenv
|
|
@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
|
|
@code{putenv} above.
|
|
|
|
@item @code{va_copy}
|
|
@c @fuindex va_copy
|
|
@prindex @code{va_copy}
|
|
The ISO C99 standard provides @code{va_copy} for copying
|
|
@code{va_list} variables. It may be available in older environments
|
|
too, though possibly as @code{__va_copy} (e.g., @command{gcc} in strict
|
|
C89 mode). These can be tested with @code{#ifdef}. A fallback to
|
|
@code{memcpy (&dst, &src, sizeof(va_list))} will give maximum
|
|
portability.
|
|
|
|
@item @code{va_list}
|
|
@c @fuindex va_list
|
|
@prindex @code{va_list}
|
|
@code{va_list} is not necessarily just a pointer. It can be a
|
|
@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 @acronym{GNU} C Library
|
|
2.1).
|
|
|
|
@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 the ISO C standard 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.
|
|
@end table
|
|
|
|
|
|
@node Particular Functions
|
|
@subsection Particular Function Checks
|
|
@cindex Function, checking
|
|
|
|
These macros check for particular C functions---whether they exist, and
|
|
in some cases how they respond when given certain arguments.
|
|
|
|
@defmac AC_FUNC_ALLOCA
|
|
@acindex{FUNC_ALLOCA}
|
|
@cvindex C_ALLOCA
|
|
@cvindex HAVE_ALLOCA_H
|
|
@ovindex ALLOCA
|
|
@c @fuindex alloca
|
|
@prindex @code{alloca}
|
|
@hdrindex 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
|
|
@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
|
|
@code{HAVE_ALLOCA}. Otherwise, it sets the output variable
|
|
@code{ALLOCA} to @samp{alloca.o} and defines @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 @code{LIBOBJS}.
|
|
|
|
This macro does not try to get @code{alloca} from the System V R3
|
|
@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
|
|
@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. In some versions of @acronym{AIX},
|
|
the declaration of @code{alloca} must precede everything else except for
|
|
comments and preprocessor directives. The @code{#pragma} directive is
|
|
indented so that pre-@acronym{ANSI} C compilers will ignore it, rather than
|
|
choke on it.
|
|
|
|
@example
|
|
@group
|
|
/* AIX requires this to be the first thing in the file. */
|
|
#ifndef __GNUC__
|
|
# if HAVE_ALLOCA_H
|
|
# include <alloca.h>
|
|
# else
|
|
# ifdef _AIX
|
|
#pragma alloca
|
|
# else
|
|
# ifndef alloca /* predefined by HP cc +Olibcalls */
|
|
char *alloca ();
|
|
# endif
|
|
# endif
|
|
# endif
|
|
#endif
|
|
@end group
|
|
@end example
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_CHOWN
|
|
@acindex{FUNC_CHOWN}
|
|
@c @fuindex chown
|
|
@prindex @code{chown}
|
|
If the @code{chown} function is available and works (in particular, it
|
|
should accept @option{-1} for @code{uid} and @code{gid}), define
|
|
@code{HAVE_CHOWN}.
|
|
@end defmac
|
|
|
|
|
|
@defmac AC_FUNC_CLOSEDIR_VOID
|
|
@acindex{FUNC_CLOSEDIR_VOID}
|
|
@cvindex CLOSEDIR_VOID
|
|
@c @fuindex closedir
|
|
@prindex @code{closedir}
|
|
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.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_ERROR_AT_LINE
|
|
@acindex{FUNC_ERROR_AT_LINE}
|
|
@c @fuindex error_at_line
|
|
@prindex @code{error_at_line}
|
|
If the @code{error_at_line} function is not found, require an
|
|
@code{AC_LIBOBJ} replacement of @samp{error}.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_FNMATCH
|
|
@acindex{FUNC_FNMATCH}
|
|
@c @fuindex fnmatch
|
|
@prindex @code{fnmatch}
|
|
If the @code{fnmatch} function conforms to @acronym{POSIX}, define
|
|
@code{HAVE_FNMATCH}. Detect common implementation bugs, for example,
|
|
the bugs in Solaris 2.4.
|
|
|
|
Note that for historical reasons, contrary to the other specific
|
|
@code{AC_FUNC} macros, @code{AC_FUNC_FNMATCH} does not replace a
|
|
broken/missing @code{fnmatch}. See @code{AC_REPLACE_FNMATCH} below.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_FNMATCH_GNU
|
|
@acindex{FUNC_FNMATCH_GNU}
|
|
@c @fuindex fnmatch
|
|
@prindex @code{fnmatch}
|
|
Behave like @code{AC_REPLACE_FNMATCH} (@emph{replace}) but also test
|
|
whether @code{fnmatch} supports @acronym{GNU} extensions. Detect common
|
|
implementation bugs, for example, the bugs in the @acronym{GNU} C
|
|
Library 2.1.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_FORK
|
|
@acindex{FUNC_FORK}
|
|
@cvindex HAVE_VFORK_H
|
|
@cvindex HAVE_WORKING_FORK
|
|
@cvindex HAVE_WORKING_VFORK
|
|
@cvindex vfork
|
|
@c @fuindex fork
|
|
@prindex @code{fork}
|
|
@c @fuindex vfork
|
|
@prindex @code{vfork}
|
|
@hdrindex vfork.h
|
|
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
|
|
@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:
|
|
@example
|
|
@group
|
|
#if !HAVE_WORKING_VFORK
|
|
# define vfork fork
|
|
#endif
|
|
@end group
|
|
@end example
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_FSEEKO
|
|
@acindex{FUNC_FSEEKO}
|
|
@cvindex _LARGEFILE_SOURCE
|
|
@c @fuindex fseeko
|
|
@prindex @code{fseeko}
|
|
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.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_GETGROUPS
|
|
@acindex{FUNC_GETGROUPS}
|
|
@ovindex GETGROUPS_LIBS
|
|
@c @fuindex getgroups
|
|
@prindex @code{getgroups}
|
|
If the @code{getgroups} function is available and works (unlike on
|
|
Ultrix 4.3, where @samp{getgroups (0, 0)} always fails), define
|
|
@code{HAVE_GETGROUPS}. Set @code{GETGROUPS_LIBS} to any libraries
|
|
needed to get that function. This macro runs @code{AC_TYPE_GETGROUPS}.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_GETLOADAVG
|
|
@acindex{FUNC_GETLOADAVG}
|
|
@cvindex SVR4
|
|
@cvindex DGUX
|
|
@cvindex UMAX
|
|
@cvindex UMAX4_3
|
|
@cvindex HAVE_NLIST_H
|
|
@cvindex NLIST_NAME_UNION
|
|
@cvindex GETLODAVG_PRIVILEGED
|
|
@cvindex NEED_SETGID
|
|
@cvindex C_GETLOADAVG
|
|
@ovindex LIBOBJS
|
|
@ovindex NEED_SETGID
|
|
@ovindex KMEM_GROUP
|
|
@ovindex GETLOADAVG_LIBS
|
|
@c @fuindex getloadavg
|
|
@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
|
|
@ref{Generic Functions}, @code{AC_CONFIG_LIBOBJ_DIR}).
|
|
|
|
If the system has the @code{getloadavg} function, define
|
|
@code{HAVE_GETLOADAVG}, and set @code{GETLOADAVG_LIBS} to any libraries
|
|
needed to get that function. Also add @code{GETLOADAVG_LIBS} to
|
|
@code{LIBS}. Otherwise, require an @code{AC_LIBOBJ} replacement for
|
|
@samp{getloadavg} with source code in @file{@var{dir}/getloadavg.c}, and
|
|
possibly define several other C preprocessor macros and output
|
|
variables:
|
|
|
|
@enumerate
|
|
@item
|
|
Define @code{C_GETLOADAVG}.
|
|
|
|
@item
|
|
Define @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if on
|
|
those systems.
|
|
|
|
@item
|
|
@hdrindex nlist.h
|
|
If @file{nlist.h} is found, define @code{HAVE_NLIST_H}.
|
|
|
|
@item
|
|
If @samp{struct nlist} has an @samp{n_un.n_name} member, define
|
|
@code{HAVE_STRUCT_NLIST_N_UN_N_NAME}. The obsolete symbol
|
|
@code{NLIST_NAME_UNION} is still defined, but do not depend upon it.
|
|
|
|
@item
|
|
Programs may need to be installed setgid (or setuid) for
|
|
@code{getloadavg} to work. In this case, define
|
|
@code{GETLOADAVG_PRIVILEGED}, set the output variable @code{NEED_SETGID}
|
|
to @samp{true} (and otherwise to @samp{false}), and set
|
|
@code{KMEM_GROUP} to the name of the group that should own the installed
|
|
program.
|
|
@end enumerate
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_GETMNTENT
|
|
@acindex{FUNC_GETMNTENT}
|
|
@cvindex HAVE_GETMNTENT
|
|
@c @fuindex getmntent
|
|
@prindex @code{getmntent}
|
|
Check for @code{getmntent} in the @file{sun}, @file{seq}, and @file{gen}
|
|
libraries, for @sc{irix} 4, PTX, and Unixware, respectively. Then, if
|
|
@code{getmntent} is available, define @code{HAVE_GETMNTENT}.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_GETPGRP
|
|
@acindex{FUNC_GETPGRP}
|
|
@cvindex GETPGRP_VOID
|
|
@c @fuindex getpgid
|
|
@c @fuindex getpgrp
|
|
@prindex @code{getpgid}
|
|
@prindex @code{getpgrp}
|
|
Define @code{GETPGRP_VOID} if it is an error to pass 0 to
|
|
@code{getpgrp}; this is the @acronym{POSIX} behavior. On older BSD
|
|
systems, you must pass 0 to @code{getpgrp}, as it takes an argument and
|
|
behaves like @acronym{POSIX}'s @code{getpgid}.
|
|
|
|
@example
|
|
#if GETPGRP_VOID
|
|
pid = getpgrp ();
|
|
#else
|
|
pid = getpgrp (0);
|
|
#endif
|
|
@end example
|
|
|
|
This macro does not check whether
|
|
@code{getpgrp} exists at all; if you need to work in that situation,
|
|
first call @code{AC_CHECK_FUNC} for @code{getpgrp}.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK
|
|
@acindex{FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK}
|
|
@cvindex LSTAT_FOLLOWS_SLASHED_SYMLINK
|
|
@c @fuindex lstat
|
|
@prindex @code{lstat}
|
|
If @file{link} is a symbolic link, then @code{lstat} should treat
|
|
@file{link/} the same as @file{link/.}. However, many older
|
|
@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
|
|
@code{unlink} also incorrectly ignore trailing slashes.
|
|
|
|
If @code{lstat} behaves properly, define
|
|
@code{LSTAT_FOLLOWS_SLASHED_SYMLINK}, otherwise require an
|
|
@code{AC_LIBOBJ} replacement of @code{lstat}.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_MALLOC
|
|
@acindex{FUNC_MALLOC}
|
|
@cvindex HAVE_MALLOC
|
|
@cvindex malloc
|
|
@c @fuindex malloc
|
|
@prindex @code{malloc}
|
|
If the @code{malloc} function is compatible with the @acronym{GNU} C
|
|
library @code{malloc} (i.e., @samp{malloc (0)} returns a valid
|
|
pointer), define @code{HAVE_MALLOC} to 1. Otherwise define
|
|
@code{HAVE_MALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
|
|
@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}):
|
|
|
|
@verbatim
|
|
#if HAVE_CONFIG_H
|
|
# include <config.h>
|
|
#endif
|
|
#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);
|
|
}
|
|
@end verbatim
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_MEMCMP
|
|
@acindex{FUNC_MEMCMP}
|
|
@ovindex LIBOBJS
|
|
@c @fuindex memcmp
|
|
@prindex @code{memcmp}
|
|
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
|
|
@code{AC_LIBOBJ} replacement for @samp{memcmp}.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_MBRTOWC
|
|
@acindex{FUNC_MBRTOWC}
|
|
@cvindex HAVE_MBRTOWC
|
|
@c @fuindex mbrtowc
|
|
@prindex @code{mbrtowc}
|
|
Define @code{HAVE_MBRTOWC} to 1 if the function @code{mbrtowc} and the
|
|
type @code{mbstate_t} are properly declared.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_MKTIME
|
|
@acindex{FUNC_MKTIME}
|
|
@ovindex LIBOBJS
|
|
@c @fuindex mktime
|
|
@prindex @code{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
|
|
@acronym{POSIX} standard and should be the inverse of
|
|
@code{localtime}.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_MMAP
|
|
@acindex{FUNC_MMAP}
|
|
@cvindex HAVE_MMAP
|
|
@c @fuindex mmap
|
|
@prindex @code{mmap}
|
|
If the @code{mmap} function exists and works correctly, define
|
|
@code{HAVE_MMAP}. Only checks private fixed mapping of already-mapped
|
|
memory.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_OBSTACK
|
|
@acindex{FUNC_OBSTACK}
|
|
@cvindex HAVE_OBSTACK
|
|
@cindex obstack
|
|
If the obstacks are found, define @code{HAVE_OBSTACK}, else require an
|
|
@code{AC_LIBOBJ} replacement for @samp{obstack}.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_REALLOC
|
|
@acindex{FUNC_REALLOC}
|
|
@cvindex HAVE_REALLOC
|
|
@cvindex realloc
|
|
@c @fuindex realloc
|
|
@prindex @code{realloc}
|
|
If the @code{realloc} function is compatible with the @acronym{GNU} C
|
|
library @code{realloc} (i.e., @samp{realloc (0, 0)} returns a
|
|
valid pointer), define @code{HAVE_REALLOC} to 1. Otherwise define
|
|
@code{HAVE_REALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
|
|
@samp{realloc}, and define @code{realloc} to @code{rpl_realloc} so that
|
|
the native @code{realloc} is not used in the main project. See
|
|
@code{AC_FUNC_MALLOC} for details.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_SELECT_ARGTYPES
|
|
@acindex{FUNC_SELECT_ARGTYPES}
|
|
@cvindex SELECT_TYPE_ARG1
|
|
@cvindex SELECT_TYPE_ARG234
|
|
@cvindex SELECT_TYPE_ARG5
|
|
@c @fuindex select
|
|
@prindex @code{select}
|
|
Determines the correct type to be passed for each of the
|
|
@code{select} function's arguments, and defines those types
|
|
in @code{SELECT_TYPE_ARG1}, @code{SELECT_TYPE_ARG234}, and
|
|
@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 *}.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_SETPGRP
|
|
@acindex{FUNC_SETPGRP}
|
|
@cvindex SETPGRP_VOID
|
|
@c @fuindex setpgrp
|
|
@prindex @code{setpgrp}
|
|
If @code{setpgrp} takes no argument (the @acronym{POSIX} version), define
|
|
@code{SETPGRP_VOID}. Otherwise, it is the @acronym{BSD} version, which takes
|
|
two process IDs as arguments. This macro does not check whether
|
|
@code{setpgrp} exists at all; if you need to work in that situation,
|
|
first call @code{AC_CHECK_FUNC} for @code{setpgrp}.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_STAT
|
|
@defmacx AC_FUNC_LSTAT
|
|
@acindex{FUNC_STAT}
|
|
@acindex{FUNC_LSTAT}
|
|
@cvindex HAVE_STAT_EMPTY_STRING_BUG
|
|
@cvindex HAVE_LSTAT_EMPTY_STRING_BUG
|
|
@c @fuindex stat
|
|
@prindex @code{stat}
|
|
@c @fuindex lstat
|
|
@prindex @code{lstat}
|
|
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
|
|
@code{HAVE_LSTAT_EMPTY_STRING_BUG}) and ask for an @code{AC_LIBOBJ}
|
|
replacement of it.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_SETVBUF_REVERSED
|
|
@acindex{FUNC_SETVBUF_REVERSED}
|
|
@cvindex SETVBUF_REVERSED
|
|
@c @fuindex setvbuf
|
|
@prindex @code{setvbuf}
|
|
If @code{setvbuf} takes the buffering type as its second argument and
|
|
the buffer pointer as the third, instead of the other way around, define
|
|
@code{SETVBUF_REVERSED}.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_STRCOLL
|
|
@acindex{FUNC_STRCOLL}
|
|
@cvindex HAVE_STRCOLL
|
|
@c @fuindex strcoll
|
|
@prindex @code{strcoll}
|
|
If the @code{strcoll} function exists and works correctly, define
|
|
@code{HAVE_STRCOLL}. This does a bit more than
|
|
@samp{AC_CHECK_FUNCS(strcoll)}, because some systems have incorrect
|
|
definitions of @code{strcoll} that should not be used.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_STRTOD
|
|
@acindex{FUNC_STRTOD}
|
|
@ovindex POW_LIB
|
|
@c @fuindex strtod
|
|
@prindex @code{strtod}
|
|
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.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_STRERROR_R
|
|
@acindex{FUNC_STRERROR_R}
|
|
@cvindex HAVE_STRERROR_R
|
|
@cvindex HAVE_DECL_STRERROR_R
|
|
@cvindex STRERROR_R_CHAR_P
|
|
@c @fuindex strerror_r
|
|
@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
|
|
@code{char *} message, define @code{STRERROR_R_CHAR_P}; otherwise it
|
|
returns an @code{int} error number. The Thread-Safe Functions option of
|
|
@acronym{POSIX} requires @code{strerror_r} to return @code{int}, but
|
|
many systems (including, for example, version 2.2.4 of the @acronym{GNU} C
|
|
Library) return a @code{char *} value that is not necessarily equal to
|
|
the buffer argument.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_STRFTIME
|
|
@acindex{FUNC_STRFTIME}
|
|
@cvindex HAVE_STRFTIME
|
|
@c @fuindex strftime
|
|
@prindex @code{strftime}
|
|
Check for @code{strftime} in the @file{intl} library, for SCO @sc{unix}.
|
|
Then, if @code{strftime} is available, define @code{HAVE_STRFTIME}.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_STRNLEN
|
|
@acindex{FUNC_STRNLEN}
|
|
@cvindex HAVE_STRNLEN
|
|
@c @fuindex strnlen
|
|
@prindex @code{strnlen}
|
|
If the @code{strnlen} function is not available, or is buggy (like the one
|
|
from @acronym{AIX} 4.3), require an @code{AC_LIBOBJ} replacement for it.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_UTIME_NULL
|
|
@acindex{FUNC_UTIME_NULL}
|
|
@cvindex HAVE_UTIME_NULL
|
|
@c @fuindex utime
|
|
@prindex @code{utime}
|
|
If @samp{utime(@var{file}, NULL)} sets @var{file}'s timestamp to
|
|
the present, define @code{HAVE_UTIME_NULL}.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_VPRINTF
|
|
@acindex{FUNC_VPRINTF}
|
|
@cvindex HAVE_VPRINTF
|
|
@cvindex HAVE_DOPRNT
|
|
@c @fuindex vprintf
|
|
@prindex @code{vprintf}
|
|
If @code{vprintf} is found, define @code{HAVE_VPRINTF}. Otherwise, if
|
|
@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.)
|
|
@end defmac
|
|
|
|
@defmac AC_REPLACE_FNMATCH
|
|
@acindex{REPLACE_FNMATCH}
|
|
@c @fuindex fnmatch
|
|
@prindex @code{fnmatch}
|
|
@hdrindex fnmatch.h
|
|
If the @code{fnmatch} function does not conform to @acronym{POSIX} (see
|
|
@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 @acronym{GNU} @code{fnmatch}. If necessary,
|
|
this source code is compiled as an @code{AC_LIBOBJ} replacement, and the
|
|
@file{fnmatch_.h} file is linked to @file{fnmatch.h} so that it can be
|
|
included in place of the system @code{<fnmatch.h>}.
|
|
@end defmac
|
|
|
|
|
|
|
|
@node Generic Functions
|
|
@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}).
|
|
|
|
@defmac AC_CHECK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found})
|
|
@acindex{CHECK_FUNC}
|
|
If C function @var{function} is available, run shell commands
|
|
@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
|
|
@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.)
|
|
@end defmac
|
|
|
|
@defmac AC_CHECK_FUNCS (@var{function}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found})
|
|
@acindex{CHECK_FUNCS}
|
|
@cvindex HAVE_@var{function}
|
|
For each @var{function} in the whitespace-separated argument list,
|
|
define @code{HAVE_@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
|
|
@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
|
|
functions is not found.
|
|
@end defmac
|
|
|
|
@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 @acronym{POSIX}
|
|
environment. Some functions may be missing or unfixable, and your
|
|
package must be ready to replace them.
|
|
|
|
@defmac AC_LIBOBJ (@var{function})
|
|
@acindex{LIBOBJ}
|
|
@ovindex LIBOBJS
|
|
Specify that @samp{@var{function}.c} must be included in the executables
|
|
to replace a missing or broken implementation of @var{function}.
|
|
|
|
Technically, it adds @samp{@var{function}.$ac_objext} to the output
|
|
variable @code{LIBOBJS} if it is not already in, and calls
|
|
@code{AC_LIBSOURCE} for @samp{@var{function}.c}. You should not
|
|
directly change @code{LIBOBJS}, since this is not traceable.
|
|
@end defmac
|
|
|
|
@defmac AC_LIBSOURCE (@var{file})
|
|
@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
|
|
@code{"foo"} or @code{"bar"}, you should do:
|
|
|
|
@example
|
|
AC_LIBSOURCE(foo.c)
|
|
AC_LIBSOURCE(bar.c)
|
|
AC_LIBOBJ($foo_or_bar)
|
|
@end example
|
|
|
|
@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.
|
|
@end defmac
|
|
|
|
@defmac AC_LIBSOURCES (@var{files})
|
|
@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:
|
|
|
|
@example
|
|
AC_LIBSOURCES([foo.c, bar.c])
|
|
AC_LIBOBJ($foo_or_bar)
|
|
@end example
|
|
@end defmac
|
|
|
|
@defmac AC_CONFIG_LIBOBJ_DIR (@var{directory})
|
|
@acindex{CONFIG_LIBOBJ_DIR}
|
|
Specify that @code{AC_LIBOBJ} replacement files are to be found in
|
|
@var{directory}, a relative path starting from 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)}.
|
|
|
|
@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, etc.
|
|
@end defmac
|
|
|
|
@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.
|
|
|
|
@defmac AC_REPLACE_FUNCS (@var{function}@dots{})
|
|
@acindex{REPLACE_FUNCS}
|
|
@ovindex LIBOBJS
|
|
Like @code{AC_CHECK_FUNCS}, but uses @samp{AC_LIBOBJ(@var{function})} as
|
|
@var{action-if-not-found}. You can declare your replacement function by
|
|
enclosing the prototype in @samp{#if !HAVE_@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.
|
|
@end defmac
|
|
|
|
@node Header Files
|
|
@section Header Files
|
|
@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.
|
|
|
|
@menu
|
|
* Header Portability:: Collected knowledge on common headers
|
|
* Particular Headers:: Special handling to find certain headers
|
|
* Generic Headers:: How to find other headers
|
|
@end menu
|
|
|
|
@node Header Portability
|
|
@subsection Portability of Headers
|
|
|
|
This section tries to collect knowledge about common headers, and the
|
|
problems they cause. By definition, this list will always require
|
|
additions. Please help us keeping it as complete as possible.
|
|
|
|
@table @asis
|
|
@item @file{inttypes.h} vs.@: @file{stdint.h}
|
|
@hdrindex inttypes.h
|
|
@hdrindex stdint.h
|
|
Paul Eggert notes that: ISO C 1999 says that @file{inttypes.h} includes
|
|
@file{stdint.h}, so there's no need to include @file{stdint.h}
|
|
separately in a standard environment. Many implementations have
|
|
@file{inttypes.h} but not @file{stdint.h} (e.g., Solaris 7), but I don't
|
|
know of any implementation that has @file{stdint.h} but not
|
|
@file{inttypes.h}. Nor do I know of any free software that includes
|
|
@file{stdint.h}; @file{stdint.h} seems to be a creation of the committee.
|
|
|
|
@item @file{linux/irda.h}
|
|
@hdrindex linux/irda.h
|
|
It requires @file{linux/types.h} and @file{sys/socket.h}.
|
|
|
|
@item @file{linux/random.h}
|
|
@hdrindex linux/random.h
|
|
It requires @file{linux/types.h}.
|
|
|
|
@item @file{net/if.h}
|
|
@hdrindex net/if.h
|
|
On Darwin, this file requires that @file{sys/socket.h} be included
|
|
beforehand. One should run:
|
|
|
|
@example
|
|
AC_CHECK_HEADERS([sys/socket.h])
|
|
AC_CHECK_HEADERS([net/if.h], [], [],
|
|
[#include <stdio.h>
|
|
#if STDC_HEADERS
|
|
# include <stdlib.h>
|
|
# include <stddef.h>
|
|
#else
|
|
# if HAVE_STDLIB_H
|
|
# include <stdlib.h>
|
|
# endif
|
|
#endif
|
|
#if HAVE_SYS_SOCKET_H
|
|
# include <sys/socket.h>
|
|
#endif
|
|
])
|
|
@end example
|
|
|
|
@item @file{netinet/if_ether.h}
|
|
@hdrindex netinet/if_ether.h
|
|
On Darwin, this file requires that @file{stdio.h} and
|
|
@file{sys/socket.h} be included beforehand. One should run:
|
|
|
|
@example
|
|
AC_CHECK_HEADERS([sys/socket.h])
|
|
AC_CHECK_HEADERS([netinet/if_ether.h], [], [],
|
|
[#include <stdio.h>
|
|
#if STDC_HEADERS
|
|
# include <stdlib.h>
|
|
# include <stddef.h>
|
|
#else
|
|
# if HAVE_STDLIB_H
|
|
# include <stdlib.h>
|
|
# endif
|
|
#endif
|
|
#if HAVE_SYS_SOCKET_H
|
|
# include <sys/socket.h>
|
|
#endif
|
|
])
|
|
@end example
|
|
|
|
@item @file{stdint.h}
|
|
See above, item @file{inttypes.h} vs.@: @file{stdint.h}.
|
|
|
|
@item @file{stdlib.h}
|
|
@hdrindex stdlib.h
|
|
On many systems (e.g., Darwin), @file{stdio.h} is a prerequisite.
|
|
|
|
@item @file{sys/mount.h}
|
|
@hdrindex sys/mount.h
|
|
On FreeBSD 4.8 on ia32 and using gcc version 2.95.4,
|
|
@file{sys/params.h} is a prerequisite.
|
|
|
|
@item @file{sys/socket.h}
|
|
@hdrindex sys/socket.h
|
|
On Darwin, @file{stdlib.h} is a prerequisite.
|
|
|
|
@item @file{sys/ucred.h}
|
|
@hdrindex sys/ucred.h
|
|
On HP Tru64 5.1, @file{sys/types.h} is a prerequisite.
|
|
|
|
@item @file{X11/extensions/scrnsaver.h}
|
|
@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.
|
|
|
|
@example
|
|
AC_CHECK_HEADERS([X11/extensions/scrnsaver.h], [], [],
|
|
[[#include <X11/Xlib.h>
|
|
]])
|
|
@end example
|
|
@end table
|
|
|
|
|
|
@node Particular Headers
|
|
@subsection Particular Header Checks
|
|
|
|
These macros check for particular system header files---whether they
|
|
exist, and in some cases whether they declare certain symbols.
|
|
|
|
@defmac AC_HEADER_DIRENT
|
|
@acindex{HEADER_DIRENT}
|
|
@cvindex HAVE_DIRENT_H
|
|
@cvindex HAVE_NDIR_H
|
|
@cvindex HAVE_SYS_DIR_H
|
|
@cvindex HAVE_SYS_NDIR_H
|
|
@hdrindex dirent.h
|
|
@hdrindex sys/ndir.h
|
|
@hdrindex sys/dir.h
|
|
@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:
|
|
|
|
@multitable {@file{sys/ndir.h}} {@code{HAVE_SYS_NDIR_H}}
|
|
@item @file{dirent.h} @tab @code{HAVE_DIRENT_H}
|
|
@item @file{sys/ndir.h} @tab @code{HAVE_SYS_NDIR_H}
|
|
@item @file{sys/dir.h} @tab @code{HAVE_SYS_DIR_H}
|
|
@item @file{ndir.h} @tab @code{HAVE_NDIR_H}
|
|
@end multitable
|
|
|
|
The directory-library declarations in your source code should look
|
|
something like the following:
|
|
|
|
@example
|
|
@group
|
|
#if HAVE_DIRENT_H
|
|
# include <dirent.h>
|
|
# define NAMLEN(dirent) strlen((dirent)->d_name)
|
|
#else
|
|
# define dirent direct
|
|
# define NAMLEN(dirent) (dirent)->d_namlen
|
|
# if HAVE_SYS_NDIR_H
|
|
# include <sys/ndir.h>
|
|
# endif
|
|
# if HAVE_SYS_DIR_H
|
|
# include <sys/dir.h>
|
|
# endif
|
|
# if HAVE_NDIR_H
|
|
# include <ndir.h>
|
|
# endif
|
|
#endif
|
|
@end group
|
|
@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
|
|
@code{struct dirent} to the @code{NAMLEN} macro.
|
|
|
|
This macro also checks for the SCO Xenix @file{dir} and @file{x} libraries.
|
|
@end defmac
|
|
|
|
@defmac AC_HEADER_MAJOR
|
|
@acindex{HEADER_MAJOR}
|
|
@cvindex MAJOR_IN_MKDEV
|
|
@cvindex MAJOR_IN_SYSMACROS
|
|
@hdrindex sys/mkdev.h
|
|
@hdrindex sys/sysmacros.h
|
|
If @file{sys/types.h} does not define @code{major}, @code{minor}, and
|
|
@code{makedev}, but @file{sys/mkdev.h} does, define
|
|
@code{MAJOR_IN_MKDEV}; otherwise, if @file{sys/sysmacros.h} does, define
|
|
@code{MAJOR_IN_SYSMACROS}.
|
|
@end defmac
|
|
|
|
|
|
@defmac AC_HEADER_STAT
|
|
@acindex{HEADER_STAT}
|
|
@acindex{STAT_MACROS_BROKEN}
|
|
@hdrindex sys/stat.h
|
|
If the macros @code{S_ISDIR}, @code{S_ISREG}, etc.@: defined in
|
|
@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.
|
|
@end defmac
|
|
|
|
@defmac AC_HEADER_STDBOOL
|
|
@acindex{HEADER_STDBOOL}
|
|
@cvindex HAVE_STDBOOL_H
|
|
@cvindex HAVE__BOOL
|
|
@hdrindex stdbool.h
|
|
@hdrindex system.h
|
|
If @file{stdbool.h} exists and is conformant to C99, define
|
|
@code{HAVE_STDBOOL_H} to 1; if the type @code{_Bool} is defined, define
|
|
@code{HAVE__BOOL} to 1. To fulfill the C99 requirements, your
|
|
@file{system.h} should contain the following code:
|
|
|
|
@verbatim
|
|
#if HAVE_STDBOOL_H
|
|
# include <stdbool.h>
|
|
#else
|
|
# if ! HAVE__BOOL
|
|
# ifdef __cplusplus
|
|
typedef bool _Bool;
|
|
# else
|
|
typedef unsigned char _Bool;
|
|
# endif
|
|
# endif
|
|
# define bool _Bool
|
|
# define false 0
|
|
# define true 1
|
|
# define __bool_true_false_are_defined 1
|
|
#endif
|
|
@end verbatim
|
|
@end defmac
|
|
|
|
|
|
@defmac AC_HEADER_STDC
|
|
@acindex{HEADER_STDC}
|
|
@cvindex STDC_HEADERS
|
|
@hdrindex stdlib.h
|
|
@hdrindex stdarg.h
|
|
@hdrindex string.h
|
|
@hdrindex float.h
|
|
@hdrindex ctype.h
|
|
Define @code{STDC_HEADERS} if the system has @acronym{ANSI} C header files.
|
|
Specifically, this macro checks for @file{stdlib.h}, @file{stdarg.h},
|
|
@file{string.h}, and @file{float.h}; if the system has those, it
|
|
probably has the rest of the @acronym{ANSI} C 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 @acronym{ANSI} C requires.
|
|
|
|
Use @code{STDC_HEADERS} instead of @code{__STDC__} to determine whether
|
|
the system has @acronym{ANSI}-compliant header files (and probably C library
|
|
functions) because many systems that have GCC do not have @acronym{ANSI} C
|
|
header files.
|
|
|
|
@hdrindex string.h
|
|
@hdrindex strings.h
|
|
On systems without @acronym{ANSI} C 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 systems
|
|
contain a mix of functions from @acronym{ANSI} and @acronym{BSD}; some are
|
|
mostly @acronym{ANSI} but lack @samp{memmove}; some define the
|
|
@acronym{BSD} functions as macros in @file{string.h} or
|
|
@file{strings.h}; some have only the @acronym{BSD} functions but
|
|
@file{string.h}; some declare 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 has the
|
|
@acronym{ANSI} versions of those then it probably has most of the others.
|
|
If you put the following in @file{configure.ac}:
|
|
|
|
@example
|
|
AC_HEADER_STDC
|
|
AC_CHECK_FUNCS(strchr memcpy)
|
|
@end example
|
|
|
|
@noindent
|
|
then, in your code, you can use declarations like this:
|
|
|
|
@example
|
|
@group
|
|
#if STDC_HEADERS
|
|
# include <string.h>
|
|
#else
|
|
# if !HAVE_STRCHR
|
|
# define strchr index
|
|
# define strrchr rindex
|
|
# endif
|
|
char *strchr (), *strrchr ();
|
|
# if !HAVE_MEMCPY
|
|
# define memcpy(d, s, n) bcopy ((s), (d), (n))
|
|
# define memmove(d, s, n) bcopy ((s), (d), (n))
|
|
# endif
|
|
#endif
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
If you use a function like @code{memchr}, @code{memset}, @code{strtok},
|
|
or @code{strspn}, which have no @acronym{BSD} equivalent, then macros won't
|
|
suffice; 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
|
|
@samp{AC_REPLACE_FUNCS(memchr)}.
|
|
@end defmac
|
|
|
|
@defmac AC_HEADER_SYS_WAIT
|
|
@acindex{HEADER_SYS_WAIT}
|
|
@cvindex HAVE_SYS_WAIT_H
|
|
@hdrindex sys/wait.h
|
|
If @file{sys/wait.h} exists and is compatible with @acronym{POSIX}, define
|
|
@code{HAVE_SYS_WAIT_H}. Incompatibility can occur if @file{sys/wait.h}
|
|
does not exist, or if it uses the old @acronym{BSD} @code{union wait} instead
|
|
of @code{int} to store a status value. If @file{sys/wait.h} is not
|
|
@acronym{POSIX} compatible, then instead of including it, define the
|
|
@acronym{POSIX} macros with their usual interpretations. Here is an
|
|
example:
|
|
|
|
@example
|
|
@group
|
|
#include <sys/types.h>
|
|
#if HAVE_SYS_WAIT_H
|
|
# include <sys/wait.h>
|
|
#endif
|
|
#ifndef WEXITSTATUS
|
|
# define WEXITSTATUS(stat_val) ((unsigned)(stat_val) >> 8)
|
|
#endif
|
|
#ifndef WIFEXITED
|
|
# define WIFEXITED(stat_val) (((stat_val) & 255) == 0)
|
|
#endif
|
|
@end group
|
|
@end example
|
|
@end defmac
|
|
|
|
@cvindex _POSIX_VERSION
|
|
@hdrindex unistd.h
|
|
@code{_POSIX_VERSION} is defined when @file{unistd.h} is included on
|
|
@acronym{POSIX} systems. If there is no @file{unistd.h}, it is definitely
|
|
not a @acronym{POSIX} system. However, some non-@acronym{POSIX} systems do
|
|
have @file{unistd.h}.
|
|
|
|
The way to check if the system supports @acronym{POSIX} is:
|
|
|
|
@example
|
|
@group
|
|
#if HAVE_UNISTD_H
|
|
# include <sys/types.h>
|
|
# include <unistd.h>
|
|
#endif
|
|
|
|
#ifdef _POSIX_VERSION
|
|
/* Code for POSIX systems. */
|
|
#endif
|
|
@end group
|
|
@end example
|
|
|
|
@defmac AC_HEADER_TIME
|
|
@acindex{HEADER_TIME}
|
|
@cvindex TIME_WITH_SYS_TIME
|
|
@hdrindex time.h
|
|
@hdrindex sys/time.h
|
|
If a program may include both @file{time.h} and @file{sys/time.h},
|
|
define @code{TIME_WITH_SYS_TIME}. On some older systems,
|
|
@file{sys/time.h} includes @file{time.h}, but @file{time.h} is not
|
|
protected against multiple inclusion, so programs should not explicitly
|
|
include both files. This macro is useful in programs that use, for
|
|
example, @code{struct timeval} as well as
|
|
@code{struct tm}. It is best used in conjunction with
|
|
@code{HAVE_SYS_TIME_H}, which can be checked for using
|
|
@code{AC_CHECK_HEADERS(sys/time.h)}.
|
|
|
|
@example
|
|
@group
|
|
#if TIME_WITH_SYS_TIME
|
|
# include <sys/time.h>
|
|
# include <time.h>
|
|
#else
|
|
# if HAVE_SYS_TIME_H
|
|
# include <sys/time.h>
|
|
# else
|
|
# include <time.h>
|
|
# endif
|
|
#endif
|
|
@end group
|
|
@end example
|
|
@end defmac
|
|
|
|
|
|
@defmac AC_HEADER_TIOCGWINSZ
|
|
@acindex{HEADER_TIOCGWINSZ}
|
|
@cvindex GWINSZ_IN_SYS_IOCTL
|
|
@hdrindex sys/ioctl.h
|
|
@hdrindex termios.h
|
|
@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:
|
|
|
|
@example
|
|
@group
|
|
#if HAVE_TERMIOS_H
|
|
# include <termios.h>
|
|
#endif
|
|
|
|
#if GWINSZ_IN_SYS_IOCTL
|
|
# include <sys/ioctl.h>
|
|
#endif
|
|
@end group
|
|
@end example
|
|
@end defmac
|
|
|
|
@node Generic Headers
|
|
@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}).
|
|
|
|
@defmac AC_CHECK_HEADER (@var{header-file}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
|
|
@acindex{CHECK_HEADER}
|
|
If the system header file @var{header-file} is compilable, execute shell
|
|
commands @var{action-if-found}, otherwise execute
|
|
@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.
|
|
|
|
For compatibility issues with older versions of Autoconf, please read
|
|
below.
|
|
@end defmac
|
|
|
|
@defmac AC_CHECK_HEADERS (@var{header-file}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
|
|
@acindex{CHECK_HEADERS}
|
|
@cvindex HAVE_@var{header}
|
|
For each given system header file @var{header-file} in the
|
|
whitespace-separated argument list that exists, define
|
|
@code{HAVE_@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.
|
|
|
|
For compatibility issues with older versions of Autoconf, please read
|
|
below.
|
|
@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. If you need to check whether a
|
|
header is preprocessable, you can use @code{AC_PREPROC_IFELSE}
|
|
(@pxref{Running the Preprocessor}).
|
|
|
|
This scheme, which improves the robustness of the test, also requires
|
|
that you make sure that headers that must be included before the
|
|
@var{header-file} be part of the @var{includes}, (@pxref{Default
|
|
Includes}). If looking for @file{bar.h}, which requires that
|
|
@file{foo.h} be included before if it exists, we suggest the following
|
|
scheme:
|
|
|
|
@verbatim
|
|
AC_CHECK_HEADERS([foo.h])
|
|
AC_CHECK_HEADERS([bar.h], [], [],
|
|
[#if HAVE_FOO_H
|
|
# include <foo.h>
|
|
# endif
|
|
])
|
|
@end verbatim
|
|
|
|
@node Declarations
|
|
@section Declarations
|
|
@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
|
|
@code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
|
|
|
|
@menu
|
|
* Particular Declarations:: Macros to check for certain declarations
|
|
* Generic Declarations:: How to find other declarations
|
|
@end menu
|
|
|
|
@node Particular Declarations
|
|
@subsection Particular Declaration Checks
|
|
|
|
There are no specific macros for declarations.
|
|
|
|
@node Generic Declarations
|
|
@subsection Generic Declaration Checks
|
|
|
|
These macros are used to find declarations not covered by the ``particular''
|
|
test macros.
|
|
|
|
@defmac AC_CHECK_DECL (@var{symbol}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
|
|
@acindex{CHECK_DECL}
|
|
If @var{symbol} (a function or a variable) is not declared in
|
|
@var{includes} and a declaration is needed, run the shell commands
|
|
@var{action-if-not-found}, otherwise @var{action-if-found}. If no
|
|
@var{includes} are specified, the default includes are used
|
|
(@pxref{Default Includes}).
|
|
|
|
This macro actually tests whether it is valid to use @var{symbol} as an
|
|
r-value, not if it is really declared, because it is much safer to avoid
|
|
introducing extra declarations when they are not needed.
|
|
@end defmac
|
|
|
|
@defmac AC_CHECK_DECLS (@var{symbols}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
|
|
@acindex{CHECK_DECLS}
|
|
@cvindex HAVE_DECL_@var{symbol}
|
|
For each of the @var{symbols} (@emph{comma}-separated list), define
|
|
@code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
|
|
@var{symbol} is declared, otherwise to @samp{0}. If
|
|
@var{action-if-not-found} is given, it is additional shell code to
|
|
execute when one of the function declarations is needed, otherwise
|
|
@var{action-if-found} is executed.
|
|
|
|
This macro uses an m4 list as first argument:
|
|
@example
|
|
AC_CHECK_DECLS(strdup)
|
|
AC_CHECK_DECLS([strlen])
|
|
AC_CHECK_DECLS([malloc, realloc, calloc, free])
|
|
@end example
|
|
|
|
Unlike the other @samp{AC_CHECK_*S} macros, when a @var{symbol} is not
|
|
declared, @code{HAVE_DECL_@var{symbol}} is defined to @samp{0} instead
|
|
of leaving @code{HAVE_DECL_@var{symbol}} undeclared. When you are
|
|
@emph{sure} that the check was performed, use
|
|
@code{HAVE_DECL_@var{symbol}} just like any other result of Autoconf:
|
|
|
|
@example
|
|
#if !HAVE_DECL_SYMBOL
|
|
extern char *symbol;
|
|
#endif
|
|
@end example
|
|
|
|
@noindent
|
|
If the test may have not been performed, however, because it is safer
|
|
@emph{not} to declare a symbol than to use a declaration that conflicts
|
|
with the system's one, you should use:
|
|
|
|
@example
|
|
#if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC
|
|
void *malloc (size_t *s);
|
|
#endif
|
|
@end example
|
|
|
|
@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.
|
|
@end defmac
|
|
|
|
|
|
@node Structures
|
|
@section Structures
|
|
@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
|
|
@code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
|
|
|
|
@menu
|
|
* Particular Structures:: Macros to check for certain structure members
|
|
* Generic Structures:: How to find other structure members
|
|
@end menu
|
|
|
|
@node Particular Structures
|
|
@subsection Particular Structure Checks
|
|
|
|
The following macros check for certain structures or structure members.
|
|
|
|
@defmac AC_STRUCT_ST_BLKSIZE
|
|
@acindex{STRUCT_ST_BLKSIZE}
|
|
@cvindex HAVE_STRUCT_STAT_ST_BLKSIZE
|
|
@cvindex HAVE_ST_BLKSIZE
|
|
If @code{struct stat} contains an @code{st_blksize} member, define
|
|
@code{HAVE_STRUCT_STAT_ST_BLKSIZE}. The former name,
|
|
@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
|
|
|
|
@example
|
|
AC_CHECK_MEMBERS([struct stat.st_blksize])
|
|
@end example
|
|
@end defmac
|
|
|
|
@defmac AC_STRUCT_ST_BLOCKS
|
|
@acindex{STRUCT_ST_BLOCKS}
|
|
@cvindex HAVE_STRUCT_STAT_ST_BLOCKS
|
|
@cvindex HAVE_ST_BLOCKS
|
|
@ovindex LIBOBJS
|
|
If @code{struct stat} contains an @code{st_blocks} member, define
|
|
@code{HAVE_STRUCT_STAT_ST_BLOCKS}. Otherwise, require an
|
|
@code{AC_LIBOBJ} replacement of @samp{fileblocks}. The former name,
|
|
@code{HAVE_ST_BLOCKS} is to be avoided, as its support will cease in the
|
|
future.
|
|
@end defmac
|
|
|
|
@defmac AC_STRUCT_ST_RDEV
|
|
@acindex{STRUCT_ST_RDEV}
|
|
@cvindex HAVE_ST_RDEV
|
|
@cvindex HAVE_STRUCT_STAT_ST_RDEV
|
|
If @code{struct stat} contains an @code{st_rdev} member, define
|
|
@code{HAVE_STRUCT_STAT_ST_RDEV}. The former name for this macro,
|
|
@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:
|
|
@example
|
|
AC_CHECK_MEMBERS([struct stat.st_rdev])
|
|
@end example
|
|
@end defmac
|
|
|
|
@defmac AC_STRUCT_TM
|
|
@acindex{STRUCT_TM}
|
|
@cvindex TM_IN_SYS_TIME
|
|
@hdrindex time.h
|
|
@hdrindex sys/time.h
|
|
If @file{time.h} does not define @code{struct tm}, define
|
|
@code{TM_IN_SYS_TIME}, which means that including @file{sys/time.h}
|
|
had better define @code{struct tm}.
|
|
@end defmac
|
|
|
|
@defmac AC_STRUCT_TIMEZONE
|
|
@acindex{STRUCT_TIMEZONE}
|
|
@cvindex HAVE_TM_ZONE
|
|
@cvindex HAVE_TZNAME
|
|
Figure out how to get the current timezone. If @code{struct tm} has a
|
|
@code{tm_zone} member, define @code{HAVE_STRUCT_TM_TM_ZONE} (and the
|
|
obsoleted @code{HAVE_TM_ZONE}). Otherwise, if the external array
|
|
@code{tzname} is found, define @code{HAVE_TZNAME}.
|
|
@end defmac
|
|
|
|
@node Generic Structures
|
|
@subsection Generic Structure Checks
|
|
|
|
These macros are used to find structure members not covered by the
|
|
``particular'' test macros.
|
|
|
|
@defmac AC_CHECK_MEMBER (@var{aggregate}.@var{member}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
|
|
@acindex{CHECK_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}).
|
|
|
|
@example
|
|
AC_CHECK_MEMBER(struct passwd.pw_gecos,,
|
|
[AC_MSG_ERROR([We need `passwd.pw_gecos'!])],
|
|
[#include <pwd.h>])
|
|
@end example
|
|
|
|
You can use this macro for sub-members:
|
|
|
|
@example
|
|
AC_CHECK_MEMBER(struct top.middle.bot)
|
|
@end example
|
|
@end defmac
|
|
|
|
@defmac AC_CHECK_MEMBERS (@var{members}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
|
|
@acindex{CHECK_MEMBERS}
|
|
Check for the existence of each @samp{@var{aggregate}.@var{member}} of
|
|
@var{members} using the previous macro. When @var{member} belongs to
|
|
@var{aggregate}, define @code{HAVE_@var{aggregate}_@var{member}} (in all
|
|
capitals, with spaces and dots replaced by underscores). If
|
|
@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.
|
|
|
|
This macro uses m4 lists:
|
|
@example
|
|
AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize])
|
|
@end example
|
|
@end defmac
|
|
|
|
|
|
@node Types
|
|
@section 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.
|
|
|
|
@menu
|
|
* Particular Types:: Special handling to find certain types
|
|
* Generic Types:: How to find other types
|
|
@end menu
|
|
|
|
@node Particular Types
|
|
@subsection Particular Type Checks
|
|
|
|
@hdrindex sys/types.h
|
|
@hdrindex stdlib.h
|
|
These macros check for particular C types in @file{sys/types.h},
|
|
@file{stdlib.h} and others, if they exist.
|
|
|
|
@defmac AC_TYPE_GETGROUPS
|
|
@acindex{TYPE_GETGROUPS}
|
|
@cvindex GETGROUPS_T
|
|
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}.
|
|
@end defmac
|
|
|
|
@defmac AC_TYPE_MBSTATE_T
|
|
@acindex{TYPE_MBSTATE_T}
|
|
@cvindex mbstate_t
|
|
@hdrindex wchar.h
|
|
Define @code{HAVE_MBSTATE_T} if @code{<wchar.h>} declares the
|
|
@code{mbstate_t} type. Also, define @code{mbstate_t} to be a type if
|
|
@code{<wchar.h>} does not declare it.
|
|
@end defmac
|
|
|
|
@defmac AC_TYPE_MODE_T
|
|
@acindex{TYPE_MODE_T}
|
|
@cvindex mode_t
|
|
Equivalent to @samp{AC_CHECK_TYPE(mode_t, int)}.
|
|
@end defmac
|
|
|
|
@defmac AC_TYPE_OFF_T
|
|
@acindex{TYPE_OFF_T}
|
|
@cvindex off_t
|
|
Equivalent to @samp{AC_CHECK_TYPE(off_t, long)}.
|
|
@end defmac
|
|
|
|
@defmac AC_TYPE_PID_T
|
|
@acindex{TYPE_PID_T}
|
|
@cvindex pid_t
|
|
Equivalent to @samp{AC_CHECK_TYPE(pid_t, int)}.
|
|
@end defmac
|
|
|
|
@defmac AC_TYPE_SIGNAL
|
|
@acindex{TYPE_SIGNAL}
|
|
@cvindex RETSIGTYPE
|
|
@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
|
|
@code{void}; otherwise, define it to be @code{int}.
|
|
|
|
Define signal handlers as returning type @code{RETSIGTYPE}:
|
|
|
|
@example
|
|
@group
|
|
RETSIGTYPE
|
|
hup_handler ()
|
|
@{
|
|
@dots{}
|
|
@}
|
|
@end group
|
|
@end example
|
|
@end defmac
|
|
|
|
@defmac AC_TYPE_SIZE_T
|
|
@acindex{TYPE_SIZE_T}
|
|
@cvindex size_t
|
|
Equivalent to @samp{AC_CHECK_TYPE(size_t, unsigned)}.
|
|
@end defmac
|
|
|
|
@defmac AC_TYPE_UID_T
|
|
@acindex{TYPE_UID_T}
|
|
@cvindex uid_t
|
|
@cvindex gid_t
|
|
If @code{uid_t} is not defined, define @code{uid_t} to be @code{int} and
|
|
@code{gid_t} to be @code{int}.
|
|
@end defmac
|
|
|
|
@node Generic Types
|
|
@subsection Generic Type Checks
|
|
|
|
These macros are used to check for types not covered by the ``particular''
|
|
test macros.
|
|
|
|
@defmac AC_CHECK_TYPE (@var{type}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
|
|
@acindex{CHECK_TYPE}
|
|
Check whether @var{type} is defined. It may be a compiler builtin type
|
|
or defined by the @var{includes} (@pxref{Default Includes}).
|
|
@end defmac
|
|
|
|
|
|
@defmac AC_CHECK_TYPES (@var{types}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
|
|
@acindex{CHECK_TYPES}
|
|
For each @var{type} of the @var{types} that is defined, define
|
|
@code{HAVE_@var{type}} (in all capitals). If no @var{includes} are
|
|
specified, the default includes are used (@pxref{Default Includes}). If
|
|
@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:
|
|
@example
|
|
AC_CHECK_TYPES(ptrdiff_t)
|
|
AC_CHECK_TYPES([unsigned long long, uintmax_t])
|
|
@end example
|
|
|
|
@end defmac
|
|
|
|
Autoconf, up to 2.13, used to provide to another version of
|
|
@code{AC_CHECK_TYPE}, broken by design. In order to keep backward
|
|
compatibility, a simple heuristics, quite safe but not totally, is
|
|
implemented. In case of doubt, read the documentation of the former
|
|
@code{AC_CHECK_TYPE}, see @ref{Obsolete Macros}.
|
|
|
|
|
|
@node Compilers and Preprocessors
|
|
@section Compilers and Preprocessors
|
|
|
|
@ovindex EXEEXT
|
|
All the tests for compilers (@code{AC_PROG_CC}, @code{AC_PROG_CXX},
|
|
@code{AC_PROG_F77}) define the output variable @code{EXEEXT} based on
|
|
the output of the compiler, typically to the empty string if Unix and
|
|
@samp{.exe} if Win32 or OS/2.
|
|
|
|
@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 Unix, @samp{obj} if Win32.
|
|
|
|
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.
|
|
|
|
@menu
|
|
* Specific Compiler Characteristics:: Some portability issues
|
|
* Generic Compiler Characteristics:: Language independent tests and features
|
|
* C Compiler:: Checking its characteristics
|
|
* C++ Compiler:: Likewise
|
|
* Fortran Compiler:: Likewise
|
|
@end menu
|
|
|
|
@node Specific Compiler Characteristics
|
|
@subsection Specific Compiler Characteristics
|
|
|
|
Some compilers exhibit different behaviors.
|
|
|
|
@table @asis
|
|
@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}s are 4
|
|
bytes long:
|
|
|
|
@example
|
|
int
|
|
main (void)
|
|
@{
|
|
static int test_array [sizeof (int) == 4 ? 1 : -1];
|
|
test_array [0] = 0
|
|
return 0;
|
|
@}
|
|
@end example
|
|
|
|
@noindent
|
|
To our knowledge, there is a single compiler that does not support this
|
|
trick: the HP C compilers (the real one, not only the ``bundled'') on
|
|
HP-UX 11.00:
|
|
|
|
@example
|
|
$ @kbd{cc -c -Ae +O2 +Onolimit conftest.c}
|
|
cc: "conftest.c": error 1879: Variable-length arrays cannot \
|
|
have static storage.
|
|
@end example
|
|
|
|
Autoconf works around this problem by casting @code{sizeof (int)} to
|
|
@code{long} before comparing it.
|
|
@end table
|
|
|
|
@node Generic Compiler Characteristics
|
|
@subsection Generic Compiler Characteristics
|
|
|
|
@defmac AC_CHECK_SIZEOF (@var{type}, @ovar{unused}, @dvar{includes, default-includes})
|
|
@acindex{CHECK_SIZEOF}
|
|
Define @code{SIZEOF_@var{type}} (@pxref{Standard Symbols}) to be the
|
|
size in bytes of @var{type}. If @samp{type} is unknown, it gets a size
|
|
of 0. If no @var{includes} are specified, the default includes are used
|
|
(@pxref{Default Includes}). If you provide @var{include}, be sure to
|
|
include @file{stdio.h} which is required for this macro to run.
|
|
|
|
This macro now works even when cross-compiling. The @var{unused}
|
|
argument was used when cross-compiling.
|
|
|
|
For example, the call
|
|
|
|
@example
|
|
AC_CHECK_SIZEOF(int *)
|
|
@end example
|
|
|
|
@noindent
|
|
defines @code{SIZEOF_INT_P} to be 8 on DEC Alpha AXP systems.
|
|
@end defmac
|
|
|
|
@defmac AC_LANG_WERROR
|
|
@acindex{LANG_WERROR}
|
|
Normally Autoconf ignores warnings generated by the compiler, linker, and
|
|
preprocessor. If this macro is used, warnings will be treated as fatal
|
|
errors instead for the current language. This macro is useful when the
|
|
results of configuration will be used where warnings are unacceptable; for
|
|
instance, if parts of a program are built with the GCC @samp{-Werror}
|
|
option. If the whole program will be built using @samp{-Werror} it is
|
|
often simpler to put @samp{-Werror} in the compiler flags (@code{CFLAGS}
|
|
etc.).
|
|
@end defmac
|
|
|
|
@node C Compiler
|
|
@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.
|
|
|
|
@table @asis
|
|
@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). Running the compiler on the following source,
|
|
|
|
@example
|
|
#ifdef __STDC__
|
|
/\
|
|
* A comment with backslash-newlines in it. %@{ %@} *\
|
|
\
|
|
/
|
|
char str[] = "\\
|
|
" A string with backslash-newlines in it %@{ %@} \\
|
|
"";
|
|
char apostrophe = '\\
|
|
\
|
|
'\
|
|
';
|
|
#endif
|
|
@end example
|
|
|
|
@noindent
|
|
yields
|
|
|
|
@example
|
|
@error{}cpp: "foo.c", line 13: error 4048: Non-terminating comment at end of file.
|
|
@error{}cpp: "foo.c", line 13: error 4033: Missing #endif at end of file.
|
|
@end example
|
|
|
|
@noindent
|
|
Removing the lines with solitary backslashes solves the problem.
|
|
|
|
@item Don't compile several files at once if output matters to you
|
|
Some compilers, such as the HP's, reports the name of the file it is
|
|
compiling @emph{when} they are several. For instance:
|
|
|
|
@example
|
|
$ @kbd{cc a.c b.c}
|
|
a.c:
|
|
b.c:
|
|
@end example
|
|
|
|
@noindent
|
|
This can cause problems if you observe the output of the compiler to
|
|
detect failures. Invoking @samp{cc -c a.c -o a.o; cc -c b.c -o b.o; cc
|
|
a.o b.o -o c} solves the issue.
|
|
|
|
@item Don't rely on correct @code{#line} support
|
|
On Solaris 8, @command{c89} (Sun WorkShop 6 update 2 C 5.3 Patch
|
|
111679-08 2002/05/09)) rejects @code{#line} directives whose line
|
|
numbers are greater than 32767. In addition, nothing in @sc{posix}
|
|
makes this invalid. That is the reason why Autoconf stopped issuing
|
|
@code{#line} directives.
|
|
@end table
|
|
|
|
@defmac AC_PROG_CC (@ovar{compiler-search-list})
|
|
@acindex{PROG_CC}
|
|
@ovindex CC
|
|
@ovindex CFLAGS
|
|
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 space 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:
|
|
|
|
@example
|
|
AC_PROG_CC(cl egcs gcc cc)
|
|
@end example
|
|
|
|
If the C compiler is not in @acronym{ANSI} C mode by default, try to add an
|
|
option to output variable @code{CC} to make it so. This macro tries
|
|
various options that select @acronym{ANSI} C on some system or another. It
|
|
considers the compiler to be in @acronym{ANSI} C mode if it handles function
|
|
prototypes correctly.
|
|
|
|
After calling this macro you can check whether the C compiler has been
|
|
set to accept @acronym{ANSI} C; if not, the shell variable
|
|
@code{ac_cv_prog_cc_stdc} is set to @samp{no}. If you wrote your source
|
|
code in @acronym{ANSI} C, you can make an un-@acronym{ANSI}fied copy of it by
|
|
using the program @code{ansi2knr}, which comes with Automake. See also
|
|
under @code{AC_C_PROTOTYPES} below.
|
|
|
|
If using the @acronym{GNU} C compiler, set shell variable @code{GCC} to
|
|
@samp{yes}. If output variable @code{CFLAGS} was not already set, set
|
|
it to @option{-g -O2} for the @acronym{GNU} C compiler (@option{-O2} on systems
|
|
where GCC does not accept @option{-g}), or @option{-g} for other compilers.
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_CC_C_O
|
|
@acindex{PROG_CC_C_O}
|
|
@cvindex NO_MINUS_C_MINUS_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 @acronym{GNU} Make to choose the default C compilation
|
|
rule.
|
|
@end defmac
|
|
|
|
|
|
@defmac AC_PROG_CPP
|
|
@acindex{PROG_CPP}
|
|
@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.
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_CPP_WERROR
|
|
@acindex{PROG_CPP_WERROR}
|
|
@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.
|
|
@end defmac
|
|
|
|
|
|
The following macros check for C compiler or machine architecture
|
|
features. To check for characteristics not listed here, use
|
|
@code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
|
|
@code{AC_RUN_IFELSE} (@pxref{Run Time}).
|
|
|
|
@defmac AC_C_BACKSLASH_A
|
|
@acindex{HAVE_C_BACKSLASH_A}
|
|
Define @samp{HAVE_C_BACKSLASH_A} to 1 if the C compiler understands
|
|
@samp{\a}.
|
|
@end defmac
|
|
|
|
@defmac AC_C_BIGENDIAN (@ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-unknown})
|
|
@acindex{C_BIGENDIAN}
|
|
@cvindex WORDS_BIGENDIAN
|
|
@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
|
|
@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.
|
|
|
|
The default for @var{action-if-true} is to define
|
|
@samp{WORDS_BIGENDIAN}. The default for @var{action-if-false} is to do
|
|
nothing. And finally, the default for @var{action-if-unknown} is to
|
|
abort configure and tell the installer which variable he should preset
|
|
to bypass this test.
|
|
@end defmac
|
|
|
|
@defmac AC_C_CONST
|
|
@acindex{C_CONST}
|
|
@cvindex const
|
|
If the C compiler does not fully support the @acronym{ANSI} C qualifier
|
|
@code{const}, 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 @file{Makefile} or configuration header file will
|
|
define 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:
|
|
|
|
@example
|
|
const int foo;
|
|
@end example
|
|
|
|
@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.
|
|
@end defmac
|
|
|
|
@defmac AC_C_RESTRICT
|
|
@acindex C_RESTRICT
|
|
@cvindex restrict
|
|
If the C compiler recognizes the @code{restrict} keyword, don't do anything.
|
|
If it recognizes only a variant spelling (@code{__restrict},
|
|
@code{__restrict__}, or @code{_Restrict}), then define
|
|
@code{restrict} to that.
|
|
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 @file{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.
|
|
@end defmac
|
|
|
|
@defmac AC_C_VOLATILE
|
|
@acindex{C_VOLATILE}
|
|
@cvindex volatile
|
|
If the C compiler does not understand the keyword @code{volatile},
|
|
define @code{volatile} to be empty. Programs can simply use
|
|
@code{volatile} as if every C compiler supported it; for those that do
|
|
not, the @file{Makefile} or configuration header will define it as
|
|
empty.
|
|
|
|
If the correctness of your program depends on the semantics of
|
|
@code{volatile}, simply defining it to be empty does, in a sense, break
|
|
your code. However, given that the compiler does not support
|
|
@code{volatile}, you are at its mercy anyway. At least your
|
|
program will compile, when it wouldn't before.
|
|
|
|
In general, the @code{volatile} keyword is a feature of @acronym{ANSI} C, so
|
|
you might expect that @code{volatile} is available only when
|
|
@code{__STDC__} is defined. However, Ultrix 4.3's native compiler does
|
|
support volatile, but does not define @code{__STDC__}.
|
|
@end defmac
|
|
|
|
@defmac AC_C_INLINE
|
|
@acindex{C_INLINE}
|
|
@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.
|
|
@end defmac
|
|
|
|
@defmac AC_C_CHAR_UNSIGNED
|
|
@acindex{C_CHAR_UNSIGNED}
|
|
@cvindex __CHAR_UNSIGNED__
|
|
If the C type @code{char} is unsigned, define @code{__CHAR_UNSIGNED__},
|
|
unless the C compiler predefines it.
|
|
@end defmac
|
|
|
|
@defmac AC_C_LONG_DOUBLE
|
|
@acindex{C_LONG_DOUBLE}
|
|
@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
|
|
@code{HAVE_LONG_DOUBLE}.
|
|
@end defmac
|
|
|
|
@defmac AC_C_STRINGIZE
|
|
@acindex{C_STRINGIZE}
|
|
@cvindex HAVE_STRINGIZE
|
|
If the C preprocessor supports the stringizing operator, define
|
|
@code{HAVE_STRINGIZE}. The stringizing operator is @samp{#} and is
|
|
found in macros such as this:
|
|
|
|
@example
|
|
#define x(y) #y
|
|
@end example
|
|
@end defmac
|
|
|
|
@defmac AC_C_PROTOTYPES
|
|
@acindex{C_PROTOTYPES}
|
|
@cvindex PROTOTYPES
|
|
@cvindex __PROTOTYPES
|
|
@cvindex PARAMS
|
|
If function prototypes are understood by the compiler (as determined by
|
|
@code{AC_PROG_CC}), define @code{PROTOTYPES} and @code{__PROTOTYPES}.
|
|
In the case the compiler does not handle
|
|
prototypes, you should use @code{ansi2knr}, which comes with the
|
|
Automake distribution, to unprotoize function definitions. For
|
|
function prototypes, you should first define @code{PARAMS}:
|
|
|
|
@example
|
|
#ifndef PARAMS
|
|
# if PROTOTYPES
|
|
# define PARAMS(protos) protos
|
|
# else /* no PROTOTYPES */
|
|
# define PARAMS(protos) ()
|
|
# endif /* no PROTOTYPES */
|
|
#endif
|
|
@end example
|
|
|
|
@noindent
|
|
then use it this way:
|
|
|
|
@example
|
|
size_t my_strlen PARAMS ((const char *));
|
|
@end example
|
|
@end defmac
|
|
|
|
This macro also defines @code{__PROTOTYPES}; this is for the benefit of
|
|
header files that cannot use macros that infringe on user name space.
|
|
|
|
@defmac AC_PROG_GCC_TRADITIONAL
|
|
@acindex{PROG_GCC_TRADITIONAL}
|
|
@ovindex CC
|
|
Add @option{-traditional} to output variable @code{CC} if using the
|
|
@acronym{GNU} C compiler and @code{ioctl} does not work properly without
|
|
@option{-traditional}. That usually happens when the fixed header files
|
|
have not been installed on an old system. Since recent versions of the
|
|
@acronym{GNU} C compiler fix the header files automatically when installed,
|
|
this is becoming a less prevalent problem.
|
|
@end defmac
|
|
|
|
|
|
@node C++ Compiler
|
|
@subsection C++ Compiler Characteristics
|
|
|
|
|
|
@defmac AC_PROG_CXX (@ovar{compiler-search-list})
|
|
@acindex{PROG_CXX}
|
|
@ovindex CXX
|
|
@ovindex CXXFLAGS
|
|
Determine a C++ compiler to use. Check if the environment variable
|
|
@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 space 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:
|
|
|
|
@example
|
|
AC_PROG_CXX(cl KCC CC cxx cc++ xlC aCC c++ g++ egcs gcc)
|
|
@end example
|
|
|
|
If using the @acronym{GNU} C++ compiler, set shell variable @code{GXX} to
|
|
@samp{yes}. If output variable @code{CXXFLAGS} was not already set, set
|
|
it to @option{-g -O2} for the @acronym{GNU} C++ compiler (@option{-O2} on
|
|
systems where G++ does not accept @option{-g}), or @option{-g} for other
|
|
compilers.
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_CXXCPP
|
|
@acindex{PROG_CXXCPP}
|
|
@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 only portable to run @code{CXXCPP} on files with a @file{.c},
|
|
@file{.C}, or @file{.cc} 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++.
|
|
@end defmac
|
|
|
|
|
|
|
|
@node Fortran Compiler
|
|
@subsection Fortran Compiler Characteristics
|
|
|
|
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},
|
|
@code{FCFLAGS}, and @code{FCLIBS}.
|
|
|
|
Except for two new macros @code{AC_FC_SRCEXT} and
|
|
@code{AC_FC_FREEFORM} (see below), the @code{FC} and @code{F77} macros
|
|
behave almost identically, and so they are documented together in this
|
|
section.
|
|
|
|
|
|
@defmac AC_PROG_F77 (@ovar{compiler-search-list})
|
|
@acindex{PROG_F77}
|
|
@ovindex F77
|
|
@ovindex FFLAGS
|
|
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 space 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
|
|
@code{AC_PROG_F77} like this:
|
|
|
|
@example
|
|
AC_PROG_F77(fl32 f77 fort77 xlf g77 f90 xlf90)
|
|
@end example
|
|
|
|
If using @code{g77} (the @acronym{GNU} Fortran 77 compiler), then
|
|
@code{AC_PROG_F77} will 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
|
|
@code{FFLAGS} to @option{-g} for all other Fortran 77 compilers.
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_FC (@ovar{compiler-search-list}, @ovar{dialect})
|
|
@acindex{PROG_FC}
|
|
@ovindex FC
|
|
@ovindex FCFLAGS
|
|
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
|
|
@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
|
|
@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 space separated list of Fortran
|
|
compilers to search for, just as in @code{AC_PROG_F77}.
|
|
|
|
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
|
|
@option{-O2} where @code{g77} does not accept @option{-g}). Otherwise,
|
|
set @code{FCFLAGS} to @option{-g} for all other Fortran compilers.
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_F77_C_O
|
|
@defmacx AC_PROG_FC_C_O
|
|
@acindex{PROG_F77_C_O}
|
|
@acindex{PROG_FC_C_O}
|
|
@cvindex F77_NO_MINUS_C_MINUS_O
|
|
@cvindex FC_NO_MINUS_C_MINUS_O
|
|
Test if the Fortran compiler accepts the options @option{-c} and
|
|
@option{-o} simultaneously, and define @code{F77_NO_MINUS_C_MINUS_O} or
|
|
@code{FC_NO_MINUS_C_MINUS_O}, respectively, if it does not.
|
|
@end defmac
|
|
|
|
The following macros check for Fortran compiler characteristics.
|
|
To check for characteristics not listed here, use
|
|
@code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
|
|
@code{AC_RUN_IFELSE} (@pxref{Run Time}), 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}).
|
|
|
|
|
|
@defmac AC_F77_LIBRARY_LDFLAGS
|
|
@defmacx AC_FC_LIBRARY_LDFLAGS
|
|
@acindex{F77_LIBRARY_LDFLAGS}
|
|
@ovindex FLIBS
|
|
@acindex{FC_LIBRARY_LDFLAGS}
|
|
@ovindex FCLIBS
|
|
Determine the linker flags (e.g., @option{-L} and @option{-l}) for the
|
|
@dfn{Fortran intrinsic and run-time 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 include 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, @acronym{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 run-time 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}/@code{AC_FC_DUMMY_MAIN} or
|
|
@code{AC_F77_MAIN}/@code{AC_FC_MAIN} will probably also be necessary to
|
|
link C/C++ with Fortran; see below.
|
|
@end defmac
|
|
|
|
@defmac AC_F77_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
|
|
@defmacx AC_FC_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
|
|
@acindex{F77_DUMMY_MAIN}
|
|
@cvindex F77_DUMMY_MAIN
|
|
With many compilers, the Fortran libraries detected by
|
|
@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
|
|
@code{AC_F77_DUMMY_MAIN}/@code{AC_FC_DUMMY_MAIN} or
|
|
@code{AC_F77_MAIN}/@code{AC_FC_MAIN} macro figures 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
|
|
@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
|
|
@code{FC_DUMMY_MAIN} to the name of this routine (e.g., @code{MAIN__})
|
|
@emph{if} it is required. @ovar{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:
|
|
|
|
@example
|
|
#ifdef F77_DUMMY_MAIN
|
|
# ifdef __cplusplus
|
|
extern "C"
|
|
# endif
|
|
int F77_DUMMY_MAIN() @{ return 1; @}
|
|
#endif
|
|
@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.
|
|
@end defmac
|
|
|
|
@defmac AC_F77_MAIN
|
|
@defmacx AC_FC_MAIN
|
|
@acindex{F77_MAIN}
|
|
@cvindex F77_MAIN
|
|
@acindex{FC_MAIN}
|
|
@cvindex 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@. The
|
|
@code{AC_F77_MAIN}/@code{AC_FC_MAIN} macro detects whether it is
|
|
@emph{possible} to utilize such an alternate main function, and defines
|
|
@code{F77_MAIN}/@code{FC_MAIN} to the name of the function. (If no
|
|
alternate main function name is found, @code{F77_MAIN}/@code{FC_MAIN} is
|
|
simply defined to @code{main}.)
|
|
|
|
Thus, when calling Fortran routines from C that perform things like I/O,
|
|
one should use this macro and name the "main" function
|
|
@code{F77_MAIN}/@code{FC_MAIN} instead of @code{main}.
|
|
@end defmac
|
|
|
|
@defmac AC_F77_WRAPPERS
|
|
@defmacx AC_FC_WRAPPERS
|
|
@acindex{F77_WRAPPERS}
|
|
@cvindex F77_FUNC
|
|
@cvindex F77_FUNC_
|
|
@acindex{FC_WRAPPERS}
|
|
@cvindex FC_FUNC
|
|
@cvindex FC_FUNC_
|
|
Defines C macros @code{F77_FUNC(name,NAME)}/@code{FC_FUNC(name,NAME)}
|
|
and @code{F77_FUNC_(name,NAME)}/@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
|
|
@code{AC_F77_WRAPPERS} or @code{AC_FC_WRAPPERS}. For example, suppose
|
|
you have the following Fortran 77 subroutine:
|
|
|
|
@example
|
|
subroutine foobar(x,y)
|
|
double precision x, y
|
|
y = 3.14159 * x
|
|
return
|
|
end
|
|
@end example
|
|
|
|
You would then declare its prototype in C or C++ as:
|
|
|
|
@example
|
|
#define FOOBAR_F77 F77_FUNC(foobar,FOOBAR)
|
|
#ifdef __cplusplus
|
|
extern "C" /* prevent C++ name mangling */
|
|
#endif
|
|
void FOOBAR_F77(double *x, double *y);
|
|
@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, @acronym{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
|
|
will generate a compile-time error, but some other behavior
|
|
(e.g., disabling Fortran-related features) can be induced by checking
|
|
whether the @code{F77_FUNC}/@code{FC_FUNC} macro is defined.
|
|
|
|
Now, to call that routine from a C program, we would do something like:
|
|
|
|
@example
|
|
@{
|
|
double x = 2.7183, y;
|
|
FOOBAR_F77(&x, &y);
|
|
@}
|
|
@end example
|
|
|
|
If the Fortran identifier contains an underscore (e.g., @code{foo_bar}),
|
|
you should use @code{F77_FUNC_}/@code{FC_FUNC_} instead of
|
|
@code{F77_FUNC}/@code{FC_FUNC} (with the same arguments). This is
|
|
because some Fortran compilers mangle names differently if they contain
|
|
an underscore.
|
|
@end defmac
|
|
|
|
@defmac AC_F77_FUNC (@var{name}, @ovar{shellvar})
|
|
@defmacx AC_FC_FUNC (@var{name}, @ovar{shellvar})
|
|
@acindex{F77_FUNC}
|
|
@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
|
|
@code{AC_FC_WRAPPERS}). @var{shellvar} is optional; if it is not
|
|
supplied, the shell variable will be 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++.
|
|
@end defmac
|
|
|
|
@defmac AC_FC_SRCEXT (@var{ext}, @ovar{action-if-success}, @ovar{action-if-failure})
|
|
@acindex{FC_SRCEXT}
|
|
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. On the other hand, some other
|
|
compilers expect all source files to end in @file{.f} and require
|
|
special flags to support other filename extensions. The
|
|
@code{AC_FC_SRCEXT} macro deals with both of these issues.
|
|
|
|
The @code{AC_FC_SRCEXT} tries to get the @code{FC} compiler to accept files
|
|
ending with the extension .@var{ext} (i.e. @var{ext} does @emph{not}
|
|
contain the dot). If any special compiler flags are needed for this, it
|
|
stores them in the output variable @code{FCFLAGS_}@var{ext}. This
|
|
extension and these flags are then used for all subsequent @code{FC} tests
|
|
(until @code{AC_FC_SRCEXT} is called again).
|
|
|
|
For example, you would use @code{AC_FC_SRCEXT(f90)} to employ the
|
|
@file{.f90} extension in future tests, and it would set a
|
|
@code{FCFLAGS_f90} output variable with any extra flags that are needed
|
|
to compile such files.
|
|
|
|
The @code{FCFLAGS_}@var{ext} can @emph{not} be simply absorbed into
|
|
@code{FCFLAGS}, for two reasons based on the limitations of some
|
|
compilers. First, only one @code{FCFLAGS_}@var{ext} can be used at a
|
|
time, so files with different extensions must be compiled separately.
|
|
Second, @code{FCFLAGS_}@var{ext} must appear @emph{immediately} before
|
|
the source-code filename when compiling. So, continuing the example
|
|
above, you might compile a @file{foo.f90} file in your Makefile with the
|
|
command:
|
|
|
|
@example
|
|
foo.o: foo.f90
|
|
$(FC) -c $(FCFLAGS) $(FCFLAGS_f90) foo.f90
|
|
@end example
|
|
|
|
If @code{AC_FC_SRCEXT} succeeds in compiling files with the @var{ext}
|
|
extension, it calls @ovar{action-if-success} (defaults to nothing). If
|
|
it fails, and cannot find a way to make the @code{FC} compiler accept such
|
|
files, it calls @ovar{action-if-failure} (defaults to exiting with an
|
|
error message).
|
|
|
|
@end defmac
|
|
|
|
@defmac AC_FC_FREEFORM (@ovar{action-if-success}, @ovar{action-if-failure})
|
|
@acindex{FC_FREEFORM}
|
|
|
|
The @code{AC_FC_FREEFORM} tries 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
|
|
@file{.f90} or @file{.f95}, then @code{AC_FC_FREEFORM} will ordinarily
|
|
succeed without modifying @code{FCFLAGS}.
|
|
|
|
If @code{AC_FC_FREEFORM} succeeds in compiling free-form source, it
|
|
calls @ovar{action-if-success} (defaults to nothing). If it fails, it
|
|
calls @ovar{action-if-failure} (defaults to exiting with an error
|
|
message).
|
|
@end defmac
|
|
|
|
@node System Services
|
|
@section System Services
|
|
|
|
The following macros check for operating system services or capabilities.
|
|
|
|
@defmac AC_PATH_X
|
|
@acindex{PATH_X}
|
|
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
|
|
@option{--x-libraries=@var{dir}}, use those directories. If either or
|
|
both were not given, get the missing values by running @code{xmkmf} on a
|
|
trivial @file{Imakefile} and examining the @file{Makefile} that it
|
|
produces. If that fails (such as if @code{xmkmf} is not present), look
|
|
for the files in several directories where they often reside. If either
|
|
method is successful, set the shell variables @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
|
|
@option{--without-x}, set the shell variable @code{no_x} to @samp{yes};
|
|
otherwise set it to the empty string.
|
|
@end defmac
|
|
|
|
@defmac AC_PATH_XTRA
|
|
@acindex{PATH_XTRA}
|
|
@ovindex X_CFLAGS
|
|
@ovindex X_LIBS
|
|
@ovindex X_EXTRA_LIBS
|
|
@ovindex X_PRE_LIBS
|
|
@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}.
|
|
|
|
@c This is an incomplete kludge. Make a real way to do it.
|
|
@c If you need to check for other X functions or libraries yourself, then
|
|
@c after calling this macro, add the contents of @code{X_EXTRA_LIBS} to
|
|
@c @code{LIBS} temporarily, like this: (FIXME - add example)
|
|
@end defmac
|
|
|
|
@defmac AC_SYS_INTERPRETER
|
|
@acindex{SYS_INTERPRETER}
|
|
Check whether the system supports starting scripts with a line of the
|
|
form @samp{#! /bin/csh} 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 will be set to @samp{yes}
|
|
if the system supports @samp{#!}, @samp{no} if not.
|
|
@end defmac
|
|
|
|
@defmac AC_SYS_LARGEFILE
|
|
@acindex{SYS_LARGEFILE}
|
|
@cvindex _FILE_OFFSET_BITS
|
|
@cvindex _LARGE_FILES
|
|
@ovindex CC
|
|
Arrange for
|
|
@href{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
|
|
@code{_FILE_OFFSET_BITS} and @code{_LARGE_FILES} if necessary.
|
|
|
|
Large-file support can be disabled by configuring with the
|
|
@option{--disable-largefile} option.
|
|
|
|
If you use this macro, check that your program works even when
|
|
@code{off_t} is longer than @code{long}, 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) 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.
|
|
@end defmac
|
|
|
|
@defmac AC_SYS_LONG_FILE_NAMES
|
|
@acindex{SYS_LONG_FILE_NAMES}
|
|
@cvindex HAVE_LONG_FILE_NAMES
|
|
If the system supports file names longer than 14 characters, define
|
|
@code{HAVE_LONG_FILE_NAMES}.
|
|
@end defmac
|
|
|
|
@defmac AC_SYS_POSIX_TERMIOS
|
|
@acindex{SYS_POSIX_TERMIOS}
|
|
@cindex POSIX termios headers
|
|
@cindex termios POSIX headers
|
|
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
|
|
@samp{yes}. If not, set the variable to @samp{no}.
|
|
@end defmac
|
|
|
|
@node UNIX Variants
|
|
@section UNIX Variants
|
|
|
|
The following macros check for certain operating systems that need
|
|
special treatment for some programs, due to exceptional oddities in
|
|
their header files or libraries. These macros are warts; they will be
|
|
replaced by a more systematic approach, based on the functions they make
|
|
available or the environments they provide.
|
|
|
|
@defmac AC_AIX
|
|
@acindex{AIX}
|
|
@cvindex _ALL_SOURCE
|
|
If on @acronym{AIX}, define @code{_ALL_SOURCE}. Allows the use of some @acronym{BSD}
|
|
functions. Should be called before any macros that run the C compiler.
|
|
@end defmac
|
|
|
|
@defmac AC_GNU_SOURCE
|
|
@acindex{GNU_SOURCE}
|
|
@cvindex _GNU_SOURCE
|
|
If using the @acronym{GNU} C library, define @code{_GNU_SOURCE}.
|
|
Allows the use of some @acronym{GNU} functions. Should be called
|
|
before any macros that run the C compiler.
|
|
@end defmac
|
|
|
|
@defmac AC_ISC_POSIX
|
|
@acindex{ISC_POSIX}
|
|
@ovindex LIBS
|
|
For @sc{interactive unix} (@acronym{ISC}), add @option{-lcposix} to output
|
|
variable @code{LIBS} if necessary for @acronym{POSIX} facilities. Call this
|
|
after @code{AC_PROG_CC} and before any other macros that use @acronym{POSIX}
|
|
interfaces. @sc{interactive unix} is no longer sold, and Sun says that
|
|
they will drop support for it on 2006-07-23, so this macro is becoming
|
|
obsolescent.
|
|
@end defmac
|
|
|
|
@defmac AC_MINIX
|
|
@acindex{MINIX}
|
|
@cvindex _MINIX
|
|
@cvindex _POSIX_SOURCE
|
|
@cvindex _POSIX_1_SOURCE
|
|
If on Minix, define @code{_MINIX} and @code{_POSIX_SOURCE} and define
|
|
@code{_POSIX_1_SOURCE} to be 2. This allows the use of @acronym{POSIX}
|
|
facilities. Should be called before any macros that run the C compiler.
|
|
@end defmac
|
|
|
|
|
|
|
|
|
|
@c ========================================================= Writing Tests
|
|
|
|
@node Writing Tests
|
|
@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.
|
|
@xref{Writing Autoconf Macros}, for how to do that.
|
|
|
|
@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
|
|
* Run Time:: Testing for run-time features
|
|
* Systemology:: A zoology of operating systems
|
|
* Multiple Cases:: Tests for several possible values
|
|
@end menu
|
|
|
|
@node Language Choice
|
|
@section Language Choice
|
|
@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
|
|
@file{configure.ac}.
|
|
|
|
@defmac AC_LANG (@var{language})
|
|
Do compilation tests using the compiler, preprocessor, and file
|
|
extensions for the specified @var{language}.
|
|
|
|
Supported languages are:
|
|
|
|
@table @samp
|
|
@item C
|
|
Do compilation tests using @code{CC} and @code{CPP} and use extension
|
|
@file{.c} for test programs. Use compilation flags: @code{CPPFLAGS} with
|
|
@code{CPP}, and both @code{CPPFLAGS} and @code{CFLAGS} with @code{CC}.
|
|
|
|
@item C++
|
|
Do compilation tests using @code{CXX} and @code{CXXCPP} and use
|
|
extension @file{.C} for test programs. Use compilation flags:
|
|
@code{CPPFLAGS} with @code{CXXPP}, and both @code{CPPFLAGS} and
|
|
@code{CXXFLAGS} with @code{CXX}.
|
|
|
|
@item Fortran 77
|
|
Do compilation tests using @code{F77} and use extension @file{.f} for
|
|
test programs. Use compilation flags: @code{FFLAGS}.
|
|
|
|
@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}.
|
|
@end table
|
|
@end defmac
|
|
|
|
@defmac AC_LANG_PUSH (@var{language})
|
|
@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.
|
|
@end defmac
|
|
|
|
@defmac AC_LANG_POP (@ovar{language})
|
|
@acindex{LANG_POP}
|
|
Select the language that is saved on the top of the stack, as set by
|
|
@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@dots{}), since Autoconf will detect inconsistencies.
|
|
|
|
@example
|
|
AC_LANG_PUSH(Fortran 77)
|
|
# Perform some tests on Fortran 77.
|
|
# @dots{}
|
|
AC_LANG_POP(Fortran 77)
|
|
@end example
|
|
@end defmac
|
|
|
|
@defmac AC_LANG_ASSERT (@var{language})
|
|
@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
|
|
@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
|
|
@code{AC_LANG_PUSH}/@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...
|
|
@end defmac
|
|
|
|
|
|
@defmac AC_REQUIRE_CPP
|
|
@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.
|
|
@end defmac
|
|
|
|
|
|
@node Writing Test Programs
|
|
@section Writing Test Programs
|
|
|
|
Autoconf tests follow is common scheme: feeding some program with some
|
|
input, and most of the time, feeding a compiler with some source file.
|
|
This section is dedicated to these source samples.
|
|
|
|
@menu
|
|
* Guidelines:: General rules for writing test programs
|
|
* Test Functions:: Avoiding pitfalls in test programs
|
|
* Generating Sources:: Source program boilerplate
|
|
@end menu
|
|
|
|
@node Guidelines
|
|
@subsection Guidelines for Test Programs
|
|
|
|
The most important rule to follow when writing testing samples is:
|
|
|
|
@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 if a header is
|
|
functional might let your @command{configure} accept a header which will
|
|
cause some @emph{compiler} error. Do not hesitate checking header with
|
|
other headers included before, especially required headers.
|
|
|
|
Make sure the symbols you use are properly defined, i.e., refrain for
|
|
simply declaring a function yourself instead of including the proper
|
|
header.
|
|
|
|
Test programs should not write anything to the standard output. They
|
|
should return 0 if the test succeeds, nonzero 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. Test programs should @code{exit}, not @code{return}, from
|
|
@code{main}, because on some systems (old Suns, at least) the argument
|
|
to @code{return} in @code{main} is ignored.
|
|
|
|
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_STDC}, then later on in
|
|
@file{configure.ac} you can have a test program that includes an
|
|
@acronym{ANSI} C header file conditionally:
|
|
|
|
@example
|
|
@group
|
|
#if STDC_HEADERS
|
|
# include <stdlib.h>
|
|
#endif
|
|
@end group
|
|
@end example
|
|
|
|
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
|
|
@command{configure} script cleans up by running @samp{rm -rf conftest*}
|
|
after running test programs and if the script is interrupted.
|
|
|
|
@node Test Functions
|
|
@subsection Test Functions
|
|
|
|
Function declarations in test programs should have a prototype
|
|
conditionalized for C++. In practice, though, test programs rarely need
|
|
functions that take arguments.
|
|
|
|
@example
|
|
#ifdef __cplusplus
|
|
foo (int i)
|
|
#else
|
|
foo (i) int i;
|
|
#endif
|
|
@end example
|
|
|
|
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.
|
|
|
|
@example
|
|
#ifdef __cplusplus
|
|
extern "C" void *malloc (size_t);
|
|
#else
|
|
void *malloc ();
|
|
#endif
|
|
@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
|
|
@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}).
|
|
|
|
|
|
@node Generating Sources
|
|
@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.
|
|
|
|
|
|
@defmac AC_LANG_CONFTEST (@var{source})
|
|
@acindex{LANG_CONFTEST}
|
|
Save the @var{source} text in the current test source file:
|
|
@file{conftest.@var{extension}} where the @var{extension} depends on the
|
|
current language.
|
|
|
|
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.
|
|
@end defmac
|
|
|
|
@defmac AC_LANG_SOURCE (@var{source})
|
|
@acindex{LANG_SOURCE}
|
|
Expands into the @var{source}, with the definition of
|
|
all the @code{AC_DEFINE} performed so far.
|
|
@end defmac
|
|
|
|
For instance executing (observe the double quotation!):
|
|
|
|
@example
|
|
AC_INIT(Autoconf Documentation, @value{VERSION}, bug-autoconf@@gnu.org)
|
|
AC_DEFINE([HELLO_WORLD], ["Hello, World\n"])
|
|
AC_LANG_CONFTEST(
|
|
[AC_LANG_SOURCE([[const char hw[] = "Hello, World\n";]])])
|
|
gcc -E -dD conftest.c -o -
|
|
@end example
|
|
|
|
@noindent
|
|
results in:
|
|
|
|
@example
|
|
# 1 "conftest.c"
|
|
# 1169 "configure"
|
|
|
|
# 1 "confdefs.h" 1
|
|
|
|
#define PACKAGE_NAME "Autoconf Documentation"
|
|
#define PACKAGE_TARNAME "autoconf-documentation"
|
|
#define PACKAGE_VERSION "@value{VERSION}"
|
|
#define PACKAGE_STRING "Autoconf Documentation @value{VERSION}"
|
|
#define PACKAGE_BUGREPORT "bug-autoconf@@gnu.org"
|
|
#define HELLO_WORLD "Hello, World\n"
|
|
# 1170 "configure" 2
|
|
|
|
const char hw[] = "Hello, World\n";
|
|
@end example
|
|
|
|
@defmac AC_LANG_PROGRAM (@var{prologue}, @var{body})
|
|
@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 feature of the latter are
|
|
available.
|
|
@end defmac
|
|
|
|
For instance:
|
|
|
|
@example
|
|
AC_INIT(Autoconf Documentation, @value{VERSION}, bug-autoconf@@gnu.org)
|
|
AC_DEFINE([HELLO_WORLD], ["Hello, World\n"])
|
|
AC_LANG_CONFTEST(
|
|
[AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
|
|
[[fputs (hw, stdout);]])])
|
|
gcc -E -dD conftest.c -o -
|
|
@end example
|
|
|
|
@noindent
|
|
results in:
|
|
|
|
@example
|
|
# 1 "conftest.c"
|
|
# 1169 "configure"
|
|
|
|
# 1 "confdefs.h" 1
|
|
|
|
#define PACKAGE_NAME "Autoconf Documentation"
|
|
#define PACKAGE_TARNAME "autoconf-documentation"
|
|
#define PACKAGE_VERSION "@value{VERSION}"
|
|
#define PACKAGE_STRING "Autoconf Documentation @value{VERSION}"
|
|
#define PACKAGE_BUGREPORT "bug-autoconf@@gnu.org"
|
|
#define HELLO_WORLD "Hello, World\n"
|
|
# 1170 "configure" 2
|
|
|
|
const char hw[] = "Hello, World\n";
|
|
int
|
|
main ()
|
|
@{
|
|
fputs (hw, stdout);
|
|
;
|
|
return 0;
|
|
@}
|
|
@end example
|
|
|
|
|
|
@defmac AC_LANG_CALL (@var{prologue}, @var{function})
|
|
@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.,
|
|
@code{main} in C). Since it uses @code{AC_LANG_PROGRAMS}, 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.
|
|
@end defmac
|
|
|
|
|
|
@defmac AC_LANG_FUNC_LINK_TRY (@var{function})
|
|
@acindex{LANG_FUNC_LINK_TRY}
|
|
Expands into a source file which consists of a pseudo use of the
|
|
@var{function} as body of the main function (e.g., @code{main} in C): a
|
|
simple (function pointer) assignment. Since it uses
|
|
@code{AC_LANG_PROGRAMS}, the feature 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).
|
|
@end defmac
|
|
|
|
@node Running the Preprocessor
|
|
@section Running the Preprocessor
|
|
|
|
Sometimes one might need to run the preprocessor on some source file.
|
|
@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 to the
|
|
temptation of following the easiest path.
|
|
|
|
Nevertheless, if you need to run the preprocessor, then use
|
|
@code{AC_PREPROC_IFELSE}.
|
|
|
|
@defmac AC_PREPROC_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
|
|
@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
|
|
@option{-g}, @option{-O}, etc.@: are not valid options to many C
|
|
preprocessors.
|
|
|
|
It is customary to report unexpected failures with
|
|
@code{AC_MSG_FAILURE}.
|
|
@end defmac
|
|
|
|
For instance:
|
|
|
|
@example
|
|
AC_INIT(Autoconf Documentation, @value{VERSION}, bug-autoconf@@gnu.org)
|
|
AC_DEFINE([HELLO_WORLD], ["Hello, World\n"])
|
|
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])])
|
|
@end example
|
|
|
|
@noindent
|
|
results in:
|
|
|
|
@example
|
|
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 how to run the C preprocessor... gcc -E
|
|
OK
|
|
@end example
|
|
|
|
@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
|
|
@code{AC_PREPROC_IFELSE}, but, in the first place, are you sure you need
|
|
to run the @emph{preprocessor} and not the compiler?
|
|
|
|
@defmac AC_EGREP_HEADER (@var{pattern}, @var{header-file}, @var{action-if-found}, @ovar{action-if-not-found})
|
|
@acindex{EGREP_HEADER}
|
|
If the output of running the preprocessor on the system header file
|
|
@var{header-file} matches the extended regular expression
|
|
@var{pattern}, execute shell commands @var{action-if-found}, otherwise
|
|
execute @var{action-if-not-found}.
|
|
@end defmac
|
|
|
|
@defmac AC_EGREP_CPP (@var{pattern}, @var{program}, @ovar{action-if-found}, @ovar{action-if-not-found})
|
|
@acindex{EGREP_CPP}
|
|
@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
|
|
@var{action-if-found}, otherwise execute @var{action-if-not-found}.
|
|
@end defmac
|
|
|
|
|
|
|
|
@node Running the Compiler
|
|
@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.
|
|
|
|
@defmac AC_COMPILE_IFELSE (@var{input}, @ovar{action-if-found}, @ovar{action-if-not-found})
|
|
@acindex{COMPILE_IFELSE}
|
|
Run the compiler and compilation flags 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.
|
|
|
|
It is customary to report unexpected failures with
|
|
@code{AC_MSG_FAILURE}. This macro does not try to link; use
|
|
@code{AC_LINK_IFELSE} if you need to do that (@pxref{Running the
|
|
Linker}).
|
|
@end defmac
|
|
|
|
@node Running the Linker
|
|
@section Running the Linker
|
|
|
|
To check for a library, a function, or a global variable, Autoconf
|
|
@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
|
|
@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 run-time behavior if needed. On the other hand,
|
|
it can be slower than scanning the libraries once, but accuracy is more
|
|
important than speed.
|
|
|
|
@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.
|
|
|
|
|
|
@defmac AC_LINK_IFELSE (@var{input}, @ovar{action-if-found}, @ovar{action-if-not-found})
|
|
@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.
|
|
|
|
@code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
|
|
current compilation flags.
|
|
|
|
It is customary to report unexpected failures with
|
|
@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{Run Time}).
|
|
@end defmac
|
|
|
|
|
|
|
|
@node Run Time
|
|
@section Checking Run Time Behavior
|
|
|
|
Sometimes you need to find out how a system performs at run time, 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 run-time 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.
|
|
|
|
@defmac AC_RUN_IFELSE (@var{input}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{action-if-cross-compiling})
|
|
@acindex{RUN_IFELSE}
|
|
If @var{program} compiles and links successfully and 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.
|
|
@code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
|
|
compilation flags of the current language (@pxref{Language Choice}).
|
|
|
|
If the compiler being used does not produce executables that run on the
|
|
system where @command{configure} is being run, then the test program is
|
|
not run. If the optional shell commands @var{action-if-cross-compiling}
|
|
are given, they are run instead. Otherwise, @command{configure} prints
|
|
an error message and exits.
|
|
|
|
In the @var{action-if-false} section, the exit status of the program is
|
|
available in the shell variable @samp{$?}, but be very careful to limit
|
|
yourself to positive values smaller than 127; bigger values should be
|
|
saved into a file by the @var{program}. Note also that you have simply
|
|
no guarantee that this exit status is issued by the @var{program}, or by
|
|
the failure of its compilation. In other words, use this feature if
|
|
sadist only, it was reestablished because the Autoconf maintainers grew
|
|
tired of receiving ``bug reports''.
|
|
|
|
It is customary to report unexpected failures with
|
|
@code{AC_MSG_FAILURE}.
|
|
@end defmac
|
|
|
|
Try to provide a pessimistic default value to use when cross-compiling
|
|
makes run-time tests impossible. You do this by passing the optional
|
|
last argument to @code{AC_RUN_IFELSE}. @command{autoconf} prints a
|
|
warning message when creating @command{configure} each time it
|
|
encounters a call to @code{AC_RUN_IFELSE} with no
|
|
@var{action-if-cross-compiling} argument given. You may ignore the
|
|
warning, though users will not be able to configure your package for
|
|
cross-compiling. A few of the macros distributed with Autoconf produce
|
|
this warning message.
|
|
|
|
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}).
|
|
|
|
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
|
|
@samp{yes}, and then use an alternate method to get the results instead
|
|
of calling the macros.
|
|
|
|
|
|
@node Systemology
|
|
@section Systemology
|
|
|
|
This section aims at presenting some systems and pointers to
|
|
documentation. It may help you addressing particular problems reported
|
|
by users.
|
|
|
|
The @href{http://bhami.com/rosetta.html, Rosetta Stone for Unix}
|
|
contains a lot of interesting crossed information on various Unices.
|
|
|
|
@table @asis
|
|
@item Darwin
|
|
@cindex Darwin
|
|
Darwin is also known as Mac OS X@. 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
|
|
@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@. We may want to rebuild
|
|
Darwin to have both UFS and HFS+ available (and put the /local/build
|
|
tree on the UFS).
|
|
|
|
@item @acronym{QNX} 4.25
|
|
@cindex @acronym{QNX} 4.25
|
|
@c FIXME: Please, if you feel like writing something more precise,
|
|
@c it'd be great. In particular, I can't understand the difference with
|
|
@c QNX Neutrino.
|
|
@acronym{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 @acronym{POSIX} certified. More
|
|
information is available on the @href{www.qnx.com, @acronym{QNX} home page},
|
|
including the @href{http://support.qnx.com/support/docs/qnx4/, @acronym{QNX}
|
|
man pages}.
|
|
|
|
@item Tru64
|
|
@cindex Tru64
|
|
The @href{http://www.tru64unix.compaq.com/docs/base_doc/DOCUMENTATION/,
|
|
documentation of several versions of Tru64} is available in different
|
|
formats.
|
|
|
|
@item Unix version 7
|
|
@cindex Unix version 7
|
|
@cindex V7
|
|
Documentation is available in the
|
|
@href{http://plan9.bell-labs.com/7thEdMan/index.html, V7 Manual}.
|
|
@end table
|
|
|
|
|
|
@node Multiple Cases
|
|
@section Multiple Cases
|
|
|
|
Some operations are accomplished in several possible ways, depending on
|
|
the @sc{unix} 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.
|
|
|
|
@example
|
|
@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) 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) 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) fstype=AIX])
|
|
fi
|
|
# (more cases omitted here)
|
|
AC_MSG_RESULT([$fstype])
|
|
@end group
|
|
@end example
|
|
|
|
@c ====================================================== Results of Tests.
|
|
|
|
@node Results
|
|
@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.
|
|
|
|
@menu
|
|
* Defining Symbols:: Defining C preprocessor symbols
|
|
* Setting Output Variables:: Replacing variables in output files
|
|
* Caching Results:: Speeding up subsequent @command{configure} runs
|
|
* Printing Messages:: Notifying @command{configure} users
|
|
@end menu
|
|
|
|
@node Defining Symbols
|
|
@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
|
|
@option{-D@var{symbol}=@var{value}} for each symbol defined. Unlike in
|
|
Autoconf version 1, there is no variable @code{DEFS} defined while
|
|
@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:
|
|
|
|
@example
|
|
AC_CHECK_FUNC(vprintf, [AC_DEFINE(HAVE_VPRINTF)])
|
|
if test "$ac_cv_func_vprintf" != yes; then
|
|
AC_CHECK_FUNC(_doprnt, [AC_DEFINE(HAVE_DOPRNT)])
|
|
fi
|
|
@end example
|
|
|
|
If @code{AC_CONFIG_HEADERS} has been called, then instead of creating
|
|
@code{DEFS}, @code{AC_OUTPUT} creates a header file by substituting the
|
|
correct values into @code{#define} statements in a template file.
|
|
@xref{Configuration Headers}, for more information about this kind of
|
|
output.
|
|
|
|
@defmac AC_DEFINE (@var{variable}, @var{value}, @ovar{description})
|
|
@defmacx AC_DEFINE (@var{variable})
|
|
@acindex{DEFINE}
|
|
Define the C preprocessor variable @var{variable} to @var{value} (verbatim).
|
|
@var{value} should not contain literal newlines, and if you are not
|
|
using @code{AC_CONFIG_HEADERS} it should not contain any @samp{#}
|
|
characters, as @command{make} tends to eat them. To use a shell variable
|
|
(which you need to do in order to define a value containing the M4 quote
|
|
characters @samp{[} or @samp{]}), use @code{AC_DEFINE_UNQUOTED} instead.
|
|
@var{description} is only useful if you are using
|
|
@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
|
|
@code{EQUATION} to be the string constant @samp{"$a > $b"}:
|
|
|
|
@example
|
|
AC_DEFINE(EQUATION, "$a > $b")
|
|
@end example
|
|
|
|
If neither @var{value} nor @var{description} are given, then
|
|
@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.
|
|
@end defmac
|
|
|
|
@defmac AC_DEFINE_UNQUOTED (@var{variable}, @var{value}, @ovar{description})
|
|
@defmacx AC_DEFINE_UNQUOTED (@var{variable})
|
|
@acindex{DEFINE_UNQUOTED}
|
|
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{\}). Single and double quote characters in the value have no
|
|
special meaning. Use this macro instead of @code{AC_DEFINE} when
|
|
@var{variable} or @var{value} is a shell variable. Examples:
|
|
|
|
@example
|
|
AC_DEFINE_UNQUOTED(config_machfile, "$machfile")
|
|
AC_DEFINE_UNQUOTED(GETGROUPS_T, $ac_cv_type_getgroups)
|
|
AC_DEFINE_UNQUOTED($ac_tr_hdr)
|
|
@end example
|
|
@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 spaces or
|
|
newlines. That is, do this:
|
|
|
|
@example
|
|
AC_CHECK_HEADER(elf.h, [AC_DEFINE(SVR4) LIBS="$LIBS -lelf"])
|
|
@end example
|
|
|
|
@noindent
|
|
or this:
|
|
|
|
@example
|
|
AC_CHECK_HEADER(elf.h,
|
|
[AC_DEFINE(SVR4)
|
|
LIBS="$LIBS -lelf"])
|
|
@end example
|
|
|
|
@noindent
|
|
instead of this:
|
|
|
|
@example
|
|
AC_CHECK_HEADER(elf.h, [AC_DEFINE(SVR4); LIBS="$LIBS -lelf"])
|
|
@end example
|
|
|
|
@node Setting Output Variables
|
|
@section Setting 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.
|
|
|
|
@defmac AC_SUBST (@var{variable}, @ovar{value})
|
|
@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 @file{Makefile}s). This means that @code{AC_OUTPUT} will
|
|
replace instances of @samp{@@@var{variable}@@} in input files with the
|
|
value that the shell variable @var{variable} has when @code{AC_OUTPUT}
|
|
is called. This value of @var{variable} should not contain literal
|
|
newlines.
|
|
|
|
If @var{value} is given, in addition assign it to @var{variable}.
|
|
@end defmac
|
|
|
|
@defmac AC_SUBST_FILE (@var{variable})
|
|
@acindex{SUBST_FILE}
|
|
Another way to create an output variable from a shell variable. Make
|
|
@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} will replace instances of
|
|
@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
|
|
@file{/dev/null} for cases that do not have a file to insert.
|
|
|
|
This macro is useful for inserting @file{Makefile} fragments containing
|
|
special dependencies or other @code{make} directives for particular host
|
|
or target types into @file{Makefile}s. For example, @file{configure.ac}
|
|
could contain:
|
|
|
|
@example
|
|
AC_SUBST_FILE(host_frag)
|
|
host_frag=$srcdir/conf/sun4.mh
|
|
@end example
|
|
|
|
@noindent
|
|
and then a @file{Makefile.in} could contain:
|
|
|
|
@example
|
|
@@host_frag@@
|
|
@end example
|
|
@end defmac
|
|
|
|
@cindex Previous Variable
|
|
@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 will 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}.
|
|
|
|
@defmac AC_ARG_VAR (@var{variable}, @var{description})
|
|
@acindex{ARG_VAR}
|
|
Declare @var{variable} is a precious variable, and include its
|
|
@var{description} in the variable section of @samp{./configure --help}.
|
|
|
|
Being precious means that
|
|
@itemize @minus
|
|
@item
|
|
@var{variable} is @code{AC_SUBST}'d.
|
|
|
|
@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
|
|
@samp{./configure} guess that @code{FOO} is @code{foo} can be two very
|
|
different runs.
|
|
|
|
@item
|
|
@var{variable} is checked for consistency between two
|
|
@command{configure} runs. For instance:
|
|
|
|
@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
|
|
@end example
|
|
|
|
@noindent
|
|
and similarly if the variable is unset, or if its content is changed.
|
|
|
|
|
|
@item
|
|
@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:
|
|
|
|
@example
|
|
$ @kbd{CC=/usr/bin/cc ./configure undeclared_var=raboof --silent}
|
|
$ @kbd{./config.status --recheck}
|
|
running /bin/sh ./configure undeclared_var=raboof --silent \
|
|
CC=/usr/bin/cc --no-create --no-recursion
|
|
@end example
|
|
@end itemize
|
|
@end defmac
|
|
|
|
|
|
@node Caching Results
|
|
@section Caching Results
|
|
@cindex Cache
|
|
|
|
To avoid checking for the same features repeatedly in various
|
|
@command{configure} scripts (or in repeated runs of one script),
|
|
@command{configure} can optionally save the results of many checks in a
|
|
@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.
|
|
|
|
@defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it})
|
|
@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
|
|
@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 will be
|
|
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
|
|
@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.
|
|
@end defmac
|
|
|
|
@defmac AC_CACHE_CHECK (@var{message}, @var{cache-id}, @var{commands-to-set-it})
|
|
@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
|
|
@var{message}, then @code{AC_CACHE_VAL} with the @var{cache-id} and
|
|
@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.
|
|
@end defmac
|
|
|
|
It is very common to find buggy macros using @code{AC_CACHE_VAL} or
|
|
@code{AC_CACHE_CHECK}, because people are tempted to call
|
|
@code{AC_DEFINE} in the @var{commands-to-set-it}. Instead, the code that
|
|
@emph{follows} the call to @code{AC_CACHE_VAL} should call
|
|
@code{AC_DEFINE}, by examining the value of the cache variable. For
|
|
instance, the following macro is broken:
|
|
|
|
@example
|
|
@group
|
|
AC_DEFUN([AC_SHELL_TRUE],
|
|
[AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
|
|
[ac_cv_shell_true_works=no
|
|
true && ac_cv_shell_true_works=yes
|
|
if test $ac_cv_shell_true_works = yes; then
|
|
AC_DEFINE([TRUE_WORKS], 1
|
|
[Define if `true(1)' works properly.])
|
|
fi])
|
|
])
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
This fails if the cache is enabled: the second time this macro is run,
|
|
@code{TRUE_WORKS} @emph{will not be defined}. The proper implementation
|
|
is:
|
|
|
|
@example
|
|
@group
|
|
AC_DEFUN([AC_SHELL_TRUE],
|
|
[AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
|
|
[ac_cv_shell_true_works=no
|
|
true && ac_cv_shell_true_works=yes])
|
|
if test $ac_cv_shell_true_works = yes; then
|
|
AC_DEFINE([TRUE_WORKS], 1
|
|
[Define if `true(1)' works properly.])
|
|
fi
|
|
])
|
|
@end group
|
|
@end example
|
|
|
|
Also, @var{commands-to-set-it} should not print any messages, for
|
|
example with @code{AC_MSG_CHECKING}; do that before calling
|
|
@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.
|
|
|
|
@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
|
|
@end menu
|
|
|
|
@node Cache Variable Names
|
|
@subsection Cache Variable Names
|
|
@cindex Cache variable
|
|
|
|
The names of cache variables should have the following format:
|
|
|
|
@example
|
|
@var{package-prefix}_cv_@var{value-type}_@var{specific-value}_@ovar{additional-options}
|
|
@end example
|
|
|
|
@noindent
|
|
for example, @samp{ac_cv_header_stat_broken} or
|
|
@samp{ac_cv_prog_gcc_traditional}. The parts of the variable name are:
|
|
|
|
@table @asis
|
|
@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
|
|
@samp{ac}.
|
|
|
|
@item @code{_cv_}
|
|
Indicates that this shell variable is a cache value. This string
|
|
@emph{must} be present in the variable name, including the leading
|
|
underscore.
|
|
|
|
@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}.
|
|
|
|
@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}).
|
|
|
|
@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.
|
|
@end table
|
|
|
|
The values assigned to cache variables may not contain newlines.
|
|
Usually, their values will be Boolean (@samp{yes} or @samp{no}) or the
|
|
names of files or functions; so this is not an important restriction.
|
|
|
|
@node Cache Files
|
|
@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.
|
|
|
|
By default, @command{configure} uses no cache file (technically, it uses
|
|
@option{--cache-file=/dev/null}), to avoid problems caused by accidental
|
|
use of stale cache files.
|
|
|
|
To enable caching, @command{configure} accepts @option{--config-cache} (or
|
|
@option{-C}) to cache results in the file @file{config.cache}.
|
|
Alternatively, @option{--cache-file=@var{file}} specifies that
|
|
@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.
|
|
|
|
@file{config.status} only pays attention to the cache file if it is
|
|
given the @option{--recheck} option, which makes it rerun
|
|
@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 will gradually accumulate information whenever someone runs a new
|
|
@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.
|
|
|
|
@node Cache Checkpointing
|
|
@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 will
|
|
reduce the amount of time it takes to re-run the configure script with
|
|
(hopefully) the error that caused the previous abort corrected.
|
|
|
|
@c FIXME: Do we really want to document this guy?
|
|
@defmac AC_CACHE_LOAD
|
|
@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}.
|
|
@end defmac
|
|
|
|
@defmac AC_CACHE_SAVE
|
|
@acindex{CACHE_SAVE}
|
|
Flushes all cached values to the cache file. Called automatically from
|
|
@code{AC_OUTPUT}, but it can be quite useful to call
|
|
@code{AC_CACHE_SAVE} at key points in @file{configure.ac}.
|
|
@end defmac
|
|
|
|
For instance:
|
|
|
|
@example
|
|
@r{ @dots{} AC_INIT, etc. @dots{}}
|
|
@group
|
|
# Checks for programs.
|
|
AC_PROG_CC
|
|
AC_PROG_GCC_TRADITIONAL
|
|
@r{ @dots{} more program checks @dots{}}
|
|
AC_CACHE_SAVE
|
|
@end group
|
|
|
|
@group
|
|
# Checks for libraries.
|
|
AC_CHECK_LIB(nsl, gethostbyname)
|
|
AC_CHECK_LIB(socket, connect)
|
|
@r{ @dots{} more lib checks @dots{}}
|
|
AC_CACHE_SAVE
|
|
@end group
|
|
|
|
@group
|
|
# Might abort@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])])
|
|
@end group
|
|
@r{ @dots{} AC_OUTPUT, etc. @dots{}}
|
|
@end example
|
|
|
|
@node Printing Messages
|
|
@section Printing Messages
|
|
@cindex Messages, from @command{configure}
|
|
|
|
@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 @code{echo} shell command.
|
|
@command{configure} scripts should rarely need to run @code{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 of the callers will change
|
|
automatically.
|
|
|
|
To diagnose static issues, i.e., when @command{autoconf} is run, see
|
|
@ref{Reporting Messages}.
|
|
|
|
@defmac AC_MSG_CHECKING (@var{feature-description})
|
|
@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
|
|
@samp{whether the Fortran compiler accepts C++ comments} or @samp{for
|
|
c89}.
|
|
|
|
This macro prints nothing if @command{configure} is run with the
|
|
@option{--quiet} or @option{--silent} option.
|
|
@end defmac
|
|
|
|
@defmac AC_MSG_RESULT (@var{result-description})
|
|
@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
|
|
@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
|
|
@code{AC_MSG_CHECKING}.
|
|
|
|
This macro prints nothing if @command{configure} is run with the
|
|
@option{--quiet} or @option{--silent} option.
|
|
@end defmac
|
|
|
|
@defmac AC_MSG_NOTICE (@var{message})
|
|
@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.,
|
|
|
|
@example
|
|
AC_MSG_NOTICE([checking if stack overflow is detectable])
|
|
@end example
|
|
|
|
This macro prints nothing if @command{configure} is run with the
|
|
@option{--quiet} or @option{--silent} option.
|
|
@end defmac
|
|
|
|
@defmac AC_MSG_ERROR (@var{error-description}, @ovar{exit-status})
|
|
@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} (1 by default).
|
|
@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''.
|
|
@end defmac
|
|
|
|
@defmac AC_MSG_FAILURE (@var{error-description}, @ovar{exit-status})
|
|
@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.
|
|
@end defmac
|
|
|
|
@defmac AC_MSG_WARN (@var{problem-description})
|
|
@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.
|
|
@var{problem-description} should be something like @samp{ln -s seems to
|
|
make hard links}.
|
|
@end defmac
|
|
|
|
|
|
|
|
@c ====================================================== Programming in M4.
|
|
|
|
@node Programming in M4
|
|
@chapter Programming in 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 are still experimental,
|
|
and their interface might change in the future. As a matter of fact,
|
|
@emph{anything that is not documented must not be used}.
|
|
|
|
@menu
|
|
* M4 Quotation:: Protecting macros from unwanted expansion
|
|
* Using autom4te:: The Autoconf executables backbone
|
|
* Programming in M4sugar:: Convenient pure M4 macros
|
|
* Programming in M4sh:: Common shell Constructs
|
|
@end menu
|
|
|
|
@node M4 Quotation
|
|
@section M4 Quotation
|
|
@cindex quotation
|
|
|
|
@c FIXME: Grmph, yet another quoting myth: quotation has *never*
|
|
@c prevented `expansion' of $1. Unless it refers to the expansion
|
|
@c of the value of $1? Anyway, we need a rewrite here@enddots{}
|
|
|
|
The most common problem with existing macros is an improper quotation.
|
|
This section, which users of Autoconf can skip, but which macro writers
|
|
@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.
|
|
|
|
@menu
|
|
* Active Characters:: Characters that change the behavior of M4
|
|
* One Macro Call:: Quotation and one macro call
|
|
* Quotation and Nested Macros:: Macros calling macros
|
|
* Changequote is Evil:: Worse than INTERCAL: M4 + changequote
|
|
* Quadrigraphs:: Another way to escape special characters
|
|
* Quotation Rule Of Thumb:: One parenthesis, one quote
|
|
@end menu
|
|
|
|
@node Active Characters
|
|
@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,
|
|
and finally @samp{(} and @samp{)} (which M4 tries to match by
|
|
pairs).
|
|
|
|
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:
|
|
|
|
@example
|
|
# define([def], ine)
|
|
@result{}# define([def], ine)
|
|
@end example
|
|
|
|
Each time there can be a macro expansion, there is a quotation
|
|
expansion, i.e., one level of quotes is stripped:
|
|
|
|
@example
|
|
int tab[10];
|
|
@result{}int tab10;
|
|
[int tab[10];]
|
|
@result{}int tab[10];
|
|
@end example
|
|
|
|
Without this in mind, the reader will try hopelessly to use her macro
|
|
@code{array}:
|
|
|
|
@example
|
|
define([array], [int tab[10];])
|
|
array
|
|
@result{}int tab10;
|
|
[array]
|
|
@result{}array
|
|
@end example
|
|
|
|
@noindent
|
|
How can you correctly output the intended results@footnote{Using
|
|
@code{defn}.}?
|
|
|
|
|
|
@node One Macro Call
|
|
@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:
|
|
|
|
@example
|
|
define([car], [$1])
|
|
@end example
|
|
|
|
@noindent
|
|
The two pairs of quotes above are not part of the arguments of
|
|
@code{define}; rather, they are understood by the top level when it
|
|
tries to find the arguments of @code{define}. Therefore, it is
|
|
equivalent to write:
|
|
|
|
@example
|
|
define(car, $1)
|
|
@end example
|
|
|
|
@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:
|
|
|
|
@example
|
|
car(foo, bar, baz)
|
|
@result{}foo
|
|
[car(foo, bar, baz)]
|
|
@result{}car(foo, bar, baz)
|
|
@end example
|
|
|
|
Let's pay attention to the special characters:
|
|
|
|
@example
|
|
car(#)
|
|
@error{}EOF in argument list
|
|
@end example
|
|
|
|
The closing parenthesis is hidden in the comment; with a hypothetical
|
|
quoting, the top level understood it this way:
|
|
|
|
@example
|
|
car([#)]
|
|
@end example
|
|
|
|
@noindent
|
|
Proper quotation, of course, fixes the problem:
|
|
|
|
@example
|
|
car([#])
|
|
@result{}#
|
|
@end example
|
|
|
|
The reader will easily understand the following examples:
|
|
|
|
@example
|
|
car(foo, bar)
|
|
@result{}foo
|
|
car([foo, bar])
|
|
@result{}foo, bar
|
|
car((foo, bar))
|
|
@result{}(foo, bar)
|
|
car([(foo], [bar)])
|
|
@result{}(foo
|
|
car([], [])
|
|
@result{}
|
|
car([[]], [[]])
|
|
@result{}[]
|
|
@end example
|
|
|
|
With this in mind, we can explore the cases where macros invoke
|
|
macros@enddots{}
|
|
|
|
|
|
@node Quotation and Nested Macros
|
|
@subsection Quotation and Nested Macros
|
|
|
|
The examples below use the following macros:
|
|
|
|
@example
|
|
define([car], [$1])
|
|
define([active], [ACT, IVE])
|
|
define([array], [int tab[10]])
|
|
@end example
|
|
|
|
Each additional embedded macro call introduces other possible
|
|
interesting quotations:
|
|
|
|
@example
|
|
car(active)
|
|
@result{}ACT
|
|
car([active])
|
|
@result{}ACT, IVE
|
|
car([[active]])
|
|
@result{}active
|
|
@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:
|
|
|
|
@example
|
|
car(ACT, IVE)
|
|
@result{}ACT
|
|
@end example
|
|
|
|
@noindent
|
|
In the second case, the top level gives @samp{active} as first and only
|
|
argument of @code{car}, which results in:
|
|
|
|
@example
|
|
active
|
|
@result{}ACT, IVE
|
|
@end example
|
|
|
|
@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:
|
|
|
|
@example
|
|
[active]
|
|
@result{}active
|
|
@end example
|
|
|
|
@noindent
|
|
exactly as we already saw above.
|
|
|
|
The example above, applied to a more realistic example, gives:
|
|
|
|
@example
|
|
car(int tab[10];)
|
|
@result{}int tab10;
|
|
car([int tab[10];])
|
|
@result{}int tab10;
|
|
car([[int tab[10];]])
|
|
@result{}int tab[10];
|
|
@end example
|
|
|
|
@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
|
|
@code{car}, so you ``fix'' your macro. Let's call it @code{qar} for
|
|
quoted car:
|
|
|
|
@example
|
|
define([qar], [[$1]])
|
|
@end example
|
|
|
|
@noindent
|
|
and check that @code{qar} is properly fixed:
|
|
|
|
@example
|
|
qar([int tab[10];])
|
|
@result{}int tab[10];
|
|
@end example
|
|
|
|
@noindent
|
|
Ahhh! That's much better.
|
|
|
|
But note what you've done: now that the arguments are literal strings,
|
|
if the user wants to use the results of expansions as arguments, she has
|
|
to use an @emph{unquoted} macro call:
|
|
|
|
@example
|
|
qar(active)
|
|
@result{}ACT
|
|
@end example
|
|
|
|
@noindent
|
|
where she wanted to reproduce what she used to do with @code{car}:
|
|
|
|
@example
|
|
car([active])
|
|
@result{}ACT, IVE
|
|
@end example
|
|
|
|
@noindent
|
|
Worse yet: she wants to use a macro that produces a set of @code{cpp}
|
|
macros:
|
|
|
|
@example
|
|
define([my_includes], [#include <stdio.h>])
|
|
car([my_includes])
|
|
@result{}#include <stdio.h>
|
|
qar(my_includes)
|
|
@error{}EOF in argument list
|
|
@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.
|
|
|
|
@node Changequote is Evil
|
|
@subsection @code{changequote} is Evil
|
|
|
|
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
|
|
@samp{'this'} and @samp{`that`}), because of literal characters in usual
|
|
programming languages (as in @samp{'0'}), there are many unbalanced
|
|
@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
|
|
@samp{changecom(<!--, -->)} when M4 is used to produce HTML pages),
|
|
@code{changeword} and @code{changesyntax} to change other syntactic
|
|
details (such as the character to denote the n-th argument, @samp{$} by
|
|
default, the parenthesis around arguments etc.).
|
|
|
|
These primitives are really meant to make M4 more useful for specific
|
|
domains: they should be considered like command line options:
|
|
@option{--quotes}, @option{--comments}, @option{--words}, and
|
|
@code{--syntax}. Nevertheless, they are implemented as M4 builtins, as
|
|
it makes M4 libraries self contained (no need for additional options).
|
|
|
|
There lies the problem@enddots{}
|
|
|
|
@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 will be lost, as the current syntax will probably not be
|
|
the one they were implemented with.
|
|
|
|
@c FIXME: I've been looking for a short, real case example, but I
|
|
@c lost them all :(
|
|
|
|
|
|
@node Quadrigraphs
|
|
@subsection Quadrigraphs
|
|
@cindex quadrigraphs
|
|
@cindex @samp{@@S|@@}
|
|
@cindex @samp{@@&t@@}
|
|
@c Info cannot handle `:' in index entries.
|
|
@c @cindex @samp{@@<:@@}
|
|
@c @cindex @samp{@@:>@@}
|
|
@c @cindex @samp{@@%:@@}
|
|
|
|
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.
|
|
|
|
You can work around this problem by using one of the following
|
|
@dfn{quadrigraphs}:
|
|
|
|
@table @samp
|
|
@item @@<:@@
|
|
@samp{[}
|
|
@item @@:>@@
|
|
@samp{]}
|
|
@item @@S|@@
|
|
@samp{$}
|
|
@item @@%:@@
|
|
@samp{#}
|
|
@item @@&t@@
|
|
Expands to nothing.
|
|
@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,
|
|
will appear as @samp{^[} in the output.
|
|
|
|
The empty quadrigraph can be used:
|
|
|
|
@itemize @minus
|
|
@item to mark trailing spaces explicitly
|
|
|
|
Trailing spaces are smashed by @command{autom4te}. This is a feature.
|
|
|
|
@item to produce other quadrigraphs
|
|
|
|
For instance @samp{@@<@@&t@@:@@} produces @samp{@@<:@@}.
|
|
|
|
@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} will still catch unexpanded
|
|
@samp{AC_*}. Then write @samp{AC@@&t@@_FOO}.
|
|
@end itemize
|
|
|
|
The name @samp{@@&t@@} was suggested by Paul Eggert:
|
|
|
|
@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
|
|
@sc{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:
|
|
|
|
@example
|
|
char const mt[] = "";
|
|
@end example
|
|
|
|
@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.
|
|
@end quotation
|
|
|
|
@node Quotation Rule Of Thumb
|
|
@subsection Quotation Rule Of Thumb
|
|
|
|
To conclude, the quotation rule of thumb is:
|
|
|
|
@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
|
|
@emph{the arguments}!
|
|
|
|
It is common to read Autoconf programs with snippets like:
|
|
|
|
@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)
|
|
@end example
|
|
|
|
@noindent
|
|
which is incredibly useless since @code{AC_TRY_LINK} is @emph{already}
|
|
double quoting, so you just need:
|
|
|
|
@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])
|
|
@end example
|
|
|
|
@noindent
|
|
The M4-fluent reader will 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:
|
|
|
|
@example
|
|
changequote(<<, >>)dnl
|
|
<<[]>>
|
|
changequote([, ])dnl
|
|
@end example
|
|
|
|
@noindent
|
|
instead of simply:
|
|
|
|
@example
|
|
[[]]
|
|
@end example
|
|
|
|
|
|
With macros that do not double quote their arguments (which is the
|
|
rule), double-quote the (risky) literals:
|
|
|
|
@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])
|
|
@end example
|
|
|
|
@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 will contain
|
|
unexpanded macros. The @command{autoconf} program checks for this problem
|
|
by doing @samp{grep AC_ configure}.
|
|
|
|
|
|
@c ---------------------------------------- Using autom4te
|
|
|
|
@node Using autom4te
|
|
@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 @command{m4}:
|
|
@command{autom4te}@footnote{
|
|
@c
|
|
Yet another great name from Lars J. Aas.
|
|
@c
|
|
}.
|
|
|
|
@command{autom4te} is a preprocessor that is like @command{m4}.
|
|
It supports M4 extensions designed for use in tools like Autoconf.
|
|
|
|
@menu
|
|
* autom4te Invocation:: A @acronym{GNU} M4 wrapper
|
|
* Customizing autom4te:: Customizing the Autoconf package
|
|
@end menu
|
|
|
|
@node autom4te Invocation
|
|
@subsection Invoking @command{autom4te}
|
|
|
|
The command line arguments are modeled after M4's:
|
|
|
|
@example
|
|
autom4te @var{options} @var{files}
|
|
@end example
|
|
|
|
@noindent
|
|
where the @var{files} are directly passed to @command{m4}. 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}:
|
|
|
|
@table @file
|
|
@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.
|
|
|
|
@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.
|
|
@end table
|
|
|
|
@sp 1
|
|
|
|
Of course, it supports the Autoconf common subset of options:
|
|
|
|
@table @option
|
|
@item --help
|
|
@itemx -h
|
|
Print a summary of the command line options and exit.
|
|
|
|
@item --version
|
|
@itemx -V
|
|
Print the version number of Autoconf and exit.
|
|
|
|
@item --verbose
|
|
@itemx -v
|
|
Report processing steps.
|
|
|
|
@item --debug
|
|
@itemx -d
|
|
Don't remove the temporary files and be even more verbose.
|
|
|
|
@item --include=@var{dir}
|
|
@itemx -I @var{dir}
|
|
Also look for input files in @var{dir}. Multiple invocations
|
|
accumulate.
|
|
|
|
@item --output=@var{file}
|
|
@itemx -o @var{file}
|
|
Save output (script or trace) to @var{file}. The file @option{-} stands
|
|
for the standard output.
|
|
@end table
|
|
|
|
@sp 1
|
|
|
|
As an extension of @command{m4}, it includes the following options:
|
|
|
|
@table @option
|
|
@item --warnings=@var{category}
|
|
@itemx -W @var{category}
|
|
@evindex WARNINGS
|
|
@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
|
|
@code{AC_DIAGNOSE}, for a comprehensive list of categories. Special
|
|
values include:
|
|
|
|
@table @samp
|
|
@item all
|
|
report all the warnings
|
|
|
|
@item none
|
|
report none
|
|
|
|
@item error
|
|
treats warnings as errors
|
|
|
|
@item no-@var{category}
|
|
disable warnings falling into @var{category}
|
|
@end table
|
|
|
|
Warnings about @samp{syntax} are enabled by default, and the environment
|
|
variable @code{WARNINGS}, a comma separated list of categories, is
|
|
honored. @command{autom4te -W @var{category}} will actually
|
|
behave as if you had run:
|
|
|
|
@example
|
|
autom4te --warnings=syntax,$WARNINGS,@var{category}
|
|
@end example
|
|
|
|
@noindent
|
|
If you want to disable @command{autom4te}'s defaults and
|
|
@code{WARNINGS}, but (for example) enable the warnings about obsolete
|
|
constructs, you would use @option{-W none,obsolete}.
|
|
|
|
@cindex Back trace
|
|
@cindex Macro invocation stack
|
|
@command{autom4te} displays a back trace for errors, but not for
|
|
warnings; if you want them, just pass @option{-W error}. For instance,
|
|
on this @file{configure.ac}:
|
|
|
|
@example
|
|
AC_DEFUN([INNER],
|
|
[AC_RUN_IFELSE([AC_LANG_PROGRAM([exit (0)])])])
|
|
|
|
AC_DEFUN([OUTER],
|
|
[INNER])
|
|
|
|
AC_INIT
|
|
OUTER
|
|
@end example
|
|
|
|
@noindent
|
|
you get:
|
|
|
|
@example
|
|
$ @kbd{autom4te -l autoconf -Wcross}
|
|
configure.ac:8: warning: AC_RUN_IFELSE called without default \
|
|
to allow cross compiling
|
|
$ @kbd{autom4te -l autoconf -Wcross,error -f}
|
|
configure.ac:8: error: AC_RUN_IFELSE called without default \
|
|
to allow cross compiling
|
|
acgeneral.m4:3044: AC_RUN_IFELSE is expanded from...
|
|
configure.ac:2: INNER is expanded from...
|
|
configure.ac:5: OUTER is expanded from...
|
|
configure.ac:8: the top level
|
|
@end example
|
|
|
|
|
|
@item --melt
|
|
@itemx -m
|
|
Do not use frozen files. Any argument @code{@var{file}.m4f} will be
|
|
replaced with @code{@var{file}.m4}. This helps tracing the macros which
|
|
are executed only when the files are frozen, typically
|
|
@code{m4_define}. For instance, running:
|
|
|
|
@example
|
|
autom4te --melt 1.m4 2.m4f 3.m4 4.m4f input.m4
|
|
@end example
|
|
|
|
@noindent
|
|
is roughly equivalent to running:
|
|
|
|
@example
|
|
m4 1.m4 2.m4 3.m4 4.m4 input.m4
|
|
@end example
|
|
|
|
@noindent
|
|
while
|
|
|
|
@example
|
|
autom4te 1.m4 2.m4f 3.m4 4.m4f input.m4
|
|
@end example
|
|
|
|
@noindent
|
|
is equivalent to:
|
|
|
|
@example
|
|
m4 --reload-state=4.m4f input.m4
|
|
@end example
|
|
|
|
@item --freeze
|
|
@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 whitespace is @emph{not} empty) and comments
|
|
(starting with @samp{#}). Please, note that contrary to @command{m4},
|
|
this options takes no argument:
|
|
|
|
@example
|
|
autom4te 1.m4 2.m4 3.m4 --freeze --output=3.m4f
|
|
@end example
|
|
|
|
@noindent
|
|
corresponds to
|
|
|
|
@example
|
|
m4 1.m4 2.m4 3.m4 --freeze-state=3.m4f
|
|
@end example
|
|
|
|
@item --mode=@var{octal-mode}
|
|
@itemx -m @var{octal-mode}
|
|
Set the mode of the non-traces output to @var{octal-mode}; by default
|
|
@samp{0666}.
|
|
@end table
|
|
|
|
@sp 1
|
|
|
|
@cindex @file{autom4te.cache}
|
|
As another additional feature over @command{m4}, @command{autom4te}
|
|
caches its results. @acronym{GNU} M4 is able to produce a regular
|
|
output and traces at the same time. Traces are heavily used in the
|
|
@acronym{GNU} Build System: @command{autoheader} uses them to build
|
|
@file{config.h.in}, @command{autoreconf} to determine what
|
|
@acronym{GNU} Build System components are used, @command{automake} to
|
|
``parse'' @file{configure.ac} etc. To save the long runs of
|
|
@command{m4}, 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 is trashed).
|
|
|
|
@table @option
|
|
@item --cache=@var{directory}
|
|
@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
|
|
path name, as for the time being, global caches are not supported.
|
|
|
|
@item --no-cache
|
|
Don't cache the results.
|
|
|
|
@item --force
|
|
@itemx -f
|
|
If a cache is used, consider it obsolete (but update it anyway).
|
|
@end table
|
|
|
|
@sp 1
|
|
|
|
Because traces are so important to the @acronym{GNU} Build System,
|
|
@command{autom4te} provides high level tracing features as compared to
|
|
M4, and helps exploiting the cache:
|
|
|
|
@table @option
|
|
@item --trace=@var{macro}[:@var{format}]
|
|
@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:
|
|
|
|
@table @samp
|
|
@item $$
|
|
The character @samp{$}.
|
|
|
|
@item $f
|
|
The filename from which @var{macro} is called.
|
|
|
|
@item $l
|
|
The line number from which @var{macro} is called.
|
|
|
|
@item $d
|
|
The depth of the @var{macro} call. This is an M4 technical detail that
|
|
you probably don't want to know about.
|
|
|
|
@item $n
|
|
The name of the @var{macro}.
|
|
|
|
@item $@var{num}
|
|
The @var{num}th argument of the call to @var{macro}.
|
|
|
|
@item $@@
|
|
@itemx $@var{sep}@@
|
|
@itemx $@{@var{separator}@}@@
|
|
All the arguments passed to @var{macro}, separated by the character
|
|
@var{sep} or the string @var{separator} (@samp{,} by default). Each
|
|
argument is quoted, i.e., enclosed in a pair of square brackets.
|
|
|
|
@item $*
|
|
@itemx $@var{sep}*
|
|
@itemx $@{@var{separator}@}*
|
|
As above, but the arguments are not quoted.
|
|
|
|
@item $%
|
|
@itemx $@var{sep}%
|
|
@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.
|
|
@end table
|
|
|
|
@xref{autoconf Invocation}, for examples of trace uses.
|
|
|
|
@item --preselect=@var{macro}
|
|
@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
|
|
@command{autoheader}, @command{automake}, @command{autoreconf} etc.@: will
|
|
trace, so that running @command{m4} is not needed to trace them: the
|
|
cache suffices. This results in a huge speed-up.
|
|
@end table
|
|
|
|
@sp 1
|
|
|
|
@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:
|
|
|
|
@table @option
|
|
@item --language=@var{language}
|
|
@itemx -l =@var{language}
|
|
Use the @var{language} Autom4te library. Current languages include:
|
|
|
|
@table @code
|
|
@item M4sugar
|
|
create M4sugar output.
|
|
|
|
@item M4sh
|
|
create M4sh executable shell scripts.
|
|
|
|
@item Autotest
|
|
create Autotest executable test suites.
|
|
|
|
@item Autoconf
|
|
create Autoconf executable configure scripts.
|
|
|
|
@item Autoconf-without-aclocal-m4
|
|
create Autoconf executable configure scripts without
|
|
reading @file{aclocal.m4}.
|
|
@end table
|
|
|
|
@item --prepend-include=@var{dir}
|
|
@item -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.
|
|
|
|
@end table
|
|
|
|
@cindex @file{autom4te.cfg}
|
|
As an example, if Autoconf is installed in its default location,
|
|
@file{/usr/local}, running @samp{autom4te -l m4sugar foo.m4} is
|
|
strictly equivalent to running @samp{autom4te --prepend-include
|
|
/usr/local/share/autoconf m4sugar/m4sugar.m4f --warnings syntax foo.m4}.
|
|
Recursive expansion applies: running @samp{autom4te -l m4sh foo.m4}
|
|
is the same as @samp{autom4te --language M4sugar m4sugar/m4sh.m4f
|
|
foo.m4}, i.e., @samp{autom4te --prepend-include /usr/local/share/autoconf
|
|
m4sugar/m4sugar.m4f m4sugar/m4sh.m4f --mode 777 foo.m4}. The definition
|
|
of the languages is stored in @file{autom4te.cfg}.
|
|
|
|
@node Customizing autom4te
|
|
@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}"},
|
|
@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:
|
|
@var{arguments}}. You may use the traditional shell syntax to quote the
|
|
@var{arguments}.
|
|
|
|
As an example, to disable Autoconf caches (@file{autom4te.cache})
|
|
globally, include the following lines in @file{~/.autom4te.cfg}:
|
|
|
|
@verbatim
|
|
## ------------------ ##
|
|
## User Preferences. ##
|
|
## ------------------ ##
|
|
|
|
begin-language: "Autoconf"
|
|
args: --no-cache
|
|
end-language: "Autoconf"
|
|
@end verbatim
|
|
|
|
|
|
@node Programming in M4sugar
|
|
@section Programming in M4sugar
|
|
|
|
@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''.
|
|
|
|
@menu
|
|
* Redefined M4 Macros:: M4 builtins changed in M4sugar
|
|
* Evaluation Macros:: More quotation and evaluation control
|
|
* Forbidden Patterns:: Catching unexpanded macros
|
|
@end menu
|
|
|
|
@node Redefined M4 Macros
|
|
@subsection Redefined M4 Macros
|
|
|
|
With a few exceptions, all the M4 native macros are moved in the
|
|
@samp{m4_} pseudo-namespace, e.g., M4sugar renames @code{define} as
|
|
@code{m4_define} etc.
|
|
|
|
Some M4 macros are redefined, and are slightly incompatible with their
|
|
native equivalent.
|
|
|
|
@defmac dnl
|
|
@msindex{dnl}
|
|
This macro kept its original name: no @code{m4_dnl} is defined.
|
|
@end defmac
|
|
|
|
@defmac m4_defn (@var{macro})
|
|
@msindex{defn}
|
|
Contrary to the M4 builtin, this macro fails if @var{macro} is not
|
|
defined. See @code{m4_undefine}.
|
|
@end defmac
|
|
|
|
@defmac m4_exit (@var{exit-status})
|
|
@msindex{exit}
|
|
This macro corresponds to @code{m4exit}.
|
|
@end defmac
|
|
|
|
@defmac m4_if (@var{comment})
|
|
@defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @ovar{not-equal})
|
|
@defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @dots{})
|
|
@msindex{if}
|
|
This macro corresponds to @code{ifelse}.
|
|
@end defmac
|
|
|
|
@defmac m4_undefine (@var{macro})
|
|
@msindex{undefine}
|
|
Contrary to the M4 builtin, this macro fails if @var{macro} is not
|
|
defined. Use
|
|
|
|
@example
|
|
m4_ifdef([@var{macro}], [m4_undefine([@var{macro}])])
|
|
@end example
|
|
|
|
@noindent
|
|
to recover the behavior of the builtin.
|
|
@end defmac
|
|
|
|
@defmac m4_bpatsubst (@var{string}, @var{regexp}, @ovar{replacement})
|
|
@msindex{bpatsubst}
|
|
This macro corresponds to @code{patsubst}. The name @code{m4_patsubst}
|
|
is kept for future versions of M4sh, on top of @acronym{GNU} M4 which will
|
|
provide extended regular expression syntax via @code{epatsubst}.
|
|
@end defmac
|
|
|
|
@defmac m4_popdef (@var{macro})
|
|
@msindex{popdef}
|
|
Contrary to the M4 builtin, this macro fails if @var{macro} is not
|
|
defined. See @code{m4_undefine}.
|
|
@end defmac
|
|
|
|
@defmac m4_bregexp (@var{string}, @var{regexp}, @ovar{replacement})
|
|
@msindex{bregexp}
|
|
This macro corresponds to @code{regexp}. The name @code{m4_regexp}
|
|
is kept for future versions of M4sh, on top of @acronym{GNU} M4 which will
|
|
provide extended regular expression syntax via @code{eregexp}.
|
|
@end defmac
|
|
|
|
@defmac m4_wrap (@var{text})
|
|
@msindex{wrap}
|
|
This macro corresponds to @code{m4wrap}.
|
|
|
|
You are encouraged to end @var{text} with @samp{[]}, so that there are
|
|
no risks that two consecutive invocations of @code{m4_wrap} result in an
|
|
unexpected pasting of tokens, as in
|
|
|
|
@example
|
|
m4_define([foo], [Foo])
|
|
m4_define([bar], [Bar])
|
|
m4_define([foobar], [FOOBAR])
|
|
m4_wrap([bar])
|
|
m4_wrap([foo])
|
|
@result{}FOOBAR
|
|
@end example
|
|
@end defmac
|
|
|
|
@node Evaluation Macros
|
|
@subsection Evaluation Macros
|
|
|
|
The following macros give some control over the order of the evaluation
|
|
by adding or removing levels of quotes. They are meant for hard-core M4
|
|
programmers.
|
|
|
|
@defmac m4_dquote (@var{arg1}, @dots{})
|
|
@msindex{dquote}
|
|
Return the arguments as a quoted list of quoted arguments.
|
|
@end defmac
|
|
|
|
@defmac m4_quote (@var{arg1}, @dots{})
|
|
@msindex{quote}
|
|
Return the arguments as a single entity, i.e., wrap them into a pair of
|
|
quotes.
|
|
@end defmac
|
|
|
|
The following example aims at emphasizing the difference between (i), not
|
|
using these macros, (ii), using @code{m4_quote}, and (iii), using
|
|
@code{m4_dquote}.
|
|
|
|
@example
|
|
$ @kbd{cat example.m4}
|
|
# Overquote, so that quotes are visible.
|
|
m4_define([show], [$[]1 = [$1], $[]@@ = [$@@]])
|
|
m4_divert(0)dnl
|
|
show(a, b)
|
|
show(m4_quote(a, b))
|
|
show(m4_dquote(a, b))
|
|
$ @kbd{autom4te -l m4sugar example.m4}
|
|
$1 = a, $@@ = [a],[b]
|
|
$1 = a,b, $@@ = [a,b]
|
|
$1 = [a],[b], $@@ = [[a],[b]]
|
|
@end example
|
|
|
|
|
|
|
|
@node Forbidden Patterns
|
|
@subsection Forbidden Patterns
|
|
|
|
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
|
|
@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$}.
|
|
|
|
@defmac m4_pattern_forbid (@var{pattern})
|
|
@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 makes sense to
|
|
the author of this documentation, as @samp{#}-comments should document
|
|
the output, not the input, documented by @samp{dnl} comments).
|
|
@end defmac
|
|
|
|
Of course, you might encounter exceptions to these generic rules, for
|
|
instance you might have to refer to @samp{$m4_flags}.
|
|
|
|
@defmac m4_pattern_allow (@var{pattern})
|
|
@msindex{pattern_allow}
|
|
Any token matching @var{pattern} is allowed, including if it matches an
|
|
@code{m4_pattern_forbid} pattern.
|
|
@end defmac
|
|
|
|
@node Programming in M4sh
|
|
@section Programming in M4sh
|
|
|
|
@c FIXME: Eventually will become a chapter, as it is not related to
|
|
@c programming in M4 per se.
|
|
|
|
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):
|
|
|
|
@quotation
|
|
Mash \Mash\, n. [Akin to G. meisch, maisch, meische, maische, mash,
|
|
wash, and prob.@: to AS.@: miscian to mix. See ``Mix''.]
|
|
|
|
@enumerate 1
|
|
@item
|
|
A mass of mixed ingredients reduced to a soft pulpy state by beating or
|
|
pressure@enddots{}
|
|
|
|
@item
|
|
A mixture of meal or bran and water fed to animals.
|
|
|
|
@item
|
|
A mess; trouble. [Obs.] --Beau.@: & Fl.
|
|
@end enumerate
|
|
@end quotation
|
|
|
|
|
|
For the time being, it is not mature enough to be widely used.
|
|
|
|
M4sh provides portable alternatives for some common shell constructs
|
|
that unfortunately are not portable in practice.
|
|
|
|
@defmac AS_DIRNAME (@var{pathname})
|
|
@asindex{DIRNAME}
|
|
Return the directory portion of @var{pathname}, using the algorithm
|
|
required by @acronym{POSIX}. @xref{Limitations of Usual Tools}, for more
|
|
details about what this returns and why it is more portable than the
|
|
@command{dirname} command.
|
|
@end defmac
|
|
|
|
@defmac AS_IF (@var{test}, @ovar{RUN-IF-TRUE}, @ovar{RUN-IF-FALSE})
|
|
@asindex{IF}
|
|
Run shell code TEST. If TEST exits with a zero status then run shell code
|
|
RUN-IF-TRUE, else run shell code RUN-IF-FALSE, with simplifications if either
|
|
RUN-IF-TRUE or RUN-IF-FALSE is empty.
|
|
@end defmac
|
|
|
|
@defmac AS_MKDIR_P (@var{filename})
|
|
@asindex{MKDIR_P}
|
|
Make the directory @var{filename}, including intervening directories
|
|
as necessary. This is equivalent to @samp{mkdir -p @var{filename}},
|
|
except that it is portable to older versions of @command{mkdir} that
|
|
lack support for the @option{-p} option.
|
|
@end defmac
|
|
|
|
@defmac AS_SET_CATFILE (@var{var}, @var{dir}, @var{file})
|
|
@asindex{SET_CATFILE}
|
|
Set the shell variable @var{var} to @var{dir}/@var{file}, but
|
|
optimizing the common cases (@var{dir} or @var{file} is @samp{.},
|
|
@var{file} is absolute etc.).
|
|
@end defmac
|
|
|
|
|
|
|
|
@c=================================================== Writing Autoconf Macros.
|
|
|
|
@node Writing Autoconf Macros
|
|
@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.
|
|
|
|
@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
|
|
@end menu
|
|
|
|
@node Macro Definitions
|
|
@section Macro Definitions
|
|
|
|
@acindex{DEFUN}
|
|
Autoconf macros are defined using the @code{AC_DEFUN} macro, which is
|
|
similar to the M4 builtin @code{m4_define} macro. 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 (@pxref{Prerequisite
|
|
Macros}).
|
|
|
|
An Autoconf macro definition looks like this:
|
|
|
|
@example
|
|
AC_DEFUN(@var{macro-name}, @var{macro-body})
|
|
@end example
|
|
|
|
You can refer to any arguments passed to the macro as @samp{$1},
|
|
@samp{$2}, etc. @xref{Definitions,, How to define new macros, m4.info,
|
|
@acronym{GNU} m4}, for more complete information on writing M4 macros.
|
|
|
|
Be sure to properly quote both the @var{macro-body} @emph{and} the
|
|
@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:
|
|
|
|
@example
|
|
# AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1])
|
|
# --------------------------------------
|
|
m4_define([AC_MSG_ERROR],
|
|
[@{ _AC_ECHO([configure: error: $1], 2); exit m4_default([$2], 1); @}])
|
|
@end example
|
|
|
|
Comments about the macro should be left in the header comment. Most
|
|
other comments will make their way into @file{configure}, so just keep
|
|
using @samp{#} to introduce comments.
|
|
|
|
@cindex @code{dnl}
|
|
If you have some very 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;
|
|
@code{dnl} is more useful to get rid of the newlines following macros
|
|
that produce no output, such as @code{AC_REQUIRE}.
|
|
|
|
|
|
@node Macro Names
|
|
@section Macro Names
|
|
|
|
All of the Autoconf macros have all-uppercase names starting with
|
|
@samp{AC_} to prevent them from accidentally conflicting with other
|
|
text. All shell variables that they use for internal purposes have
|
|
mostly-lowercase names starting with @samp{ac_}. 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.
|
|
|
|
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 @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.
|
|
|
|
@table @code
|
|
@item C
|
|
C language builtin features.
|
|
@item DECL
|
|
Declarations of C variables in header files.
|
|
@item FUNC
|
|
Functions in libraries.
|
|
@item GROUP
|
|
@sc{unix} group owners of files.
|
|
@item HEADER
|
|
Header files.
|
|
@item LIB
|
|
C libraries.
|
|
@item PATH
|
|
The full path names to files, including programs.
|
|
@item PROG
|
|
The base names of programs.
|
|
@item MEMBER
|
|
Members of aggregates.
|
|
@item SYS
|
|
Operating system features.
|
|
@item TYPE
|
|
C builtin or declared types.
|
|
@item VAR
|
|
C variables in libraries.
|
|
@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_FUNC_UTIME_NULL} checks the
|
|
behavior of the @code{utime} function when called with a @code{NULL}
|
|
pointer.
|
|
|
|
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
|
|
@code{_AC_PATH_X_XMKMF} and @code{_AC_PATH_X_DIRECT}.
|
|
|
|
@node Reporting Messages
|
|
@section Reporting Messages
|
|
@cindex Messages, from @command{autoconf}
|
|
|
|
When macros statically diagnose abnormal situations, benign or fatal,
|
|
they should report them using these macros. For dynamic issues, i.e.,
|
|
when @command{configure} is run, see @ref{Printing Messages}.
|
|
|
|
@defmac AC_DIAGNOSE (@var{category}, @var{message})
|
|
@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. You are
|
|
encouraged to use standard categories, which currently include:
|
|
|
|
@table @samp
|
|
@item all
|
|
messages that don't fall into one of the following categories. Use of an
|
|
empty @var{category} is equivalent.
|
|
|
|
@item cross
|
|
related to cross compilation issues.
|
|
|
|
@item obsolete
|
|
use of an obsolete construct.
|
|
|
|
@item syntax
|
|
dubious syntactic constructs, incorrectly ordered macro calls.
|
|
@end table
|
|
@end defmac
|
|
|
|
@defmac AC_WARNING (@var{message})
|
|
@acindex{WARNING}
|
|
Equivalent to @samp{AC_DIAGNOSE([syntax], @var{message})}, but you are
|
|
strongly encouraged to use a finer grained category.
|
|
@end defmac
|
|
|
|
@defmac AC_FATAL (@var{message})
|
|
@acindex{FATAL}
|
|
Report a severe error @var{message}, and have @command{autoconf} die.
|
|
@end defmac
|
|
|
|
When the user runs @samp{autoconf -W error}, warnings from
|
|
@code{AC_DIAGNOSE} and @code{AC_WARNING} are reported as error, see
|
|
@ref{autoconf Invocation}.
|
|
|
|
@node Dependencies Between Macros
|
|
@section 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.
|
|
|
|
@menu
|
|
* Prerequisite Macros:: Ensuring required information
|
|
* Suggested Ordering:: Warning about possible ordering problems
|
|
@end menu
|
|
|
|
@node Prerequisite Macros
|
|
@subsection Prerequisite Macros
|
|
|
|
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
|
|
@code{AC_PROG_LEX} having been called first to set the shell variable
|
|
@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.
|
|
|
|
@defmac AC_REQUIRE (@var{macro-name})
|
|
@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
|
|
@code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
|
|
that it has been called.
|
|
|
|
@code{AC_REQUIRE} must be used inside an @code{AC_DEFUN}'d macro; it
|
|
must not be called from the top level.
|
|
@end defmac
|
|
|
|
@code{AC_REQUIRE} is often misunderstood. It really implements
|
|
dependencies between macros in the sense that if one macro depends upon
|
|
another, the latter will be expanded @emph{before} the body of the
|
|
former. In particular, @samp{AC_REQUIRE(FOO)} is not replaced with the
|
|
body of @code{FOO}. For instance, this definition of macros:
|
|
|
|
@example
|
|
@group
|
|
AC_DEFUN([TRAVOLTA],
|
|
[test "$body_temperature_in_celsius" -gt "38" &&
|
|
dance_floor=occupied])
|
|
AC_DEFUN([NEWTON_JOHN],
|
|
[test "$hair_style" = "curly" &&
|
|
dance_floor=occupied])
|
|
@end group
|
|
|
|
@group
|
|
AC_DEFUN([RESERVE_DANCE_FLOOR],
|
|
[if date | grep '^Sat.*pm' >/dev/null 2>&1; then
|
|
AC_REQUIRE([TRAVOLTA])
|
|
AC_REQUIRE([NEWTON_JOHN])
|
|
fi])
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
with this @file{configure.ac}
|
|
|
|
@example
|
|
AC_INIT
|
|
RESERVE_DANCE_FLOOR
|
|
if test "$dance_floor" = occupied; then
|
|
AC_MSG_ERROR([cannot pick up here, let's move])
|
|
fi
|
|
@end example
|
|
|
|
@noindent
|
|
will not leave you with a better chance to meet a kindred soul at
|
|
other times than Saturday night since it expands into:
|
|
|
|
@example
|
|
@group
|
|
test "$body_temperature_in_Celsius" -gt "38" &&
|
|
dance_floor=occupied
|
|
test "$hair_style" = "curly" &&
|
|
dance_floor=occupied
|
|
fi
|
|
if date | grep '^Sat.*pm' >/dev/null 2>&1; then
|
|
|
|
|
|
fi
|
|
@end group
|
|
@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:
|
|
|
|
@example
|
|
@group
|
|
if @dots{}; then
|
|
AC_REQUIRE([SOME_CHECK])
|
|
fi
|
|
@dots{}
|
|
SOME_CHECK
|
|
@end group
|
|
@end example
|
|
|
|
|
|
You are encouraged to put all @code{AC_REQUIRE}s at the beginning of a
|
|
macro. You can use @code{dnl} to avoid the empty lines they leave.
|
|
|
|
@node Suggested Ordering
|
|
@subsection Suggested Ordering
|
|
|
|
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
|
|
@file{configure.ac} file. The warning occurs when creating
|
|
@command{configure} from @file{configure.ac}, not when running
|
|
@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:
|
|
|
|
@example
|
|
AC_BEFORE([$0], [AC_PROG_CPP])dnl
|
|
@end example
|
|
|
|
@noindent
|
|
This warns the user if a call to @code{AC_PROG_CPP} has already occurred
|
|
when @code{AC_PROG_CC} is called.
|
|
|
|
@defmac AC_BEFORE (@var{this-macro-name}, @var{called-macro-name})
|
|
@acindex{BEFORE}
|
|
Make M4 print a warning message to the standard error output if
|
|
@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
|
|
@code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
|
|
that it has been called.
|
|
@end defmac
|
|
|
|
@node Obsoleting Macros
|
|
@section Obsoleting Macros
|
|
|
|
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.
|
|
|
|
@defmac AU_DEFUN (@var{old-macro}, @var{implementation}, @ovar{message})
|
|
@acindex{DEFUN}
|
|
@acindex{AU_DEFUN}
|
|
Define @var{old-macro} as @var{implementation}. The only difference
|
|
with @code{AC_DEFUN} is that the user will be warned that
|
|
@var{old-macro} is now obsolete.
|
|
|
|
If she then uses @command{autoupdate}, the call to @var{old-macro} will be
|
|
replaced by the modern @var{implementation}. In the future,
|
|
@command{autoupdate} will then print the additional @var{message}.
|
|
@end defmac
|
|
|
|
@node Coding Style
|
|
@section 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 via 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
|
|
@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
|
|
@code{AC_SUBST} used to remember what @var{symbol}s were already defined
|
|
by setting @code{AC_SUBST_@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,
|
|
@code{AC_SUBST(@var{symbol})} or @code{_AC_SUBST(@var{symbol})} should
|
|
have been used (yes, with the parentheses)@dots{}or better yet, high-level
|
|
macros such as @code{AC_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.
|
|
|
|
@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 spaces 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
|
|
|
|
@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])])
|
|
@end example
|
|
|
|
@noindent
|
|
write
|
|
|
|
@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])])
|
|
@end example
|
|
|
|
@noindent
|
|
or even
|
|
|
|
@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])])
|
|
@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:
|
|
|
|
@example
|
|
m4_bpatsubst([$1], [$"])
|
|
@end example
|
|
|
|
@noindent
|
|
use
|
|
|
|
@example
|
|
m4_bpatsubst([$1], [$""])
|
|
@end example
|
|
|
|
@noindent
|
|
so that Emacsen do not open an endless ``string'' at the first quote.
|
|
For the same reasons, avoid:
|
|
|
|
@example
|
|
test $[#] != 0
|
|
@end example
|
|
|
|
@noindent
|
|
and use:
|
|
|
|
@example
|
|
test $[@@%:@@] != 0
|
|
@end example
|
|
|
|
@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
|
|
@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
|
|
purpose. With the @code{s} command, the preferred separator is @samp{/}
|
|
unless @samp{/} itself is used in the command, in which case you should
|
|
use @samp{,}.
|
|
|
|
@xref{Macro Definitions}, for details on how to define a macro. If a
|
|
macro doesn't use @code{AC_REQUIRE} and it is expected to never be the
|
|
object of an @code{AC_REQUIRE} directive, then use @code{m4_define}. In
|
|
case of doubt, use @code{AC_DEFUN}. All the @code{AC_REQUIRE}
|
|
statements should be at the beginning of the macro, @code{dnl}'ed.
|
|
|
|
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
|
|
@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:
|
|
|
|
@example
|
|
AC_DEFUN([AC_PATH_X],
|
|
[AC_MSG_CHECKING([for X])
|
|
AC_REQUIRE_CPP()
|
|
@r{# @dots{}omitted@dots{}}
|
|
AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
|
|
fi])
|
|
@end example
|
|
|
|
@noindent
|
|
you would write:
|
|
|
|
@example
|
|
AC_DEFUN([AC_PATH_X],
|
|
[AC_REQUIRE_CPP()[]dnl
|
|
AC_MSG_CHECKING([for X])
|
|
@r{# @dots{}omitted@dots{}}
|
|
AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
|
|
fi[]dnl
|
|
])# AC_PATH_X
|
|
@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
|
|
@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:
|
|
|
|
@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 "$ac_cv_emxos2" = yes && EMXOS2=yes])
|
|
@end example
|
|
|
|
@noindent
|
|
and the new way:
|
|
|
|
@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 "$ac_cv_emxos2" = yes && EMXOS2=yes[]dnl
|
|
])# _AC_EMXOS2
|
|
@end example
|
|
|
|
|
|
|
|
|
|
@c ============================================= Portable Shell Programming
|
|
|
|
@node Portable Shell
|
|
@chapter 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, but to prevent trouble, do not take
|
|
advantage of features that were added after @sc{unix} version 7, circa
|
|
1977 (@pxref{Systemology}).
|
|
|
|
You should not use shell functions, aliases, negated character
|
|
classes, or other features that are not found in all Bourne-compatible
|
|
shells; restrict yourself to the lowest common denominator. Even
|
|
@code{unset} is not supported by all shells! Also, include a space
|
|
after the exclamation point in interpreter specifications, like this:
|
|
|
|
@example
|
|
#! /usr/bin/perl
|
|
@end example
|
|
|
|
@noindent
|
|
If you omit the space before the path, then 4.2@acronym{BSD} based systems
|
|
(such as DYNIX) will ignore the line, because they interpret
|
|
@samp{#! /} as a 4-byte magic number. Some old systems have quite
|
|
small limits on the length of the @samp{#!} line too, for instance 32
|
|
bytes (not including the newline) on SunOS 4.
|
|
|
|
The set of external programs you should run in a @command{configure} script
|
|
is fairly small. @xref{Utilities in Makefiles,, Utilities in
|
|
Makefiles, standards, @acronym{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
|
|
@ref{Limitations of Usual Tools}.
|
|
|
|
There are other sources of documentation about shells. See for instance
|
|
@href{http://www.faqs.org/faqs/unix-faq/shell/, the Shell FAQs}.
|
|
|
|
@menu
|
|
* Shellology:: A zoology of shells
|
|
* Here-Documents:: Quirks and tricks
|
|
* File Descriptors:: FDs and redirections
|
|
* File System Conventions:: File- and pathnames
|
|
* Shell Substitutions:: Variable and command expansions
|
|
* Assignments:: Varying side effects of assignments
|
|
* Parentheses:: Parentheses in shell scripts
|
|
* Special Shell Variables:: Variables you should not change
|
|
* Limitations of Builtins:: Portable use of not so portable /bin/sh
|
|
* Limitations of Usual Tools:: Portable use of portable tools
|
|
* Limitations of Make:: Portable Makefiles
|
|
@end menu
|
|
|
|
@node Shellology
|
|
@section 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
|
|
@href{http://www.faqs.org/faqs/unix-faq/shell/shell-differences/, the
|
|
Shell difference FAQ} includes a small history of Unix shells, and a
|
|
comparison between several of them.
|
|
|
|
Below we describe some of the members of the Bourne shell family.
|
|
|
|
@table @asis
|
|
@item Ash
|
|
@cindex Ash
|
|
@command{ash} is often used on @acronym{GNU}/Linux and @acronym{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
|
|
@acronym{GNU}/Linux distributions.
|
|
|
|
To be compatible with Ash 0.2:
|
|
|
|
@itemize @minus
|
|
@item
|
|
don't use @samp{$?} after expanding empty or unset variables:
|
|
|
|
@example
|
|
foo=
|
|
false
|
|
$foo
|
|
echo "Don't use it: $?"
|
|
@end example
|
|
|
|
@item
|
|
don't use command substitution within variable expansion:
|
|
|
|
@example
|
|
cat $@{FOO=`bar`@}
|
|
@end example
|
|
|
|
@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''.
|
|
@end itemize
|
|
|
|
@item Bash
|
|
@cindex Bash
|
|
To detect whether you are running @command{bash}, test if
|
|
@code{BASH_VERSION} is set. To disable its extensions and require
|
|
@acronym{POSIX} compatibility, run @samp{set -o posix}. @xref{Bash POSIX
|
|
Mode,, Bash @acronym{POSIX} Mode, bash, The @acronym{GNU} Bash Reference
|
|
Manual}, for details.
|
|
|
|
@item Bash 2.05 and later
|
|
@cindex Bash 2.05 and later
|
|
Versions 2.05 and later of @command{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 @command{bash} (or with many other shells, probably). So if
|
|
you use @command{bash} 2.05 or higher to execute @command{configure},
|
|
you'll need to use @command{bash} 2.05 for all other build tasks as well.
|
|
|
|
@item Ksh
|
|
@prindex Ksh
|
|
@prindex Korn shell
|
|
@prindex @samp{ksh88}
|
|
@prindex @samp{ksh93}
|
|
The Korn shell is compatible with the Bourne family and it mostly
|
|
conforms to @acronym{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 Solaris systems have
|
|
three variants:
|
|
@prindex @command{/usr/bin/ksh} on Solaris
|
|
@command{/usr/bin/ksh} is @samp{ksh88},
|
|
@prindex @command{/usr/xpg4/bin/sh} on Solaris
|
|
@command{/usr/xpg4/bin/sh} is a @acronym{POSIX}-compliant variant of
|
|
@samp{ksh88}, and
|
|
@prindex @command{/usr/dt/bin/dtksh} on Solaris
|
|
@command{/usr/dt/bin/dtksh} is @samp{ksh93}. @command{/usr/bin/ksh}
|
|
is standard on Solaris; the other variants are 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.
|
|
@prindex @samp{pdksh}
|
|
A public-domain clone of the Korn shell called @samp{pdksh} is also
|
|
widely available: it has most of the @samp{ksh88} features along with
|
|
a few of its own.
|
|
|
|
@item Zsh
|
|
@cindex Zsh
|
|
To detect whether you are running @command{zsh}, test if
|
|
@code{ZSH_VERSION} is set. By default @command{zsh} is @emph{not}
|
|
compatible with the Bourne shell: you have to run @samp{emulate sh} and
|
|
set @code{NULLCMD} to @samp{:}. @xref{Compatibility,, Compatibility,
|
|
zsh, The Z Shell Manual}, for details.
|
|
|
|
Zsh 3.0.8 is the native @command{/bin/sh} on Mac OS X 10.0.3.
|
|
@end table
|
|
|
|
The following discussion between Russ Allbery and Robert Lipe is worth
|
|
reading:
|
|
|
|
@noindent
|
|
Russ Allbery:
|
|
|
|
@quotation
|
|
The @acronym{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 @acronym{POSIX} shell. Thus,
|
|
vendors who have taken this route will @emph{never} (OK@dots{}``never say
|
|
never'') replace the Bourne shell (as @command{/bin/sh}) with a
|
|
@acronym{POSIX} shell.
|
|
@end quotation
|
|
|
|
@noindent
|
|
Robert Lipe:
|
|
|
|
@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
|
|
@command{/bin/sh} programs are not the @acronym{POSIX} shell.
|
|
|
|
So while most modern systems do have a shell @emph{somewhere} that meets the
|
|
@acronym{POSIX} standard, the challenge is to find it.
|
|
@end quotation
|
|
|
|
@node Here-Documents
|
|
@section 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{/bin/sh}
|
|
on Open@acronym{BSD} 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 Open@acronym{BSD} 2.7's @command{/bin/sh}
|
|
|
|
@example
|
|
@group
|
|
$ @kbd{cat <<EOF
|
|
> \" \\
|
|
> EOF}
|
|
" \
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
and with Bash:
|
|
|
|
@example
|
|
@group
|
|
bash-2.04$ @kbd{cat <<EOF
|
|
> \" \\
|
|
> EOF}
|
|
\" \
|
|
@end group
|
|
@end example
|
|
|
|
|
|
Many older shells (including the Bourne shell) implement here-documents
|
|
inefficiently. And some shells mishandle large here-documents: for
|
|
example, Solaris 8 @command{dtksh}, which is derived from
|
|
@command{ksh} M-12/28/93d, mishandles variable expansion that occurs
|
|
on 1024-byte buffer boundaries within a here-document. Users can
|
|
generally fix these problems by using a faster or more reliable
|
|
shell, e.g., by using the command @samp{bash ./configure} rather than
|
|
plain @samp{./configure}.
|
|
|
|
Some shells can be extremely inefficient when there are a lot of
|
|
here-documents inside a single statement. For instance if your
|
|
@file{configure.ac} includes something like:
|
|
|
|
@example
|
|
@group
|
|
if <cross_compiling>; then
|
|
assume this and that
|
|
else
|
|
check this
|
|
check that
|
|
check something else
|
|
@dots{}
|
|
on and on forever
|
|
@dots{}
|
|
fi
|
|
@end group
|
|
@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
|
|
@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 run-time, and we end up not
|
|
executing the macro at all.
|
|
|
|
@node File Descriptors
|
|
@section File Descriptors
|
|
|
|
Some file descriptors shall not be used, since some systems, admittedly
|
|
arcane, use them for special purpose:
|
|
|
|
@display
|
|
3 --- some systems may open it to @samp{/dev/tty}.
|
|
4 --- used on the Kubota Titan.
|
|
@end display
|
|
|
|
Don't redirect the same file descriptor several times, as you are doomed
|
|
to failure under Ultrix.
|
|
|
|
@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.
|
|
@end example
|
|
|
|
@noindent
|
|
In each case the expected result is of course @file{fullness} containing
|
|
@samp{matter} and @file{void} being empty.
|
|
|
|
Don't try to redirect the standard error of a command substitution: it
|
|
must be done @emph{inside} the command substitution: when running
|
|
@samp{: `cd /zorglub` 2>/dev/null} expect the error message to
|
|
escape, while @samp{: `cd /zorglub 2>/dev/null`} works properly.
|
|
|
|
It is worth noting that Zsh (but not Ash nor Bash) makes it possible
|
|
in assignments though: @samp{foo=`cd /zorglub` 2>/dev/null}.
|
|
|
|
Most shells, if not all (including Bash, Zsh, Ash), output traces on
|
|
stderr, even for sub-shells. This might result in undesirable content
|
|
if you meant to capture the standard-error output of the inner command:
|
|
|
|
@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'}
|
|
@i{# Traces on startup files deleted here.}
|
|
$ @kbd{cat stderr}
|
|
+zsh:1> eval echo foo >&2
|
|
+zsh:1> echo foo
|
|
foo
|
|
@end example
|
|
|
|
@noindent
|
|
You'll appreciate the various levels of detail@enddots{}
|
|
|
|
One workaround is to grep out uninteresting lines, hoping not to remove
|
|
good ones@enddots{}
|
|
|
|
Don't try to move/delete open files, such as in @samp{exec >foo; mv foo
|
|
bar}; see @ref{Limitations of Builtins}, @command{mv} for more details.
|
|
|
|
@node File System Conventions
|
|
@section File System Conventions
|
|
|
|
While @command{autoconf} and friends will usually be run on some Unix
|
|
variety, it can and will be used on other systems, most notably @acronym{DOS}
|
|
variants. This impacts several assumptions regarding file and
|
|
path names.
|
|
|
|
@noindent
|
|
For example, the following code:
|
|
|
|
@example
|
|
case $foo_dir in
|
|
/*) # Absolute
|
|
;;
|
|
*)
|
|
foo_dir=$dots$foo_dir ;;
|
|
esac
|
|
@end example
|
|
|
|
@noindent
|
|
will fail to properly detect absolute paths on those systems, because
|
|
they can use a drivespec, and will usually use a backslash as directory
|
|
separator. The canonical way to check for absolute paths is:
|
|
|
|
@example
|
|
case $foo_dir in
|
|
[\\/]* | ?:[\\/]* ) # Absolute
|
|
;;
|
|
*)
|
|
foo_dir=$dots$foo_dir ;;
|
|
esac
|
|
@end example
|
|
|
|
@noindent
|
|
Make sure you quote the brackets if appropriate and keep the backslash as
|
|
first character (@pxref{Limitations of 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, use the
|
|
@code{PATH_SEPARATOR} output variable instead. @command{configure} sets this
|
|
to the appropriate value (@samp{:} or @samp{;}) when it starts up.
|
|
|
|
File names need extra care as well. While @acronym{DOS}-based environments
|
|
that are Unixy enough to run @command{autoconf} (such as DJGPP) will
|
|
usually be 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
|
|
@href{ftp://ftp.gnu.org/gnu/non-gnu/doschk/doschk-1.1.tar.gz, doschk}
|
|
package.
|
|
|
|
A short overview follows; problems are marked with @sc{sfn}/@sc{lfn} to
|
|
indicate where they apply: @sc{sfn} means the issues are only relevant to
|
|
plain @acronym{DOS}, not to @acronym{DOS} boxes under Windows, while @sc{lfn}
|
|
identifies problems that exist even under Windows.
|
|
|
|
@table @asis
|
|
@item No multiple dots (@sc{sfn})
|
|
@acronym{DOS} cannot handle multiple dots in filenames. 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 Unices:
|
|
|
|
@example
|
|
AC_CONFIG_HEADERS([config.h])
|
|
AC_CONFIG_FILES([source.c foo.bar])
|
|
AC_OUTPUT
|
|
@end example
|
|
|
|
@noindent
|
|
but it causes problems on @acronym{DOS}, as it requires @samp{config.h.in},
|
|
@samp{source.c.in} and @samp{foo.bar.in}. To make your package more portable
|
|
to @acronym{DOS}-based environments, you should use this instead:
|
|
|
|
@example
|
|
AC_CONFIG_HEADERS([config.h:config.hin])
|
|
AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in])
|
|
AC_OUTPUT
|
|
@end example
|
|
|
|
@item No leading dot (@sc{sfn})
|
|
@acronym{DOS} cannot handle filenames that start with a dot. This is usually
|
|
not a very important issue for @command{autoconf}.
|
|
|
|
@item Case insensitivity (@sc{lfn})
|
|
@acronym{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} will do nothing (unless the
|
|
@samp{install} target is marked as PHONY).
|
|
|
|
@item The 8+3 limit (@sc{sfn})
|
|
Because the @acronym{DOS} file system only stores the first 8 characters of
|
|
the filename and the first 3 of the extension, those must be unique.
|
|
That means that @file{foobar-part1.c}, @file{foobar-part2.c} and
|
|
@file{foobar-prettybird.c} all resolve to the same filename
|
|
(@file{FOOBAR-P.C}). The same goes for @file{foo.bar} and
|
|
@file{foo.bartender}.
|
|
|
|
Note: This is not usually a problem under Windows, as it uses numeric
|
|
tails in the short version of filenames 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 @sc{sfn}
|
|
and @sc{lfn} environments, it also means the above problem applies there
|
|
as well.
|
|
|
|
@item Invalid characters
|
|
Some characters are invalid in @acronym{DOS} filenames, and should therefore
|
|
be avoided. In a @sc{lfn} environment, these are @samp{/}, @samp{\},
|
|
@samp{?}, @samp{*}, @samp{:}, @samp{<}, @samp{>}, @samp{|} and @samp{"}.
|
|
In a @sc{sfn} environment, other characters are also invalid. These
|
|
include @samp{+}, @samp{,}, @samp{[} and @samp{]}.
|
|
@end table
|
|
|
|
@node Shell Substitutions
|
|
@section 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:
|
|
|
|
@example
|
|
case "$given_srcdir" in
|
|
.) top_srcdir="`echo "$dots" | sed 's,/$,,'`"
|
|
*) top_srcdir="$dots$given_srcdir" ;;
|
|
esac
|
|
@end example
|
|
|
|
@noindent
|
|
is more readable when written as:
|
|
|
|
@example
|
|
case $given_srcdir in
|
|
.) top_srcdir=`echo "$dots" | sed 's,/$,,'`
|
|
*) top_srcdir=$dots$given_srcdir ;;
|
|
esac
|
|
@end example
|
|
|
|
@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{}`"}.
|
|
Worse yet, not all shells understand @code{"`@dots{}\"@dots{}\"@dots{}`"}
|
|
the same way. There is just no portable way to use double-quoted
|
|
strings inside double-quoted back-quoted expressions (pfew!).
|
|
|
|
@table @code
|
|
@item $@@
|
|
@cindex @samp{"$@@"}
|
|
One of the most famous shell-portability issues is related to
|
|
@samp{"$@@"}. When there are no positional arguments, @acronym{POSIX} says
|
|
that @samp{"$@@"} is supposed to be equivalent to nothing, but the
|
|
original Unix Version 7 Bourne shell treated it as equivalent to
|
|
@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
|
|
@samp{$@{1+"$@@"@}}. Unfortunately this method does not work with
|
|
Zsh (3.x and 4.x), which is used on Mac OS X@. When emulating
|
|
the Bourne shell, Zsh performs word splitting on @samp{$@{1+"$@@"@}}:
|
|
|
|
@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
|
|
!
|
|
@end example
|
|
|
|
@noindent
|
|
Zsh handles plain @samp{"$@@"} properly, but we can't use plain
|
|
@samp{"$@@"} because of the portability problems mentioned above.
|
|
One workaround relies on Zsh's ``global aliases'' to convert
|
|
@samp{$@{1+"$@@"@}} into @samp{"$@@"} by itself:
|
|
|
|
@example
|
|
test "$@{ZSH_VERSION+set@}" = set && alias -g '$@{1+"$@@"@}'='"$@@"'
|
|
@end example
|
|
|
|
A more conservative workaround is to avoid @samp{"$@@"} if it is
|
|
possible that there may be no positional arguments. For example,
|
|
instead of:
|
|
|
|
@example
|
|
cat conftest.c "$@@"
|
|
@end example
|
|
|
|
you can use this instead:
|
|
|
|
@example
|
|
case $# in
|
|
0) cat conftest.c;;
|
|
*) cat conftest.c "$@@";;
|
|
esac
|
|
@end example
|
|
|
|
@item $@{@var{var}:-@var{value}@}
|
|
@c Info cannot handle `:' in index entries.
|
|
@c @cindex $@{@var{var}:-@var{value}@}
|
|
Old @acronym{BSD} shells, including the Ultrix @code{sh}, don't accept the
|
|
colon for any shell substitution, and complain and die.
|
|
|
|
@item $@{@var{var}=@var{literal}@}
|
|
@cindex $@{@var{var}=@var{literal}@}
|
|
Be sure to quote:
|
|
|
|
@example
|
|
: $@{var='Some words'@}
|
|
@end example
|
|
|
|
@noindent
|
|
otherwise some shells, such as on Digital Unix V 5.0, will die because
|
|
of a ``bad substitution''.
|
|
|
|
@sp 1
|
|
|
|
Solaris' @command{/bin/sh} has a frightening bug in its interpretation
|
|
of this. Imagine you need set a variable to a string containing
|
|
@samp{@}}. This @samp{@}} character confuses Solaris' @command{/bin/sh}
|
|
when the affected variable was already set. This bug can be exercised
|
|
by running:
|
|
|
|
@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!
|
|
@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.
|
|
|
|
@item $@{@var{var}=@var{expanded-value}@}
|
|
@cindex $@{@var{var}=@var{expanded-value}@}
|
|
On Ultrix,
|
|
running
|
|
|
|
@example
|
|
default="yu,yaa"
|
|
: $@{var="$default"@}
|
|
@end example
|
|
|
|
@noindent
|
|
will set @var{var} to @samp{M-yM-uM-,M-yM-aM-a}, i.e., the 8th bit of
|
|
each char will be set. You won't observe the phenomenon using a simple
|
|
@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:
|
|
|
|
@example
|
|
$ @kbd{cat -v <<EOF
|
|
$var
|
|
EOF}
|
|
@end example
|
|
|
|
@noindent
|
|
and
|
|
|
|
@example
|
|
$ @kbd{set | grep '^var=' | cat -v}
|
|
@end example
|
|
|
|
One classic incarnation of this bug is:
|
|
|
|
@example
|
|
default="a b c"
|
|
: $@{list="$default"@}
|
|
for c in $list; do
|
|
echo $c
|
|
done
|
|
@end example
|
|
|
|
@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 @acronym{QNX} 4.25 then sets @var{list} to the @emph{last} item of
|
|
@var{default}!
|
|
|
|
The portable way out consists in using a double assignment, to switch
|
|
the 8th bit twice on Ultrix:
|
|
|
|
@example
|
|
list=$@{list="$default"@}
|
|
@end example
|
|
|
|
@noindent
|
|
@dots{}but beware of the @samp{@}} bug from Solaris (see above). For safety,
|
|
use:
|
|
|
|
@example
|
|
test "$@{var+set@}" = set || var=@var{@{value@}}
|
|
@end example
|
|
|
|
|
|
@item `@var{commands}`
|
|
@cindex `@var{commands}`
|
|
@cindex Command Substitution
|
|
While in general it makes no sense, do not substitute a single builtin
|
|
with side effects, becauase 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:
|
|
|
|
@example
|
|
$ @kbd{pwd}
|
|
/tmp
|
|
$ @kbd{test -z "`cd /`" && pwd}
|
|
/
|
|
@end example
|
|
|
|
@noindent
|
|
The result of @samp{foo=`exit 1`} is left as an exercise to the reader.
|
|
|
|
|
|
@item $(@var{commands})
|
|
@cindex $(@var{commands})
|
|
This construct is meant to replace @samp{`@var{commands}`}; they can be
|
|
nested while this is impossible to do portably with back quotes.
|
|
Unfortunately it is not yet widely supported. Most notably, even recent
|
|
releases of Solaris don't support it:
|
|
|
|
@example
|
|
$ @kbd{showrev -c /bin/sh | grep version}
|
|
Command version: SunOS 5.8 Generic 109324-02 February 2001
|
|
$ @kbd{echo $(echo blah)}
|
|
syntax error: `(' unexpected
|
|
@end example
|
|
|
|
@noindent
|
|
nor does @sc{irix} 6.5's Bourne shell:
|
|
@example
|
|
$ @kbd{uname -a}
|
|
IRIX firebird-image 6.5 07151432 IP22
|
|
$ @kbd{echo $(echo blah)}
|
|
$(echo blah)
|
|
@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.
|
|
|
|
@end table
|
|
|
|
|
|
@node Assignments
|
|
@section 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 sh on Solaris, but @samp{2} with Bash. You must use
|
|
@samp{;} to enforce the order: @samp{foo=1; foo=2; echo $foo}.
|
|
|
|
Don't rely on the following to find @file{subdir/program}:
|
|
|
|
@example
|
|
PATH=subdir$PATH_SEPARATOR$PATH program
|
|
@end example
|
|
|
|
@noindent
|
|
as this does not work with Zsh 3.0.6. Use something like this
|
|
instead:
|
|
|
|
@example
|
|
(PATH=subdir$PATH_SEPARATOR$PATH; export PATH; exec program)
|
|
@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:
|
|
|
|
@example
|
|
$ @kbd{false || foo=bar; echo $?}
|
|
1
|
|
$ @kbd{false || foo=`:`; echo $?}
|
|
0
|
|
@end example
|
|
|
|
@noindent
|
|
and to make things even worse, @acronym{QNX} 4.25 just sets the exit status
|
|
to 0 in any case:
|
|
|
|
@example
|
|
$ @kbd{foo=`exit 1`; echo $?}
|
|
0
|
|
@end example
|
|
|
|
To assign default values, follow this algorithm:
|
|
|
|
@enumerate
|
|
@item
|
|
If the default value is a literal and does not contain any closing
|
|
brace, use:
|
|
|
|
@example
|
|
: $@{var='my literal'@}
|
|
@end example
|
|
|
|
@item
|
|
If the default value contains no closing brace, has to be expanded, and
|
|
the variable being initialized will never be IFS-split (i.e., it's not a
|
|
list), then use:
|
|
|
|
@example
|
|
: $@{var="$default"@}
|
|
@end example
|
|
|
|
@item
|
|
If the default value contains no closing brace, has to be expanded, and
|
|
the variable being initialized will be IFS-split (i.e., it's a list),
|
|
then use:
|
|
|
|
@example
|
|
var=$@{var="$default"@}
|
|
@end example
|
|
|
|
@item
|
|
If the default value contains a closing brace, then use:
|
|
|
|
@example
|
|
test "$@{var+set@}" = set || var='$@{indirection@}'
|
|
@end example
|
|
@end enumerate
|
|
|
|
In most cases @samp{var=$@{var="$default"@}} is fine, but in case of
|
|
doubt, just use the latter. @xref{Shell Substitutions}, items
|
|
@samp{$@{@var{var}:-@var{value}@}} and @samp{$@{@var{var}=@var{value}@}}
|
|
for the rationale.
|
|
|
|
@node Parentheses
|
|
@section Parentheses in Shell Scripts
|
|
|
|
Beware of two opening parentheses in a row, as some shell
|
|
implementations mishandle them. For example, @samp{pdksh} 5.2.14
|
|
misparses the following code:
|
|
|
|
@example
|
|
if ((true) || false); then
|
|
echo ok
|
|
fi
|
|
@end example
|
|
|
|
@noindent
|
|
To work around this problem, insert a space between the two opening
|
|
parentheses. There is a similar problem and workaround with
|
|
@samp{$((}; see @ref{Shell Substitutions}.
|
|
|
|
@acronym{POSIX} requires support for @code{case} patterns with opening
|
|
parentheses like this:
|
|
|
|
@example
|
|
case $filename in
|
|
(*.c) echo "C source code";;
|
|
esac
|
|
@end example
|
|
|
|
@noindent
|
|
but the @code{(} in this example is not portable to many older Bourne
|
|
shell implementations. It can be omitted safely.
|
|
|
|
@node Special Shell Variables
|
|
@section 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, but
|
|
@command{unset} is not portable (@pxref{Limitations of Builtins}) and a
|
|
fallback value is needed. We list these values below.
|
|
|
|
@c Alphabetical order, case insensitive, `A' before `a'.
|
|
@table @code
|
|
@item CDPATH
|
|
@evindex CDPATH
|
|
When this variable is set it specifies a list of directories to search
|
|
when invoking @code{cd} with a relative filename. @acronym{POSIX}
|
|
1003.1-2001 says that if a nonempty directory name from @code{CDPATH}
|
|
is used successfully, @code{cd} prints the resulting absolute
|
|
filename. Unfortunately this output can break idioms like
|
|
@samp{abs=`cd src && pwd`} because @code{abs} receives the path twice.
|
|
Also, many shells do not conform to this part of @acronym{POSIX}; for
|
|
example, @command{zsh} prints the result only if a directory name
|
|
other than @file{.} was chosen from @code{CDPATH}.
|
|
|
|
In practice the shells that have this problem also support
|
|
@command{unset}, so you can work around the problem as follows:
|
|
|
|
@example
|
|
(unset CDPATH) >/dev/null 2>&1 && unset CDPATH
|
|
@end example
|
|
|
|
Autoconf-generated scripts automatically unset @code{CDPATH} if
|
|
possible, so you need not worry about this problem in those scripts.
|
|
|
|
@item IFS
|
|
@evindex IFS
|
|
Don't set the first character of @code{IFS} to backslash. Indeed,
|
|
Bourne shells use the first character (backslash) when joining the
|
|
components in @samp{"$@@"} and some shells then re-interpret (!) the
|
|
backslash escapes, so you can end up with backspace and other strange
|
|
characters.
|
|
|
|
The proper value for @code{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{@@*}.
|
|
|
|
@item LANG
|
|
@itemx LC_ALL
|
|
@itemx LC_COLLATE
|
|
@itemx LC_CTYPE
|
|
@itemx LC_MESSAGES
|
|
@itemx LC_MONETARY
|
|
@itemx LC_NUMERIC
|
|
@itemx LC_TIME
|
|
@evindex LANG
|
|
@evindex LC_ALL
|
|
@evindex LC_COLLATE
|
|
@evindex LC_CTYPE
|
|
@evindex LC_MESSAGES
|
|
@evindex LC_MONETARY
|
|
@evindex LC_NUMERIC
|
|
@evindex LC_TIME
|
|
|
|
Autoconf-generated scripts normally set all these variables to
|
|
@samp{C} because so much configuration code assumes the C locale and
|
|
@acronym{POSIX} requires that locale environment variables be set to
|
|
@samp{C} if the C locale is desired. However, some older, nonstandard
|
|
systems (notably @acronym{SCO}) break if locale environment variables
|
|
are set to @samp{C}, so when running on these systems
|
|
Autoconf-generated scripts unset the variables instead.
|
|
|
|
@item LANGUAGE
|
|
@evindex LANGUAGE
|
|
|
|
@env{LANGUAGE} is not specified by @acronym{POSIX}, but it is a @acronym{GNU}
|
|
extension that overrides @env{LC_ALL} in some cases, so
|
|
Autoconf-generated scripts set it too.
|
|
|
|
@item LC_ADDRESS
|
|
@itemx LC_IDENTIFICATION
|
|
@itemx LC_MEASUREMENT
|
|
@itemx LC_NAME
|
|
@itemx LC_PAPER
|
|
@itemx LC_TELEPHONE
|
|
@evindex LC_ADDRESS
|
|
@evindex LC_IDENTIFICATION
|
|
@evindex LC_MEASUREMENT
|
|
@evindex LC_NAME
|
|
@evindex LC_PAPER
|
|
@evindex LC_TELEPHONE
|
|
|
|
These locale environment variables are @acronym{GNU} extensions. They
|
|
are treated like their @acronym{POSIX} brethren (@env{LC_COLLATE},
|
|
etc.)@: as described above.
|
|
|
|
@item LINENO
|
|
@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.
|
|
Autoconf attempts to execute @command{configure} with a modern shell.
|
|
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.
|
|
|
|
You should not rely on @code{LINENO} within @command{eval}, as the
|
|
behavior differs in practice. Also, the possibility of the Sed
|
|
prepass means that you should not rely on @code{$LINENO} when quoted,
|
|
when in here-documents, or when in long commands that cross line
|
|
boundaries. Subshells should be OK, though. In the following
|
|
example, lines 1, 6, and 9 are portable, but the other instances of
|
|
@code{LINENO} are not:
|
|
|
|
@example
|
|
@group
|
|
$ @kbd{cat lineno}
|
|
echo 1. $LINENO
|
|
cat <<EOF
|
|
3. $LINENO
|
|
4. $LINENO
|
|
EOF
|
|
( echo 6. $LINENO )
|
|
eval 'echo 7. $LINENO'
|
|
echo 8. '$LINENO'
|
|
echo 9. $LINENO '
|
|
10.' $LINENO
|
|
@end group
|
|
@group
|
|
$ @kbd{bash-2.05 lineno}
|
|
1. 1
|
|
3. 2
|
|
4. 2
|
|
6. 6
|
|
7. 1
|
|
8. $LINENO
|
|
9. 9
|
|
10. 9
|
|
@end group
|
|
@group
|
|
$ @kbd{zsh-3.0.6 lineno}
|
|
1. 1
|
|
3. 2
|
|
4. 2
|
|
6. 6
|
|
7. 7
|
|
8. $LINENO
|
|
9. 9
|
|
10. 9
|
|
@end group
|
|
@group
|
|
$ @kbd{pdksh-5.2.14 lineno}
|
|
1. 1
|
|
3. 2
|
|
4. 2
|
|
6. 6
|
|
7. 0
|
|
8. $LINENO
|
|
9. 9
|
|
10. 9
|
|
@end group
|
|
@group
|
|
$ @kbd{sed '=' <lineno |}
|
|
> @kbd{ sed '}
|
|
> @kbd{ N}
|
|
> @kbd{ s,$,-,}
|
|
> @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
|
|
3. 3
|
|
4. 4
|
|
6. 6
|
|
7. 7
|
|
8. 8
|
|
9. 9
|
|
10. 10
|
|
@end group
|
|
@end example
|
|
|
|
|
|
@item NULLCMD
|
|
@evindex NULLCMD
|
|
When executing the command @samp{>foo}, @command{zsh} executes
|
|
@samp{$NULLCMD >foo}. The Bourne shell considers @code{NULLCMD} to be
|
|
@samp{:}, while @command{zsh}, even in Bourne shell compatibility mode,
|
|
sets @code{NULLCMD} to @samp{cat}. If you forgot to set @code{NULLCMD},
|
|
your script might be suspended waiting for data on its standard input.
|
|
|
|
@item ENV
|
|
@itemx MAIL
|
|
@itemx MAILPATH
|
|
@itemx PS1
|
|
@itemx PS2
|
|
@itemx PS4
|
|
@evindex ENV
|
|
@evindex MAIL
|
|
@evindex MAILPATH
|
|
@evindex PS1
|
|
@evindex PS2
|
|
@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 @sc{uwin} @command{ksh}) 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, Autoconf-generated scripts do something like this:
|
|
|
|
@example
|
|
(unset ENV) >/dev/null 2>&1 && unset ENV MAIL MAILPATH
|
|
PS1='$ '
|
|
PS2='> '
|
|
PS4='+ '
|
|
@end example
|
|
|
|
@item PWD
|
|
@evindex PWD
|
|
@acronym{POSIX} 1003.1-2001 requires that @command{cd} and
|
|
@command{pwd} must update the @env{PWD} environment variable to point
|
|
to the logical path to 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} will
|
|
point to the wrong directory. Use @samp{`pwd`} rather than
|
|
@samp{$PWD}.
|
|
|
|
@item status
|
|
@evindex status
|
|
This variable is an alias to @samp{$?} for @code{zsh} (at least 3.1.6),
|
|
hence read-only. Do not use it.
|
|
|
|
@item PATH_SEPARATOR
|
|
@evindex PATH_SEPARATOR
|
|
If it is not set, @command{configure} will detect the appropriate path
|
|
separator for the build system and set the @code{PATH_SEPARATOR} output
|
|
variable accordingly.
|
|
|
|
On DJGPP systems, the @code{PATH_SEPARATOR} environment variable can be
|
|
set to either @samp{:} or @samp{;} to control the path separator
|
|
@command{bash} uses to set up certain environment variables (such as
|
|
@code{PATH}). Since this only works inside @command{bash}, you want
|
|
@command{configure} to detect the regular @acronym{DOS} path separator
|
|
(@samp{;}), so it can be safely substituted in files that may not support
|
|
@samp{;} as path separator. So it is recommended to either unset this
|
|
variable or set it to @samp{;}.
|
|
|
|
@item RANDOM
|
|
@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 @sc{irix} 6.5 the value changes all
|
|
the time. This can be observed by using @command{set}.
|
|
@end table
|
|
|
|
|
|
@node Limitations of Builtins
|
|
@section 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 have a very different behavior with arguments
|
|
starting with a dash. For instance, 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.
|
|
|
|
@table @asis
|
|
@item @command{.}
|
|
@prindex @command{.}
|
|
Use @command{.} only with regular files (use @samp{test -f}). Bash
|
|
2.03, for instance, chokes on @samp{. /dev/null}. Also, remember that
|
|
@command{.} uses @env{PATH} if its argument contains no slashes, so if
|
|
you want to use @command{.} on a file @file{foo} in the current
|
|
directory, you must use @samp{. ./foo}.
|
|
|
|
@item @command{!}
|
|
@prindex @command{!}
|
|
You can't use @command{!}; you'll have to rewrite your code.
|
|
|
|
|
|
@item @command{break}
|
|
@c ------------------
|
|
@prindex @command{break}
|
|
The use of @samp{break 2} etc.@: is safe.
|
|
|
|
|
|
@item @command{cd}
|
|
@c ---------------------------------
|
|
@prindex @command{cd}
|
|
@acronym{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
|
|
@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 @acronym{POSIX} default behavior means that, for example,
|
|
@samp{ls ..} and @samp{cd ..} may refer to different directories if
|
|
the current logical directory is a symbolic link. It is safe to use
|
|
@command{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.
|
|
|
|
Also please see the discussion of the @command{pwd} command.
|
|
|
|
|
|
@item @command{case}
|
|
@c -----------------
|
|
@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.
|
|
|
|
Because of a bug in its @code{fnmatch}, @command{bash} fails to properly
|
|
handle backslashes in character classes:
|
|
|
|
@example
|
|
bash-2.02$ @kbd{case /tmp in [/\\]*) echo OK;; esac}
|
|
bash-2.02$
|
|
@end example
|
|
|
|
@noindent
|
|
This is extremely unfortunate, since you are likely to use this code to
|
|
handle @sc{unix} or @sc{ms-dos} absolute paths. To work around this
|
|
bug, always put the backslash first:
|
|
|
|
@example
|
|
bash-2.02$ @kbd{case '\TMP' in [\\/]*) echo OK;; esac}
|
|
OK
|
|
bash-2.02$ @kbd{case /tmp in [\\/]*) echo OK;; esac}
|
|
OK
|
|
@end example
|
|
|
|
Some shells, such as Ash 0.3.8, are confused by an empty
|
|
@code{case}/@code{esac}:
|
|
|
|
@example
|
|
ash-0.3.8 $ @kbd{case foo in esac;}
|
|
@error{}Syntax error: ";" unexpected (expecting ")")
|
|
@end example
|
|
|
|
Many shells still do not support parenthesized cases, which is a pity
|
|
for those of us using tools that rely on balanced parentheses. For
|
|
instance, Solaris 8's Bourne shell:
|
|
|
|
@example
|
|
$ @kbd{case foo in (foo) echo foo;; esac}
|
|
@error{}syntax error: `(' unexpected
|
|
@end example
|
|
|
|
|
|
@item @command{echo}
|
|
@c -----------------
|
|
@prindex @command{echo}
|
|
The simple @code{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. New applications
|
|
which are not aiming at portability should use @samp{printf} instead of
|
|
@samp{echo}.
|
|
|
|
Don't expect any option. @xref{Preset Output Variables}, @code{ECHO_N}
|
|
etc.@: for a means to simulate @option{-n}.
|
|
|
|
Do not use backslashes in the arguments, as there is no consensus on
|
|
their handling. On @samp{echo '\n' | wc -l}, the @command{sh} of
|
|
Digital Unix 4.0 and @acronym{MIPS RISC/OS} 4.52, answer 2, but the Solaris'
|
|
@command{sh}, Bash, and Zsh (in @command{sh} emulation mode) report 1.
|
|
Please note that the problem is truly @command{echo}: all the shells
|
|
understand @samp{'\n'} as the string composed of a backslash and an
|
|
@samp{n}.
|
|
|
|
Because of these problems, do not pass a string containing arbitrary
|
|
characters to @command{echo}. For example, @samp{echo "$foo"} is safe
|
|
if you know that @var{foo}'s value cannot contain backslashes and cannot
|
|
start with @samp{-}, but otherwise you should use a here-document like
|
|
this:
|
|
|
|
@example
|
|
cat <<EOF
|
|
$foo
|
|
EOF
|
|
@end example
|
|
|
|
|
|
@item @command{exit}
|
|
@c -----------------
|
|
@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}.
|
|
|
|
@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$
|
|
@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 8 @command{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
|
|
@code{exit 1}. Instead of calling @code{exit} directly, use the
|
|
@code{AC_MSG_ERROR} macro that has a workaround for this problem.
|
|
|
|
|
|
@item @command{export}
|
|
@c -------------------
|
|
@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 2.5, @sc{irix} 6.3, @sc{irix} 5.2,
|
|
@acronym{AIX} 4.1.5, and Digital @sc{unix} 4.0, forget to
|
|
@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:
|
|
|
|
@example
|
|
#! /bin/sh
|
|
echo $FOO
|
|
FOO=bar
|
|
echo $FOO
|
|
exec /bin/sh $0
|
|
@end example
|
|
|
|
@noindent
|
|
when run with @samp{FOO=foo} in the environment, these shells will print
|
|
alternately @samp{foo} and @samp{bar}, although it should only print
|
|
@samp{foo} and then a sequence of @samp{bar}s.
|
|
|
|
Therefore you should @command{export} again each environment variable
|
|
that you update.
|
|
|
|
|
|
@item @command{false}
|
|
@c ------------------
|
|
@prindex @command{false}
|
|
Don't expect @command{false} to exit with status 1: in the native Bourne
|
|
shell of Solaris 8 it exits with status 255.
|
|
|
|
|
|
@item @command{for}
|
|
@c ----------------
|
|
@prindex @command{for}
|
|
To loop over positional arguments, use:
|
|
|
|
@example
|
|
for arg
|
|
do
|
|
echo "$arg"
|
|
done
|
|
@end example
|
|
|
|
@noindent
|
|
You may @emph{not} leave the @code{do} on the same line as @code{for},
|
|
since some shells improperly grok:
|
|
|
|
@example
|
|
for arg; do
|
|
echo "$arg"
|
|
done
|
|
@end example
|
|
|
|
If you want to explicitly refer to the positional arguments, given the
|
|
@samp{$@@} bug (@pxref{Shell Substitutions}), use:
|
|
|
|
@example
|
|
for arg in $@{1+"$@@"@}; do
|
|
echo "$arg"
|
|
done
|
|
@end example
|
|
|
|
@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.
|
|
|
|
|
|
@item @command{if}
|
|
@c ---------------
|
|
@prindex @command{if}
|
|
Using @samp{!} is not portable. Instead of:
|
|
|
|
@example
|
|
if ! cmp -s file file.new; then
|
|
mv file.new file
|
|
fi
|
|
@end example
|
|
|
|
@noindent
|
|
use:
|
|
|
|
@example
|
|
if cmp -s file file.new; then :; else
|
|
mv file.new file
|
|
fi
|
|
@end example
|
|
|
|
There are shells that do not reset the exit status from an @command{if}:
|
|
|
|
@example
|
|
$ @kbd{if (exit 42); then true; fi; echo $?}
|
|
42
|
|
@end example
|
|
|
|
@noindent
|
|
whereas a proper shell should have printed @samp{0}. This is especially
|
|
bad in Makefiles since it produces false failures. This is why properly
|
|
written Makefiles, such as Automake's, have such hairy constructs:
|
|
|
|
@example
|
|
if test -f "$file"; then
|
|
install "$file" "$dest"
|
|
else
|
|
:
|
|
fi
|
|
@end example
|
|
|
|
|
|
@item @command{printf}
|
|
@c ------------------
|
|
@prindex @command{printf}
|
|
A format string starting with a @samp{-} can cause problems.
|
|
@command{bash} (eg. 2.05b) will interpret it as an options string and
|
|
give an error. And @samp{--} to mark the end of options is not good
|
|
in the NetBSD Almquist shell (eg. 0.4.6) which will take that
|
|
literally as the format string. Putting the @samp{-} in a @samp{%c}
|
|
or @samp{%s} is probably the easiest way to avoid doubt,
|
|
|
|
@example
|
|
printf %s -foo
|
|
@end example
|
|
|
|
|
|
@item @command{pwd}
|
|
@c ----------------
|
|
@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.
|
|
|
|
@acronym{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
|
|
@option{-P} behavior.
|
|
|
|
Portable scripts should assume neither option is supported, and should
|
|
assume neither behavior is the default. Also, on many hosts
|
|
@samp{/bin/pwd} is equivalent to @samp{pwd -P}, but @acronym{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:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Logical names are what the user specified.
|
|
@item
|
|
Physical names may not be portable from one installation
|
|
host to another due to network filesystem gymnastics.
|
|
@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.
|
|
@end itemize
|
|
|
|
Also please see the discussion of the @command{cd} command.
|
|
|
|
|
|
@item @command{set}
|
|
@c ----------------
|
|
@prindex @command{set}
|
|
This 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 most shells simply stop the option
|
|
processing as soon as a non-option argument is found. Therefore, use
|
|
@samp{dummy} or simply @samp{x} to end the option processing, and use
|
|
@command{shift} to pop it out:
|
|
|
|
@example
|
|
set x $my_list; shift
|
|
@end example
|
|
|
|
Some shells have the "opposite" problem of not recognizing all options
|
|
(e.g., @samp{set -e -x} assigns @samp{-x} to the command line). It is
|
|
better to elide these:
|
|
|
|
@example
|
|
set -ex
|
|
@end example
|
|
|
|
|
|
@item @command{shift}
|
|
@c ------------------
|
|
@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 @acronym{MIPS
|
|
RISC/OS} 4.52 refuses to do it.
|
|
|
|
|
|
@item @command{source}
|
|
@c -------------------
|
|
@prindex @command{source}
|
|
This command is not portable, as @acronym{POSIX} does not require it; use
|
|
@command{.} instead.
|
|
|
|
|
|
@item @command{test}
|
|
@c -----------------
|
|
@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.
|
|
|
|
If you need to make multiple checks using @code{test}, combine them with
|
|
the shell operators @samp{&&} and @samp{||} instead of using the
|
|
@code{test} operators @option{-a} and @option{-o}. On System V, the
|
|
precedence of @option{-a} and @option{-o} is wrong relative to the unary
|
|
operators; consequently, @acronym{POSIX} does not specify them, so using them
|
|
is nonportable. If you combine @samp{&&} and @samp{||} in the same
|
|
statement, keep in mind that they have equal precedence.
|
|
|
|
You may use @samp{!} with @command{test}, but not with @command{if}:
|
|
@samp{test ! -r foo || exit 1}.
|
|
|
|
|
|
@item @command{test} (files)
|
|
@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} or
|
|
@samp{test -r}. Do not use @samp{test -x}, because 4.3@acronym{BSD} does not
|
|
have it. Do not use @samp{test -e} either, because Solaris 2.5 does not
|
|
have it. To test for symbolic links on systems that have them, use
|
|
@samp{test -h} rather than @samp{test -L}; either form conforms to
|
|
@acronym{POSIX} 1003.1-2001, but older shells like Solaris 8
|
|
@code{/bin/sh} support only @option{-h}.
|
|
|
|
@item @command{test} (strings)
|
|
@c ---------------------------
|
|
Avoid @samp{test "@var{string}"}, in particular if @var{string} might
|
|
start with a dash, since @code{test} might interpret its argument as an
|
|
option (e.g., @samp{@var{string} = "-n"}).
|
|
|
|
Contrary to a common belief, @samp{test -n @var{string}} and
|
|
@samp{test -z @var{string}} @strong{are} portable. Nevertheless many
|
|
shells (such as Solaris 2.5, @acronym{AIX} 3.2, @sc{unicos} 10.0.0.6,
|
|
Digital Unix 4 etc.) have bizarre precedence and may be confused if
|
|
@var{string} looks like an operator:
|
|
|
|
@example
|
|
$ @kbd{test -n =}
|
|
test: argument expected
|
|
@end example
|
|
|
|
If there are risks, use @samp{test "x@var{string}" = x} or @samp{test
|
|
"x@var{string}" != x} instead.
|
|
|
|
It is common to find variations of the following idiom:
|
|
|
|
@example
|
|
test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" &&
|
|
@var{action}
|
|
@end example
|
|
|
|
@noindent
|
|
to take an action when a token matches a given pattern. Such constructs
|
|
should always be avoided by using:
|
|
|
|
@example
|
|
echo "$ac_feature" | grep '[^-a-zA-Z0-9_]' >/dev/null 2>&1 &&
|
|
@var{action}
|
|
@end example
|
|
|
|
@noindent
|
|
Use @code{case} where possible since it is faster, being a shell builtin:
|
|
|
|
|
|
@example
|
|
case $ac_feature in
|
|
*[!-a-zA-Z0-9_]*) @var{action};;
|
|
esac
|
|
@end example
|
|
|
|
Alas, negated character classes are probably not portable, although no
|
|
shell is known to not support the @acronym{POSIX} syntax @samp{[!@dots{}]}
|
|
(when in interactive mode, @command{zsh} is confused by the
|
|
@samp{[!@dots{}]} syntax and looks for an event in its history because of
|
|
@samp{!}). Many shells do not support the alternative syntax
|
|
@samp{[^@dots{}]} (Solaris, Digital Unix, etc.).
|
|
|
|
One solution can be:
|
|
|
|
@example
|
|
expr "$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
|
|
@var{action}
|
|
@end example
|
|
|
|
@noindent
|
|
or better yet
|
|
|
|
@example
|
|
expr "x$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
|
|
@var{action}
|
|
@end example
|
|
|
|
@samp{expr "X@var{foo}" : "X@var{bar}"} is more robust than @samp{echo
|
|
"X@var{foo}" | grep "^X@var{bar}"}, because it avoids problems when
|
|
@samp{@var{foo}} contains backslashes.
|
|
|
|
|
|
@item @command{trap}
|
|
@c -----------------
|
|
@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).
|
|
|
|
Although @acronym{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
|
|
@command{exit} itself?''
|
|
|
|
Bash considers @command{exit} to be the last command, while Zsh and
|
|
Solaris 8 @command{sh} consider that when the trap is run it is
|
|
@emph{still} in the @command{exit}, hence it is the previous exit status
|
|
that the trap receives:
|
|
|
|
@example
|
|
$ @kbd{cat trap.sh}
|
|
trap 'echo $?' 0
|
|
(exit 42); exit 0
|
|
$ @kbd{zsh trap.sh}
|
|
42
|
|
$ @kbd{bash trap.sh}
|
|
0
|
|
@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.
|
|
|
|
The shell in Free@acronym{BSD} 4.0 has the following bug: @samp{$?} is
|
|
reset to 0 by empty lines if the code is inside @command{trap}.
|
|
|
|
@example
|
|
$ @kbd{trap 'false}
|
|
|
|
echo $?' 0
|
|
$ @kbd{exit}
|
|
0
|
|
@end example
|
|
|
|
@noindent
|
|
Fortunately, this bug only affects @command{trap}.
|
|
|
|
@item @command{true}
|
|
@c -----------------
|
|
@prindex @command{true}
|
|
@c Info cannot handle `:' in index entries.
|
|
@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:
|
|
|
|
@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}.
|
|
@end quotation
|
|
|
|
|
|
@item @command{unset}
|
|
@c ------------------
|
|
@prindex @command{unset}
|
|
You cannot assume the support of @command{unset}. Nevertheless, because
|
|
it is extremely useful to disable embarrassing variables such as
|
|
@code{PS1}, you can test for its existence and use
|
|
it @emph{provided} you give a neutralizing value when @command{unset} is
|
|
not supported:
|
|
|
|
@example
|
|
if (unset FOO) >/dev/null 2>&1; then
|
|
unset=unset
|
|
else
|
|
unset=false
|
|
fi
|
|
$unset PS1 || PS1='$ '
|
|
@end example
|
|
|
|
@xref{Special Shell Variables}, for some neutralizing values. Also, see
|
|
@ref{Limitations of Builtins}, documentation of @command{export}, for
|
|
the case of environment variables.
|
|
@end table
|
|
|
|
@node Limitations of Usual Tools
|
|
@section 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.
|
|
|
|
@table @asis
|
|
@item @command{awk}
|
|
@c ----------------
|
|
@prindex @command{awk}
|
|
Don't leave white spaces before the parentheses in user functions calls;
|
|
@acronym{GNU} awk will reject it:
|
|
|
|
@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!
|
|
@end example
|
|
|
|
If you want your program to be deterministic, don't depend on @code{for}
|
|
on arrays:
|
|
|
|
@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
|
|
@end example
|
|
|
|
Some AWK, such as HPUX 11.0's native one, have regex engines fragile to
|
|
inner anchors:
|
|
|
|
@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
|
|
@end example
|
|
|
|
@noindent
|
|
Either do not depend on such patterns (i.e., use @samp{/^(.*foo|bar)/},
|
|
or use a simple test to reject such AWK@.
|
|
|
|
|
|
@item @command{cat}
|
|
@c ----------------
|
|
@prindex @command{cat}
|
|
Don't rely on any option. The option @option{-v}, which displays
|
|
non-printing characters, @emph{seems} portable, though.
|
|
|
|
|
|
@item @command{cc}
|
|
@c ---------------
|
|
When a compilation such as @samp{cc foo.c -o foo} fails, some compilers
|
|
(such as @sc{cds} on Reliant @sc{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} will appear to succeed, but in fact does
|
|
nothing.
|
|
|
|
The default executable, produced by @samp{cc foo.c}, can be
|
|
|
|
@itemize
|
|
@item @file{a.out} --- usual Unix convention.
|
|
@item @file{b.out} --- i960 compilers (including @command{gcc}).
|
|
@item @file{a.exe} --- DJGPP port of @command{gcc}.
|
|
@item @file{a_out.exe} --- GNV @command{cc} wrapper for DEC C on OpenVMS.
|
|
@item @file{foo.exe} --- various MS-DOS compilers.
|
|
@end itemize
|
|
|
|
|
|
@item @command{cmp}
|
|
@c ----------------
|
|
@prindex @command{cmp}
|
|
@command{cmp} performs a raw data comparison of two files, while
|
|
@command{diff} compares two text files. Therefore, if you might compare
|
|
DOS files, even if only checking whether two files are different, use
|
|
@command{diff} to avoid spurious differences due to differences of
|
|
newline encoding.
|
|
|
|
|
|
@item @command{cp}
|
|
@c ---------------
|
|
@prindex @command{cp}
|
|
@cindex timestamp resolution
|
|
Traditionally, file timestamps had 1-second resolution, and @samp{cp
|
|
-p} copied the timestamps exactly. However, many modern filesystems
|
|
have timestamps with 1-nanosecond resolution. Unfortunately, @samp{cp
|
|
-p} implementations truncate timestamps when copying files, so this
|
|
can result in the destination file appearing 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
|
|
@code{utime}, which has 1-second resolution, but some newer
|
|
@command{cp} implementations use @code{utimes}, which has
|
|
1-microsecond resolution. These newer implementations include GNU
|
|
coreutils 5.0.91 or later, and Solaris 8 (sparc) patch 109933-02 or
|
|
later. Unfortunately as of September 2003 there is still no system
|
|
call to set time stamps to the full nanosecond resolution.
|
|
|
|
@c This is thanks to Ian.
|
|
SunOS @command{cp} does not support @option{-f}, although its
|
|
@command{mv} does. It's possible to deduce why @command{mv} and
|
|
@command{cp} are different with respect to @option{-f}. @command{mv}
|
|
prompts by default before overwriting a read-only file. @command{cp}
|
|
does not. Therefore, @command{mv} requires a @option{-f} option, but
|
|
@command{cp} does not. @command{mv} and @command{cp} behave differently
|
|
with respect to read-only files because the simplest form of
|
|
@command{cp} cannot overwrite a read-only file, but the simplest form of
|
|
@command{mv} can. This is because @command{cp} opens the target for
|
|
write access, whereas @command{mv} simply calls @code{link} (or, in
|
|
newer systems, @code{rename}).
|
|
@c Ian said: ``I don't think -p or -r are portable''!!! How can you live
|
|
@c without -r???
|
|
|
|
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 SysV any user can chown files to any other user, and SysV also had a
|
|
non-sticky @file{/tmp}. That undoubtedly derives from the heritage of
|
|
SysV 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.
|
|
|
|
Linux by default follows BSD, but it can be configured to allow
|
|
@command{chown}. HP-UX as an alternate example follows SysV, but it can
|
|
be configured to use the modern security model and disallow
|
|
@command{chown}. Since it is an administrator configurable parameter
|
|
you can't use the name of the kernel as an indicator of the behavior.
|
|
|
|
|
|
|
|
@item @command{date}
|
|
@c -----------------
|
|
@prindex @command{date}
|
|
Some versions of @command{date} do not recognize special % directives,
|
|
and unfortunately, instead of complaining, they just pass them through,
|
|
and exit with success:
|
|
|
|
@example
|
|
$ @kbd{uname -a}
|
|
OSF1 medusa.sis.pasteur.fr V5.1 732 alpha
|
|
$ @kbd{date "+%s"}
|
|
%s
|
|
@end example
|
|
|
|
|
|
@item @command{diff}
|
|
@c -----------------
|
|
@prindex @command{diff}
|
|
Option @option{-u} is nonportable.
|
|
|
|
Some implementations, such as Tru64's, fail when comparing to
|
|
@file{/dev/null}. Use an empty file instead.
|
|
|
|
|
|
@item @command{dirname}
|
|
@c --------------------
|
|
@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:
|
|
|
|
@example
|
|
dir=`dirname "$file"` # This is not portable.
|
|
dir=`AS_DIRNAME(["$file"])` # This is more portable.
|
|
@end example
|
|
|
|
@noindent
|
|
This handles a few subtleties in the standard way required by
|
|
@acronym{POSIX}. For example, under UN*X, should @samp{dirname //1} give
|
|
@samp{/}? Paul Eggert answers:
|
|
|
|
@quotation
|
|
No, under some older flavors of Unix, leading @samp{//} is a special
|
|
path name: it refers to a ``super-root'' and is used to access other
|
|
machines' files. Leading @samp{///}, @samp{////}, etc.@: are equivalent
|
|
to @samp{/}; but leading @samp{//} is special. I think this tradition
|
|
started with Apollo Domain/OS, an OS that is still in use on some older
|
|
hosts.
|
|
|
|
@acronym{POSIX} allows but does not require the special treatment for
|
|
@samp{//}. It says that the behavior of dirname on path names of the
|
|
form @samp{//([^/]+/*)?} is implementation defined. In these cases,
|
|
@acronym{GNU} @command{dirname} returns @samp{/}, but it's more
|
|
portable to return @samp{//} as this works even on those older flavors
|
|
of Unix.
|
|
@end quotation
|
|
|
|
|
|
@item @command{egrep}
|
|
@c ------------------
|
|
@prindex @command{egrep}
|
|
@acronym{POSIX} 1003.1-2001 no longer requires @command{egrep},
|
|
but many older hosts do not yet support the @acronym{POSIX}
|
|
replacement @code{grep -E}. To work around this problem, invoke
|
|
@code{AC_PROG_EGREP} and then use @code{$EGREP}.
|
|
|
|
The empty alternative is not portable, use @samp{?} instead. For
|
|
instance with Digital Unix v5.0:
|
|
|
|
@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
|
|
@end example
|
|
|
|
@command{$EGREP} also suffers the limitations of @command{grep}.
|
|
|
|
@item @command{expr}
|
|
@c -----------------
|
|
@prindex @command{expr}
|
|
No @command{expr} keyword starts with @samp{x}, so use @samp{expr
|
|
x"@var{word}" : 'x@var{regex}'} to keep @command{expr} from
|
|
misinterpreting @var{word}.
|
|
|
|
Don't use @code{length}, @code{substr}, @code{match} and @code{index}.
|
|
|
|
@item @command{expr} (@samp{|})
|
|
@prindex @command{expr} (@samp{|})
|
|
You can use @samp{|}. Although @acronym{POSIX} does require that @samp{expr
|
|
''} return the empty string, it does not specify the result when you
|
|
@samp{|} together the empty string (or zero) with the empty string. For
|
|
example:
|
|
|
|
@example
|
|
expr '' \| ''
|
|
@end example
|
|
|
|
@acronym{GNU}/Linux and @acronym{POSIX}.2-1992 return the empty string
|
|
for this case, but traditional @sc{unix} returns @samp{0} (Solaris is
|
|
one such example). In @acronym{POSIX}.1-2001, the specification has
|
|
been changed to match traditional @sc{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:
|
|
|
|
@example
|
|
expr bar : foo \| foo : bar
|
|
@end example
|
|
|
|
@noindent
|
|
Avoid this portability problem by avoiding the empty string.
|
|
|
|
|
|
@item @command{expr} (@samp{:})
|
|
@c ----------------------------
|
|
@prindex @command{expr}
|
|
Don't use @samp{\?}, @samp{\+} and @samp{\|} in patterns, as they are
|
|
not supported on Solaris.
|
|
|
|
The @acronym{POSIX} standard is ambiguous as to whether
|
|
@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 @acronym{QNX} 4.25 native
|
|
@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:
|
|
|
|
@example
|
|
expr a : '\(b\)' \| ''
|
|
@end example
|
|
|
|
@noindent
|
|
Unfortunately this behaves exactly as the original expression; see the
|
|
@samp{@command{expr} (@samp{:})} entry for more information.
|
|
|
|
Older @command{expr} implementations (e.g., SunOS 4 @command{expr} and
|
|
Solaris 8 @command{/usr/ucb/expr}) have a silly length limit that causes
|
|
@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
|
|
@command{expr} fails.
|
|
|
|
Don't leave, there is some more!
|
|
|
|
The @acronym{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!
|
|
|
|
@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
|
|
@end example
|
|
|
|
@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
|
|
@command{sed}), since you may get twice the result. For instance
|
|
|
|
@example
|
|
$ @kbd{expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/'}
|
|
@end example
|
|
|
|
@noindent
|
|
will output @samp{a} on most hosts, but @samp{aa} on @acronym{QNX} 4.25. A
|
|
simple workaround consists in testing @command{expr} and use a variable
|
|
set to @command{expr} or to @command{false} according to the result.
|
|
|
|
|
|
@item @command{fgrep}
|
|
@c ------------------
|
|
@prindex @command{fgrep}
|
|
@acronym{POSIX} 1003.1-2001 no longer requires @command{fgrep},
|
|
but many older hosts do not yet support the @acronym{POSIX}
|
|
replacement @code{grep -F}. To work around this problem, invoke
|
|
@code{AC_PROG_FGREP} and then use @code{$FGREP}.
|
|
|
|
|
|
@item @command{find}
|
|
@c -----------------
|
|
The option @option{-maxdepth} seems to be @acronym{GNU} specific.
|
|
Tru64 v5.1, Net@acronym{BSD} 1.5 and Solaris 2.5 @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:
|
|
|
|
@example
|
|
$ @kbd{touch foo}
|
|
$ @kbd{find . -name foo -exec echo "@{@}-@{@}" \;}
|
|
@{@}-@{@}
|
|
@end example
|
|
|
|
@noindent
|
|
while @acronym{GNU} @command{find} reports @samp{./foo-./foo}.
|
|
|
|
|
|
@item @command{grep}
|
|
@c -----------------
|
|
@prindex @command{grep}
|
|
Don't use @samp{grep -s} to suppress output, because @samp{grep -s} on
|
|
System V does not suppress output, only error messages. 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.
|
|
|
|
Don't use multiple regexps with @option{-e}, as some @code{grep} will only
|
|
honor the last pattern (e.g., @sc{irix} 6.5 and Solaris 2.5.1). Anyway,
|
|
Stardent Vistra SVR4 @code{grep} lacks @option{-e}@dots{} Instead, use
|
|
extended regular expressions and alternation.
|
|
|
|
Don't rely on @option{-w}, as Irix 6.5.16m's @command{grep} does not
|
|
support it.
|
|
|
|
|
|
@item @command{ln}
|
|
@c ---------------
|
|
@prindex @command{ln}
|
|
@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, @command{ln} emulates soft links
|
|
to executables by generating a stub that in turn calls the real
|
|
program. This feature also works with nonexistent files like in the
|
|
Unix spec. So @samp{ln -s file link} will generate @file{link.exe},
|
|
which will attempt 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 symlink support.
|
|
|
|
|
|
@item @command{ls}
|
|
@c ---------------
|
|
@prindex @command{ls}
|
|
@cindex Listing directories
|
|
The portable options are @option{-acdilrtu}. Modern practice is for
|
|
@option{-l} to output both owner and group, but traditional
|
|
@command{ls} omits the group.
|
|
|
|
@c From Bruce Lilly:
|
|
@c
|
|
@c # telnet dim
|
|
@c [...]
|
|
@c UNIX System V (TWG-TCP/IP) (dim.blilly.com)
|
|
@c [...]
|
|
@c $ mkdir foo
|
|
@c $ cd foo
|
|
@c $ /bin/ls a.exe 2>/dev/null
|
|
@c a.exe not found
|
|
@c $ what /bin/ls
|
|
@c /bin/ls:
|
|
@c fndcmd:fndcmd.sl 1.68
|
|
@c $ uname -a
|
|
@c UNIX dim SYSTEM5 3.51m mc68k
|
|
@c
|
|
@c It's an AT&T 3B1. See http://www.faqs.org/faqs/3b1-faq/ or any
|
|
@c mirror of the 3B1 FAQ. It's actually SVR2.2.
|
|
Modern practice is for all diagnostics to go to standard error, but
|
|
traditional @samp{ls foo} prints the message @samp{foo not found} to
|
|
standard output if @file{foo} does not exist. Be careful when writing
|
|
shell commands like @samp{sources=`ls *.c 2>/dev/null`}, since with
|
|
traditional @command{ls} this is equivalent to @samp{sources="*.c not
|
|
found"} if there are no @samp{.c} files.
|
|
|
|
|
|
@item @command{mkdir}
|
|
@c ------------------
|
|
@prindex @command{mkdir}
|
|
@cindex Making directories
|
|
None of @command{mkdir}'s options are portable. Instead of
|
|
@samp{mkdir -p @var{filename}}, you should use use
|
|
@code{AS_MKDIR_P(@var{filename})} (@pxref{Programming in M4sh}).
|
|
|
|
@item @command{mv}
|
|
@c ---------------
|
|
@prindex @command{mv}
|
|
@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 V6),
|
|
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
|
|
@file{existing} actually exists.
|
|
|
|
Be aware that moving files from @file{/tmp} can sometimes cause
|
|
undesirable (but perfectly valid) warnings, even if you created these
|
|
files. On some systems, creating the file in @file{/tmp} is setting a
|
|
guid @code{wheel} which you may not be part of. So the file is copied,
|
|
and then the @code{chgrp} fails:
|
|
|
|
@example
|
|
$ @kbd{touch /tmp/foo}
|
|
$ @kbd{mv /tmp/foo .}
|
|
@error{}mv: ./foo: set owner/group (was: 3830/0): Operation not permitted
|
|
$ @kbd{echo $?}
|
|
0
|
|
$ @kbd{ls foo}
|
|
foo
|
|
@end example
|
|
|
|
@noindent
|
|
This behavior conforms to @acronym{POSIX}:
|
|
|
|
@quotation
|
|
If the duplication of the file characteristics fails for any reason, mv
|
|
shall write a diagnostic message to standard error, but this failure
|
|
shall not cause mv to modify its exit status.''
|
|
@end quotation
|
|
|
|
Moving directories across mount points is not portable, use @command{cp}
|
|
and @command{rm}.
|
|
|
|
Moving/Deleting open files isn't portable. The following can't be done
|
|
on DOS/WIN32:
|
|
|
|
@example
|
|
exec > foo
|
|
mv foo bar
|
|
@end example
|
|
|
|
@noindent
|
|
nor can
|
|
|
|
@example
|
|
exec > foo
|
|
rm -f foo
|
|
@end example
|
|
|
|
@item @command{sed}
|
|
@c ----------------
|
|
@prindex @command{sed}
|
|
Patterns should not include the separator (unless escaped), even as part
|
|
of a character class. In conformance with @acronym{POSIX}, the Cray
|
|
@command{sed} will reject @samp{s/[^/]*$//}: use @samp{s,[^/]*$,,}.
|
|
|
|
Sed scripts should not use branch labels longer than 8 characters and
|
|
should not contain comments.
|
|
|
|
Don't include extra @samp{;}, as some @command{sed}, such as Net@acronym{BSD}
|
|
1.4.2's, try to interpret the second as a command:
|
|
|
|
@example
|
|
$ @kbd{echo a | sed 's/x/x/;;s/x/x/'}
|
|
sed: 1: "s/x/x/;;s/x/x/": invalid command code ;
|
|
@end example
|
|
|
|
Input should have reasonably long lines, since some @command{sed} have
|
|
an input buffer limited to 4000 bytes.
|
|
|
|
Alternation, @samp{\|}, is common but @acronym{POSIX} does not require its
|
|
support, so it should be avoided in portable scripts. Solaris 8
|
|
@command{sed} does not support alternation; e.g., @samp{sed '/a\|b/d'}
|
|
deletes only lines that contain the literal string @samp{a|b}.
|
|
|
|
Anchors (@samp{^} and @samp{$}) inside groups are not portable.
|
|
|
|
Nested parenthesization in patterns (e.g., @samp{\(\(a*\)b*)\)}) is
|
|
quite portable to modern hosts, but is not supported by some older
|
|
@command{sed} implementations like SVR3.
|
|
|
|
Of course the option @option{-e} is portable, but it is not needed. No
|
|
valid Sed program can start with a dash, so it does not help
|
|
disambiguating. Its sole usefulness is to help enforcing indentation as
|
|
in:
|
|
|
|
@example
|
|
sed -e @var{instruction-1} \
|
|
-e @var{instruction-2}
|
|
@end example
|
|
|
|
@noindent
|
|
as opposed to
|
|
|
|
@example
|
|
sed @var{instruction-1};@var{instruction-2}
|
|
@end example
|
|
|
|
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 Bell Lab's V7 @command{sed} (at least; we
|
|
don't have first hand experience with older @command{sed}s) have
|
|
supported it.
|
|
|
|
@acronym{POSIX} requires that you must not have any white space between
|
|
@samp{!} and the following command. It is OK to have blanks between
|
|
the address and the @samp{!}. For instance, on Solaris 8:
|
|
|
|
@example
|
|
$ @kbd{echo "foo" | sed -n '/bar/ ! p'}
|
|
@error{}Unrecognized command: /bar/ ! p
|
|
$ @kbd{echo "foo" | sed -n '/bar/! p'}
|
|
@error{}Unrecognized command: /bar/! p
|
|
$ @kbd{echo "foo" | sed -n '/bar/ !p'}
|
|
foo
|
|
@end example
|
|
|
|
@item @command{sed} (@samp{t})
|
|
@c ---------------------------
|
|
@prindex @command{sed} (@samp{t})
|
|
Some old systems have @command{sed} that ``forget'' to reset their
|
|
@samp{t} flag when starting a new cycle. For instance on @acronym{MIPS
|
|
RISC/OS}, and on @sc{irix} 5.3, if you run the following @command{sed}
|
|
script (the line numbers are not actual part of the texts):
|
|
|
|
@example
|
|
s/keep me/kept/g # a
|
|
t end # b
|
|
s/.*/deleted/g # c
|
|
: end # d
|
|
@end example
|
|
|
|
@noindent
|
|
on
|
|
|
|
@example
|
|
delete me # 1
|
|
delete me # 2
|
|
keep me # 3
|
|
delete me # 4
|
|
@end example
|
|
|
|
@noindent
|
|
you get
|
|
|
|
@example
|
|
deleted
|
|
delete me
|
|
kept
|
|
deleted
|
|
@end example
|
|
|
|
@noindent
|
|
instead of
|
|
|
|
@example
|
|
deleted
|
|
deleted
|
|
kept
|
|
deleted
|
|
@end example
|
|
|
|
Why? When processing 1, a matches, therefore sets the t flag, b jumps to
|
|
d, and the output is produced. When processing line 2, the t flag is
|
|
still set (this is the bug). Line a fails to match, but @command{sed}
|
|
is not supposed to clear the t flag when a substitution fails. Line 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 3, t
|
|
is clear, a matches, so the flag is set, hence b clears the flags and
|
|
jumps. Finally, since the flag is clear, 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; : clear} to reset the 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:
|
|
|
|
@example
|
|
t clear
|
|
: clear
|
|
s/keep me/kept/g
|
|
t end
|
|
s/.*/deleted/g
|
|
: end
|
|
@end example
|
|
|
|
@item @command{touch}
|
|
@c ------------------
|
|
@prindex @command{touch}
|
|
@cindex timestamp resolution
|
|
If you specify the desired timestamp (e.g., with the @option{-r}
|
|
option), @command{touch} typically uses the @code{utime} or
|
|
@code{utimes} system call, which can result in the same kind of
|
|
timestamp truncation problems that @samp{cp -p} has.
|
|
|
|
On some old @acronym{BSD} systems, @command{touch} or any command that
|
|
results in an empty file does not update the timestamps, so use a
|
|
command like @code{echo} as a workaround.
|
|
|
|
@acronym{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
|
|
@acronym{NFS}-mounted 4.2 volume.
|
|
|
|
@end table
|
|
|
|
|
|
@node Limitations of Make
|
|
@section Limitations of Make
|
|
|
|
@command{make} itself suffers a great number of limitations, only a few
|
|
of which are listed here. First of all, remember that since commands
|
|
are executed by the shell, all its weaknesses are inherited@enddots{}
|
|
|
|
@table @asis
|
|
@item @code{$<}
|
|
@acronym{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 8's @command{make} for instance
|
|
will replace it with the argument.
|
|
|
|
@item Leading underscore in macro names
|
|
Some @command{make}s don't support leading underscores in macro names,
|
|
such as on NEWS-OS 4.2R.
|
|
|
|
@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
|
|
@end example
|
|
|
|
@item Trailing backslash in macro
|
|
@c This has been seen on ia64 hpux 11.20, and on one hppa hpux 10.20,
|
|
@c but another hppa hpux 10.20 didn't have it. Bob Proulx
|
|
@c <bob@proulx.com> thinks it was in hpux 8.0 too.
|
|
On some versions of HP-UX, @command{make} will read multiple newlines
|
|
following a backslash, continuing to the next non-empty line. For
|
|
example,
|
|
|
|
@example
|
|
FOO = one \
|
|
|
|
BAR = two
|
|
|
|
test:
|
|
: FOO is "$(FOO)"
|
|
: BAR is "$(BAR)"
|
|
@end example
|
|
|
|
@noindent
|
|
shows @code{FOO} equal to @code{one BAR = two}. Other @command{make}s
|
|
sensibly let a backslash continue only to the immediately following
|
|
line.
|
|
|
|
@item Escaped newline in comments
|
|
|
|
According to @acronym{POSIX}, @file{Makefile} comments start with @code{#}
|
|
and continue until an unescaped newline is reached.
|
|
|
|
@example
|
|
% @kbd{cat Makefile}
|
|
# A = foo \
|
|
bar \
|
|
baz
|
|
|
|
all:
|
|
@@echo ok
|
|
% @kbd{make} # GNU make
|
|
ok
|
|
@end example
|
|
|
|
@noindent
|
|
However in Real World this is not always the case. Some implementations
|
|
discards anything from @code{#} up to the end of line, ignoring any
|
|
trailing backslash.
|
|
|
|
@example
|
|
% @kbd{pmake} # BSD make
|
|
"Makefile", line 3: Need an operator
|
|
Fatal errors encountered -- cannot continue
|
|
@end example
|
|
|
|
@noindent
|
|
Therefore, if you want to comment out a multi-line definition, prefix each
|
|
line with @code{#}, not only the first.
|
|
|
|
@example
|
|
# A = foo \
|
|
# bar \
|
|
# baz
|
|
@end example
|
|
|
|
@item @code{make macro=value} and sub-@command{make}s.
|
|
|
|
A command-line variable definition such as @code{foo=bar} overrides any
|
|
definition of @code{foo} in the @file{Makefile}. Some @command{make}
|
|
implementations (such as @acronym{GNU} @command{make}) will propagate this
|
|
override to sub-invocations of @command{make}. Some other implementation
|
|
will not pass the substitution along to sub-@command{make}s.
|
|
|
|
@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
|
|
@end example
|
|
|
|
You have a few possibilities if you do want the @code{foo=bar} override
|
|
to propagate to sub-@command{make}s. One is to use the @code{-e}
|
|
option, which causes all environment variables to have precedence over
|
|
the @file{Makefile} macro definitions, and declare foo as an environment
|
|
variable:
|
|
|
|
@example
|
|
% @kbd{env foo=bar make -e}
|
|
@end example
|
|
|
|
The @code{-e} option is propagated to sub-@command{make}s automatically,
|
|
and since the environment is inherited between @command{make}
|
|
invocations, the @code{foo} macro will be overridden in
|
|
sub-@code{make}s as expected.
|
|
|
|
This syntax (@code{foo=bar make -e}) is portable only when used
|
|
outside a @file{Makefile}, for instance from a script or from the
|
|
command line. When run inside a @command{make} rule, GNU
|
|
@command{make} 3.80 and prior versions forget to propagate the
|
|
@code{-e} option to sub-@command{make}s.
|
|
|
|
Moreover, using @code{-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.)
|
|
|
|
Another way to propagate overrides to sub-@command{make}s is to do it
|
|
manually, from your @file{Makefile}:
|
|
|
|
@example
|
|
foo = foo
|
|
one:
|
|
@@echo $(foo)
|
|
$(MAKE) foo=$(foo) two
|
|
two:
|
|
@@echo $(foo)
|
|
@end example
|
|
|
|
You need to foresee all macros that a user might want to override if
|
|
you do that.
|
|
|
|
@item The @code{SHELL} macro
|
|
@cindex @code{SHELL} and @command{make}
|
|
@cindex @command{make} and @code{SHELL}
|
|
|
|
@acronym{POSIX}-compliant @command{make}s internally use the @code{$(SHELL)}
|
|
macro to spawn shell processes and execute @file{Makefile} rules. This
|
|
is a builtin macro supplied by @command{make}, but it can be modified
|
|
from the @file{Makefile} or a command-line argument.
|
|
|
|
Not all @command{make}s will define this @code{SHELL} macro. OSF/Tru64
|
|
@command{make} is an example; this implementation will always use
|
|
@code{/bin/sh}. So it's a good idea to always define @code{SHELL} in
|
|
your @file{Makefile}s. If you use Autoconf, do
|
|
|
|
@example
|
|
SHELL = @@SHELL@@
|
|
@end example
|
|
|
|
@acronym{POSIX}-compliant @command{make}s 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
|
|
@code{SHELL=/bin/tcsh}).
|
|
|
|
However not all @command{make} implementations will make this exception.
|
|
For instance it's not surprising that OSF/Tru64 @command{make} doesn't
|
|
protect @code{SHELL}, since it doesn't use it.
|
|
|
|
@example
|
|
% @kbd{cat Makefile}
|
|
SHELL = /bin/sh
|
|
FOO = foo
|
|
all:
|
|
@@echo $(SHELL)
|
|
@@echo $(FOO)
|
|
% @kbd{env SHELL=/bin/tcsh FOO=bar make -e} # OSF1 V4.0 Make
|
|
/bin/tcsh
|
|
bar
|
|
% @kbd{env SHELL=/bin/tcsh FOO=bar gmake -e} # GNU make
|
|
/bin/sh
|
|
bar
|
|
@end example
|
|
|
|
@item Comments in rules
|
|
@cindex Comments in @file{Makefile} rules
|
|
@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
|
|
@file{Makefile} will run @code{# foo} through the shell.
|
|
|
|
@example
|
|
all:
|
|
# foo
|
|
@end example
|
|
|
|
@item The @file{obj/} subdirectory.
|
|
@cindex @file{obj/}, subdirectory
|
|
@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} will enter it
|
|
before reading @file{Makefile}. Hence the @file{Makefile} in the
|
|
current directory will not be read.
|
|
|
|
@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
|
|
@end example
|
|
|
|
@item @code{make -k}
|
|
@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.
|
|
|
|
@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
|
|
@end example
|
|
|
|
@item @code{VPATH}
|
|
@cindex @code{VPATH}
|
|
|
|
There is no @code{VPATH} support specified in @acronym{POSIX}. Many
|
|
@command{make}s have a form of @code{VPATH} support, but its
|
|
implementation is not consistent amongst @command{make}s.
|
|
|
|
Maybe the best suggestion to give to people who need the @code{VPATH}
|
|
feature is to choose a @command{make} implementation and stick to it.
|
|
Since the resulting @file{Makefile}s are not portable anyway, better
|
|
choose a portable @command{make} (hint, hint).
|
|
|
|
Here are a couple of known issues with some @code{VPATH}
|
|
implementations.
|
|
|
|
@table @asis
|
|
|
|
@item @code{VPATH} and double-colon rules
|
|
@cindex @code{VPATH} and double-colon rules
|
|
@cindex double-colon rules and @code{VPATH}
|
|
|
|
Any assignment to @code{VPATH} causes Sun @command{make} to only execute
|
|
the first set of double-colon rules. (This comment has been here since
|
|
1994 and the context has been lost. It's probably about SunOS 4. If
|
|
you can reproduce this, please send us a test case for illustration.)
|
|
|
|
@item @code{$<} not supported in explicit rules
|
|
@cindex explicit rules, @code{$<}, and @code{VPATH}
|
|
@cindex @code{$<}, explicit rules, and @code{VPATH}
|
|
@cindex @code{VPATH}, explicit rules, and @code{$<}
|
|
|
|
As said elsewhere, 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. For instance, using the following pattern:
|
|
|
|
@example
|
|
VPATH = ../pkg/src
|
|
foo.o: foo.c
|
|
cc -c `test -f foo.c || echo ../pkg/src/`foo.c -o foo.o
|
|
@end example
|
|
|
|
@item Automatic rule rewriting
|
|
@cindex @code{VPATH} and automatic rule rewriting
|
|
@cindex automatic rule rewriting and @code{VPATH}
|
|
|
|
Some @command{make} implementations, such as SunOS @command{make} or
|
|
OSF1/Tru64 @command{make}, will search prerequisites in @code{VPATH} and
|
|
rewrite all their occurrences in the rule appropriately.
|
|
|
|
For instance
|
|
|
|
@example
|
|
VPATH = ../pkg/src
|
|
foo.o: foo.c
|
|
cc -c foo.c -o foo.o
|
|
@end example
|
|
|
|
@noindent
|
|
would execute @code{cc -c ../pkg/src/foo.c -o foo.o} if @file{foo.c} was
|
|
found in @file{../pkg/src}. That sounds great.
|
|
|
|
However, for the sake of other @command{make} implementations, we can't
|
|
rely on this, and we have to search @code{VPATH} manually:
|
|
|
|
@example
|
|
VPATH = ../pkg/src
|
|
foo.o: foo.c
|
|
cc -c `test -f foo.c || echo ../pkg/src/`foo.c -o foo.o
|
|
@end example
|
|
|
|
@noindent
|
|
However the "prerequisite rewriting" still applies here. So if
|
|
@file{foo.c} is in @file{../pkg/src}, SunOS @command{make} and OSF1/Tru64
|
|
@command{make} will execute
|
|
|
|
@example
|
|
@code{cc -c `test -f ../pkg/src/foo.c || echo ../pkg/src/`foo.c -o foo.o}
|
|
@end example
|
|
|
|
@noindent
|
|
which reduces to
|
|
|
|
@example
|
|
cc -c foo.c -o foo.o
|
|
@end example
|
|
|
|
@noindent
|
|
and thus fails. Oops.
|
|
|
|
One workaround is to make sure that foo.c never appears as a plain word
|
|
in the rule. For instance these three rules would be safe.
|
|
|
|
@example
|
|
VPATH = ../pkg/src
|
|
foo.o: foo.c
|
|
cc -c `test -f ./foo.c || echo ../pkg/src/`foo.c -o foo.o
|
|
foo2.o: foo2.c
|
|
cc -c `test -f 'foo2.c' || echo ../pkg/src/`foo2.c -o foo2.o
|
|
foo3.o: foo3.c
|
|
cc -c `test -f "foo3.c" || echo ../pkg/src/`foo3.c -o foo3.o
|
|
@end example
|
|
|
|
Things get worse when your prerequisites are in a macro.
|
|
|
|
@example
|
|
VPATH = ../pkg/src
|
|
HEADERS = foo.h foo2.h foo3.h
|
|
install-HEADERS: $(HEADERS)
|
|
for i in $(HEADERS); do \
|
|
$(INSTALL) -m 644 `test -f $$i || echo ../pkg/src/`$$i \
|
|
$(DESTDIR)$(includedir)/$$i; \
|
|
done
|
|
@end example
|
|
|
|
The above @code{install-HEADERS} rule is not SunOS-proof because @code{for
|
|
i in $(HEADERS);} will be expanded as @code{for i in foo.h foo2.h foo3.h;}
|
|
where @code{foo.h} and @code{foo2.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:
|
|
|
|
@example
|
|
for i in ../pkg/src/foo.h ../pkg/src/foo2.h foo3.h; do \
|
|
install -m 644 `test -f $i || echo ../pkg/src/`$i \
|
|
/usr/local/include/$i; \
|
|
done
|
|
@end example
|
|
|
|
where the two first @command{install} calls will fail. For instance,
|
|
consider the @code{foo.h} installation:
|
|
|
|
@example
|
|
install -m 644 `test -f ../pkg/src/foo.h || echo ../pkg/src/`../pkg/src/foo.h \
|
|
/usr/local/include/../pkg/src/foo.h;
|
|
@end example
|
|
@noindent
|
|
It reduces to:
|
|
|
|
@example
|
|
install -m 644 ../pkg/src/foo.h /usr/local/include/../pkg/src/foo.h;
|
|
@end example
|
|
|
|
Note that the manual @code{VPATH} search did not cause any problems here;
|
|
however this command installs @file{foo.h} in an incorrect directory.
|
|
|
|
Trying to quote @code{$(HEADERS)} in some way, as we did for
|
|
@code{foo.c} a few @file{Makefile}s ago, does not help:
|
|
|
|
@example
|
|
install-HEADERS: $(HEADERS)
|
|
headers='$(HEADERS)'; for i in $$headers; do \
|
|
$(INSTALL) -m 644 `test -f $$i || echo ../pkg/src/`$$i \
|
|
$(DESTDIR)$(includedir)/$$i; \
|
|
done
|
|
@end example
|
|
|
|
Indeed, @code{headers='$(HEADERS)'} expands to @code{headers='foo.h
|
|
foo2.h foo3.h'} where @code{foo2.h} is still a plain word. (Aside: the
|
|
@code{headers='$(HEADERS)'; for i in $$headers;} idiom 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:
|
|
@example
|
|
VPATH = ../pkg/src
|
|
HEADERS = foo.h foo2.h foo3.h
|
|
install-HEADERS: $(HEADERS)
|
|
headers='$(HEADERS)'; for i in $$headers; do \
|
|
i=`expr "$$i" : '../pkg/src/\(.*\)'`;
|
|
$(INSTALL) -m 644 `test -f $$i || echo ../pkg/src/`$$i \
|
|
$(DESTDIR)$(includedir)/$$i; \
|
|
done
|
|
@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
|
|
@code{HEADERS = ../foo.h}, the above fragment would fail in a VPATH
|
|
build with OSF1/Tru64 @command{make}. The reason is that not only does
|
|
OSF1/Tru64 @command{make} rewrite dependencies, but it also simplifies
|
|
them. Hence @code{../foo.h} will become @code{../pkg/foo.h} instead of
|
|
@code{../pkg/src/../foo.h}. This obviously defeats any attempt to strip
|
|
a leading @file{../pkg/src/} component.
|
|
|
|
The following example makes the behavior of OSF1/Tru64 @command{make}
|
|
more apparent.
|
|
@example
|
|
% cat Makefile
|
|
VPATH = sub
|
|
all: ../foo
|
|
echo ../foo
|
|
% ls
|
|
Makefile foo
|
|
% make
|
|
echo foo
|
|
foo
|
|
@end example
|
|
@noindent
|
|
Dependency @file{../foo} was found in @file{sub/../foo}, but OSF1/Tru64
|
|
@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 records here is how SunOS @command{make} behaves on this
|
|
very same example.
|
|
@example
|
|
% make
|
|
make: Fatal error: Don't know how to make target `../foo'
|
|
% mkdir sub
|
|
% make
|
|
echo sub/../foo
|
|
sub/../foo
|
|
@end example
|
|
|
|
|
|
@item OSF/Tru64 @command{make} creates prerequisite directories magically
|
|
@cindex @code{VPATH} and prerequisite directories
|
|
@cindex prerequisite directories and @code{VPATH}
|
|
|
|
When a prerequisite is a sub-directory of @code{VPATH}, Tru64
|
|
@command{make} will create it in the current directory.
|
|
|
|
@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
|
|
@end example
|
|
|
|
This can yield unexpected results if a rule uses a manual @code{VPATH}
|
|
search as presented before.
|
|
|
|
@example
|
|
VPATH = ..
|
|
all : foo/bar
|
|
command `test -d foo/bar || echo ../`foo/bar
|
|
@end example
|
|
|
|
The above @command{command} will be run on the empty @file{foo/bar}
|
|
directory that was created in the current directory.
|
|
|
|
@item target lookup
|
|
@cindex @code{VPATH}, resolving target pathnames
|
|
|
|
@acronym{GNU} @command{make} uses a rather 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 @acronym{GNU} Make
|
|
Manual}.
|
|
|
|
If a target needs to be rebuilt, @acronym{GNU} @command{make} discards the
|
|
filename found during the @code{VPATH} search for this target, and
|
|
builds the file locally using the filename given in the @file{Makefile}.
|
|
If a target does not need to be rebuilt, @acronym{GNU} @command{make} uses the
|
|
filename found during the @code{VPATH} search.
|
|
|
|
Other @command{make} implementations, like NetBSD @command{make}, are
|
|
easier to describe: the filename found during the @code{VPATH} search
|
|
will be used whether the target needs to be rebuilt or not. Therefore
|
|
new files are created locally, but existing files are updated at their
|
|
@code{VPATH} location.
|
|
|
|
OpenBSD and FreeBSD @command{make}s, however, will never perform a
|
|
@code{VPATH} search for a dependency which 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 the
|
|
@acronym{GNU}
|
|
@command{make} will build everything locally in the @file{build}
|
|
directory, while BSD @command{make} will build new files locally and
|
|
update existing files in the source directory.
|
|
|
|
@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
|
|
@end example
|
|
|
|
Note how NetBSD @command{make} updates @file{../bar.x} in its VPATH
|
|
location, and how FreeBSD, OpenBSD, and Tru64 @command{make} always
|
|
update @file{bar.x}, even when @file{../bar.x} is up to date.
|
|
|
|
Another point worth mentioning is that once @acronym{GNU} @command{make} has
|
|
decided to ignore a @code{VPATH} filename (e.g., it ignored
|
|
@file{../bar.x} in the above example) it will continue to ignore it when
|
|
the target occurs as a prerequisite of another rule.
|
|
|
|
The following example shows that @acronym{GNU} @command{make} does not look up
|
|
@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.
|
|
|
|
@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
|
|
@end example
|
|
|
|
Note that if you drop away the command from the @code{bar.x: newer.x}
|
|
rule, @acronym{GNU} @command{make} will magically start 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 will also work, but FreeBSD and OpenBSD still don't.
|
|
|
|
@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} # True64 make
|
|
cp ../bar.x bar.y
|
|
@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.
|
|
|
|
@end table
|
|
@c end item about VPATH
|
|
|
|
@item Single Suffix Rules and Separated Dependencies
|
|
@cindex Single Suffix Inference Rule
|
|
@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:}).
|
|
|
|
@cindex Separated Dependencies
|
|
@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:
|
|
|
|
@example
|
|
$ @kbd{cat Makefile}
|
|
.SUFFIXES: .in
|
|
foo: foo.in
|
|
.in:
|
|
cp $< $@
|
|
$ @kbd{touch foo.in}
|
|
$ @kbd{make}
|
|
$ @kbd{ls}
|
|
Makefile foo.in
|
|
@end example
|
|
|
|
@noindent
|
|
while @acronym{GNU} Make does:
|
|
|
|
@example
|
|
$ @kbd{gmake}
|
|
cp foo.in foo
|
|
$ @kbd{ls}
|
|
Makefile foo foo.in
|
|
@end example
|
|
|
|
Note it works without the @samp{foo: foo.in} dependency.
|
|
|
|
@example
|
|
$ @kbd{cat Makefile}
|
|
.SUFFIXES: .in
|
|
.in:
|
|
cp $< $@
|
|
$ @kbd{make foo}
|
|
cp foo.in foo
|
|
@end example
|
|
|
|
@noindent
|
|
and it works with double suffix inference rules:
|
|
|
|
@example
|
|
$ @kbd{cat Makefile}
|
|
foo.out: foo.in
|
|
.SUFFIXES: .in .out
|
|
.in.out:
|
|
cp $< $@
|
|
$ @kbd{make}
|
|
cp foo.in foo.out
|
|
@end example
|
|
|
|
As a result, in such a case, you have to write target rules.
|
|
|
|
@item Timestamp Resolution
|
|
@cindex timestamp resolution
|
|
Traditionally, file timestamps had 1-second resolution, and
|
|
@command{make} used those timestamps to determine whether one file was
|
|
newer than the other. However, many modern filesystems 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{Limitations of Usual
|
|
Tools}). Hence you should be wary of rules like this:
|
|
|
|
@example
|
|
dest: src
|
|
cp -p src dest
|
|
@end example
|
|
|
|
as @file{dest} will often appear 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.:
|
|
|
|
@example
|
|
dest-stamp: src
|
|
cp -p src dest
|
|
date >dest-stamp
|
|
@end example
|
|
|
|
@end table
|
|
|
|
|
|
|
|
|
|
@c ================================================== Manual Configuration
|
|
|
|
@node Manual Configuration
|
|
@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
|
|
@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.
|
|
|
|
@menu
|
|
* Specifying Names:: Specifying the system type
|
|
* Canonicalizing:: Getting the canonical system type
|
|
* Using System Type:: What to do with the system type
|
|
@end menu
|
|
|
|
@node Specifying Names
|
|
@section Specifying the System Type
|
|
|
|
Like other @acronym{GNU} @command{configure} scripts, Autoconf-generated
|
|
@command{configure} scripts can make decisions based on a canonical name
|
|
for the system type, which has the form:
|
|
@samp{@var{cpu}-@var{vendor}-@var{os}}, where @var{os} can be
|
|
@samp{@var{system}} or @samp{@var{kernel}-@var{system}}
|
|
|
|
@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
|
|
@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}. 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:
|
|
|
|
@table @option
|
|
@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}.
|
|
|
|
@item --host=@var{host-type}
|
|
@ovindex cross_compiling
|
|
the type of system on which the package will run. By default it is the
|
|
same as the build machine. Specifying it enables the cross-compilation
|
|
mode.
|
|
|
|
@item --target=@var{target-type}
|
|
the type of system for which any compiler tools in the package will
|
|
produce code (rarely needed). By default, it is the same as host.
|
|
@end table
|
|
|
|
If you mean to override the result of @command{config.guess}, use
|
|
@option{--build}, not @option{--host}, since the latter enables
|
|
cross-compilation. For historical reasons, passing @option{--host} also
|
|
changes the build type. Therefore, whenever you specify @code{--host},
|
|
be sure to specify @code{--build} too. This will be fixed in the
|
|
future.
|
|
|
|
@example
|
|
./configure --build=i686-pc-linux-gnu --host=m68k-coff
|
|
@end example
|
|
|
|
@noindent
|
|
will enter cross-compilation mode, but @command{configure} will fail if it
|
|
can't run the code generated by the specified compiler if you configure
|
|
as follows:
|
|
|
|
@example
|
|
./configure CC=m68k-coff-gcc
|
|
@end example
|
|
|
|
@cindex @command{config.sub}
|
|
@command{configure} recognizes short aliases for many system types; for
|
|
example, @samp{decstation} can be used instead of
|
|
@samp{mips-dec-ultrix4.2}. @command{configure} runs a script called
|
|
@command{config.sub} to canonicalize system type aliases.
|
|
|
|
This section deliberately omits the description of the obsolete
|
|
interface; see @ref{Hosts and Cross-Compilation}.
|
|
|
|
|
|
@node Canonicalizing
|
|
@section Getting the Canonical System Type
|
|
|
|
The following macros make the system type available to @command{configure}
|
|
scripts.
|
|
|
|
@ovindex build_alias
|
|
@ovindex host_alias
|
|
@ovindex target_alias
|
|
|
|
The variables @samp{build_alias}, @samp{host_alias}, and
|
|
@samp{target_alias} are always exactly the arguments of @option{--build},
|
|
@option{--host}, and @option{--target}; in particular, they are left empty
|
|
if the user did not use them, even if the corresponding
|
|
@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
|
|
@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.
|
|
|
|
|
|
@defmac AC_CANONICAL_BUILD
|
|
@acindex{CANONICAL_BUILD}
|
|
@ovindex build
|
|
@ovindex build_cpu
|
|
@ovindex build_vendor
|
|
@ovindex build_os
|
|
Compute the canonical build-system type variable, @code{build}, and its
|
|
three individual parts @code{build_cpu}, @code{build_vendor}, and
|
|
@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}.
|
|
@end defmac
|
|
|
|
@defmac AC_CANONICAL_HOST
|
|
@acindex{CANONICAL_HOST}
|
|
@ovindex host
|
|
@ovindex host_cpu
|
|
@ovindex host_vendor
|
|
@ovindex host_os
|
|
Compute the canonical host-system type variable, @code{host}, and its
|
|
three individual parts @code{host_cpu}, @code{host_vendor}, and
|
|
@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}.
|
|
@end defmac
|
|
|
|
@defmac AC_CANONICAL_TARGET
|
|
@acindex{CANONICAL_TARGET}
|
|
@ovindex target
|
|
@ovindex target_cpu
|
|
@ovindex target_vendor
|
|
@ovindex target_os
|
|
Compute the canonical target-system type variable, @code{target}, and its
|
|
three individual parts @code{target_cpu}, @code{target_vendor}, and
|
|
@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}.
|
|
@end defmac
|
|
|
|
Note that there can be artifacts due to the backward compatibility
|
|
code. See @xref{Hosts and Cross-Compilation}, for more.
|
|
|
|
@node Using System Type
|
|
@section Using the System Type
|
|
|
|
In @file{configure.ac} the system type is generally used by one or more
|
|
@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 @file{Makefile} to add the object to a
|
|
program or library.
|
|
|
|
@example
|
|
case $host in
|
|
alpha*-*-*) CYCLE_OBJ=rpcc.o ;;
|
|
i?86-*-*) CYCLE_OBJ=rdtsc.o ;;
|
|
*) CYCLE_OBJ= ;;
|
|
esac
|
|
AC_SUBST(CYCLE_OBJ)
|
|
@end example
|
|
|
|
@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 run-time capability checks may be necessary too.
|
|
|
|
@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
|
|
@end example
|
|
|
|
Another example is filenames made to vary according to system
|
|
conventions. On Unix-like systems ``dot'' files are usual but on DOS
|
|
systems @file{ini} files are usual. It may be worth allowing the user
|
|
to override such things though, if it's a matter of personal preference,
|
|
or in case a new DOS-like system comes along.
|
|
|
|
@example
|
|
case $host in
|
|
*-*-msdos* | *-*-go32* | *-*-mingw32* | *-*-cygwin* | *-*-windows*)
|
|
MUMBLE_INIT="mumble.ini"
|
|
;;
|
|
*)
|
|
MUMBLE_INIT=".mumbleinit"
|
|
;;
|
|
esac
|
|
AC_SUBST(MUMBLE_INIT)
|
|
@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 won't. Here are some guidelines,
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Availability of libraries and library functions should always be checked
|
|
by probing.
|
|
@item
|
|
Variant behaviour 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}.
|
|
@item
|
|
Assembler code is inevitably highly CPU-specific and is best selected
|
|
according to @samp{$host_cpu}.
|
|
@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.
|
|
@end itemize
|
|
|
|
@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 will themselves determine how the target will work.
|
|
|
|
|
|
@c ===================================================== Site Configuration.
|
|
|
|
@node Site Configuration
|
|
@chapter Site Configuration
|
|
|
|
@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.
|
|
|
|
@menu
|
|
* External Software:: Working with other optional software
|
|
* Package Options:: Selecting optional features
|
|
* Pretty Help Strings:: Formatting help string
|
|
* Site Details:: Configuring site details
|
|
* Transforming Names:: Changing program names when installing
|
|
* Site Defaults:: Giving @command{configure} local defaults
|
|
@end menu
|
|
|
|
@node External Software
|
|
@section Working With 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:
|
|
|
|
@c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
|
|
@c awful.
|
|
@example
|
|
--with-@var{package}[=@var{arg}]
|
|
--without-@var{package}
|
|
@end example
|
|
|
|
For example, @option{--with-gnu-ld} means work with the @acronym{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
|
|
@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}.
|
|
@option{--without-@var{package}} is equivalent to
|
|
@option{--with-@var{package}=no}.
|
|
|
|
@command{configure} scripts do not complain about
|
|
@option{--with-@var{package}} options that they do not support. This
|
|
behavior permits configuring a source tree containing multiple packages
|
|
with a top-level @command{configure} script when the packages support
|
|
different options, without spurious error messages about options that
|
|
some of the packages support. An unfortunate side effect is that option
|
|
spelling errors are not diagnosed. No better approach to this problem
|
|
has been suggested so far.
|
|
|
|
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.
|
|
|
|
@defmac AC_ARG_WITH (@var{package}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given})
|
|
@acindex{ARG_WITH}
|
|
If the user gave @command{configure} the option @option{--with-@var{package}}
|
|
or @option{--without-@var{package}}, run shell commands
|
|
@var{action-if-given}. If neither option was given, run shell commands
|
|
@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 and dashes.
|
|
|
|
The option's argument is available to the shell commands
|
|
@var{action-if-given} in the shell variable @code{withval}, which is
|
|
actually just the value of the shell variable @code{with_@var{package}},
|
|
with any @option{-} characters 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:
|
|
@example
|
|
--with-readline support fancy command line editing
|
|
@end example
|
|
|
|
@noindent
|
|
@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. You'll need to enclose the
|
|
help string in @samp{[} and @samp{]} in order to produce the leading
|
|
spaces.
|
|
|
|
You should format your @var{help-string} with the macro
|
|
@code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
|
|
@end defmac
|
|
|
|
@defmac AC_WITH (@var{package}, @var{action-if-given}, @ovar{action-if-not-given})
|
|
@acindex{WITH}
|
|
This is an obsolete version of @code{AC_ARG_WITH} that does not
|
|
support providing a help string.
|
|
@end defmac
|
|
|
|
@node Package Options
|
|
@section Choosing Package Options
|
|
|
|
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:
|
|
|
|
@c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
|
|
@c awful.
|
|
@example
|
|
--enable-@var{feature}[=@var{arg}]
|
|
--disable-@var{feature}
|
|
@end example
|
|
|
|
These options allow users to choose which optional features to build and
|
|
install. @option{--enable-@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
|
|
@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-@var{feature}} is
|
|
equivalent to @option{--enable-@var{feature}=no}.
|
|
|
|
@command{configure} scripts do not complain about
|
|
@option{--enable-@var{feature}} options that they do not support.
|
|
This behavior permits configuring a source tree containing multiple
|
|
packages with a top-level @command{configure} script when the packages
|
|
support different options, without spurious error messages about options
|
|
that some of the packages support.
|
|
An unfortunate side effect is that option spelling errors are not diagnosed.
|
|
No better approach to this problem has been suggested so far.
|
|
|
|
For each optional feature, @file{configure.ac} should call
|
|
@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.
|
|
|
|
@defmac AC_ARG_ENABLE (@var{feature}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given})
|
|
@acindex{ARG_ENABLE}
|
|
If the user gave @command{configure} the option
|
|
@option{--enable-@var{feature}} or @option{--disable-@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 and dashes.
|
|
|
|
The option's argument is available to the shell commands
|
|
@var{action-if-given} in the shell variable @code{enableval}, which is
|
|
actually just the value of the shell variable
|
|
@code{enable_@var{feature}}, with any @option{-} characters changed into
|
|
@samp{_}. You may use that variable instead, if you wish. The
|
|
@var{help-string} argument is like that of @code{AC_ARG_WITH}
|
|
(@pxref{External Software}).
|
|
|
|
You should format your @var{help-string} with the macro
|
|
@code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
|
|
@end defmac
|
|
|
|
@defmac AC_ENABLE (@var{feature}, @var{action-if-given}, @ovar{action-if-not-given})
|
|
@acindex{ENABLE}
|
|
This is an obsolete version of @code{AC_ARG_ENABLE} that does not
|
|
support providing a help string.
|
|
@end defmac
|
|
|
|
|
|
@node Pretty Help Strings
|
|
@section Making Your Help Strings Look Pretty
|
|
|
|
Properly formatting the @samp{help strings} which are used in
|
|
@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
|
|
@samp{configure --help} just like the standard Autoconf @samp{help
|
|
strings} do. This is the purpose of the @code{AS_HELP_STRING} macro.
|
|
|
|
@defmac AS_HELP_STRING (@var{left-hand-side}, @var{right-hand-side})
|
|
@acindex{HELP_STRING}
|
|
|
|
Expands into an help string that looks pretty when the user executes
|
|
@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 will make this clearer.
|
|
|
|
@example
|
|
AC_DEFUN([TEST_MACRO],
|
|
[AC_ARG_WITH([foo],
|
|
AS_HELP_STRING([--with-foo],
|
|
[use foo (default is NO)]),
|
|
[ac_cv_use_foo=$withval], [ac_cv_use_foo=no])
|
|
AC_CACHE_CHECK([whether to use foo],
|
|
[ac_cv_use_foo], [ac_cv_use_foo=no])])
|
|
@end example
|
|
|
|
Please note that the call to @code{AS_HELP_STRING} is @strong{unquoted}.
|
|
Then the last few lines of @samp{configure --help} will appear like
|
|
this:
|
|
|
|
@example
|
|
--enable and --with options recognized:
|
|
--with-foo use foo (default is NO)
|
|
@end example
|
|
|
|
The @code{AS_HELP_STRING} macro is particularly helpful when the
|
|
@var{left-hand-side} and/or @var{right-hand-side} are composed of macro
|
|
arguments, as shown in the following example.
|
|
|
|
@example
|
|
AC_DEFUN(MY_ARG_WITH,
|
|
[AC_ARG_WITH([$1],
|
|
AS_HELP_STRING([--with-$1], [use $1 (default is $2)]),
|
|
ac_cv_use_$1=$withval, ac_cv_use_$1=no),
|
|
AC_CACHE_CHECK(whether to use $1, ac_cv_use_$1, ac_cv_use_$1=$2)])
|
|
@end example
|
|
@end defmac
|
|
|
|
|
|
@node Site Details
|
|
@section Configuring 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
|
|
run time, rather than at compile time. Run-time 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, @acronym{GNU} Coding
|
|
Standards}, for more information on where to put data files.
|
|
|
|
@node Transforming Names
|
|
@section Transforming Program Names When Installing
|
|
|
|
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}.
|
|
|
|
@defmac AC_ARG_PROGRAM
|
|
@acindex{ARG_PROGRAM}
|
|
@ovindex program_transform_name
|
|
Place in output variable @code{program_transform_name} a sequence of
|
|
@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
|
|
@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.
|
|
@end defmac
|
|
|
|
@menu
|
|
* Transformation Options:: @command{configure} options to transform names
|
|
* Transformation Examples:: Sample uses of transforming names
|
|
* Transformation Rules:: @file{Makefile} uses of transforming names
|
|
@end menu
|
|
|
|
@node Transformation Options
|
|
@subsection Transformation Options
|
|
|
|
You can specify name transformations by giving @command{configure} these
|
|
command line options:
|
|
|
|
@table @option
|
|
@item --program-prefix=@var{prefix}
|
|
prepend @var{prefix} to the names;
|
|
|
|
@item --program-suffix=@var{suffix}
|
|
append @var{suffix} to the names;
|
|
|
|
@item --program-transform-name=@var{expression}
|
|
perform @code{sed} substitution @var{expression} on the names.
|
|
@end table
|
|
|
|
@node Transformation Examples
|
|
@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
|
|
@option{--target=i960-vxworks} is normally installed as
|
|
@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
|
|
@acronym{GNU} programs installed on your system to shadow other programs with
|
|
the same name. For example, if you configure @acronym{GNU} @code{diff} with
|
|
@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
|
|
|
|
@example
|
|
--program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/'
|
|
@end example
|
|
@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
|
|
@code{less} and @code{lesskey} that aren't @acronym{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},
|
|
@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.
|
|
|
|
@node Transformation Rules
|
|
@subsection Transformation Rules
|
|
|
|
Here is how to use the variable @code{program_transform_name} in a
|
|
@file{Makefile.in}:
|
|
|
|
@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)'`; \
|
|
done
|
|
@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
|
|
@code{program_transform_name} within a sed program using @samp{;}:
|
|
|
|
@example
|
|
transform = @@program_transform_name@@
|
|
transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/
|
|
@end example
|
|
|
|
Whether to do the transformations on documentation files (Texinfo or
|
|
@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.
|
|
|
|
@node Site Defaults
|
|
@section Setting Site Defaults
|
|
|
|
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.
|
|
|
|
@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. 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
|
|
@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
|
|
@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};
|
|
@option{--enable-warnings=no} or @option{--disable-warnings} sets the variable
|
|
@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
|
|
@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
|
|
@file{@var{prefix}/etc/config.site}. To find out the names of the cache
|
|
variables you need to set, 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.
|
|
|
|
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
|
|
@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).
|
|
|
|
@example
|
|
# 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
|
|
@end example
|
|
|
|
|
|
@c ============================================== Running configure Scripts.
|
|
|
|
@node Running configure Scripts
|
|
@chapter Running @command{configure} Scripts
|
|
@cindex @command{configure}
|
|
|
|
Below are instructions on how to configure a package that uses a
|
|
@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.
|
|
|
|
@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
|
|
* 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
|
|
@end menu
|
|
|
|
@set autoconf
|
|
@include install.texi
|
|
|
|
|
|
@c ============================================== Recreating a Configuration
|
|
|
|
@node config.status Invocation
|
|
@chapter Recreating a Configuration
|
|
@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:
|
|
@example
|
|
./config.status @var{option}@dots{} [@var{file}@dots{}]
|
|
@end example
|
|
|
|
It configures the @var{files}; if none are specified, all the templates
|
|
are instantiated. The files must be specified without their
|
|
dependencies, as in
|
|
|
|
@example
|
|
./config.status foobar
|
|
@end example
|
|
|
|
@noindent
|
|
not
|
|
|
|
@example
|
|
./config.status foobar:foo.in:bar.in
|
|
@end example
|
|
|
|
The supported @var{option}s are:
|
|
|
|
@table @option
|
|
@item --help
|
|
@itemx -h
|
|
Print a summary of the command line options, the list of the template
|
|
files, and exit.
|
|
|
|
@item --version
|
|
@itemx -V
|
|
Print the version number of Autoconf and exit.
|
|
|
|
@item --silent
|
|
@itemx --quiet
|
|
@itemx -q
|
|
Do not print progress messages.
|
|
|
|
@item --debug
|
|
@itemx -d
|
|
Don't remove the temporary files.
|
|
|
|
@item --file=@var{file}[:@var{template}]
|
|
Require that @var{file} be instantiated as if
|
|
@samp{AC_CONFIG_FILES(@var{file}:@var{template})} was used. Both
|
|
@var{file} and @var{template} may be @samp{-} in which case the standard
|
|
output and/or standard input, respectively, is used. If a
|
|
@var{template} filename 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.
|
|
|
|
@item --header=@var{file}[:@var{template}]
|
|
Same as @option{--file} above, but with @samp{AC_CONFIG_HEADERS}.
|
|
|
|
@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
|
|
@option{--recheck} option re-runs @command{configure} with the same arguments
|
|
you used before, plus the @option{--no-create} option, which prevents
|
|
@command{configure} from running @file{config.status} and creating
|
|
@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 @file{Makefile} rules can
|
|
run @file{config.status} when it changes; @pxref{Automatic Remaking},
|
|
for an example).
|
|
@end table
|
|
|
|
@file{config.status} checks several optional environment variables that
|
|
can alter its behavior:
|
|
|
|
@defvar CONFIG_SHELL
|
|
@evindex CONFIG_SHELL
|
|
The shell with which to run @command{configure} for the @option{--recheck}
|
|
option. It must be Bourne-compatible. The default is a shell that
|
|
supports @env{LINENO} if available, and @file{/bin/sh} otherwise.
|
|
@end defvar
|
|
|
|
@defvar CONFIG_STATUS
|
|
@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.
|
|
@end defvar
|
|
|
|
You can use @file{./config.status} in your Makefiles. For example, in
|
|
the dependencies given above (@pxref{Automatic Remaking}),
|
|
@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:
|
|
@example
|
|
@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
|
|
@end group
|
|
@end example
|
|
|
|
The calling convention of @file{config.status} has changed; see
|
|
@ref{Obsolete config.status Use}, for details.
|
|
|
|
|
|
@c =================================================== Obsolete Constructs
|
|
|
|
@node Obsolete Constructs
|
|
@chapter 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.
|
|
|
|
@menu
|
|
* Obsolete config.status Use:: Different calling convention
|
|
* acconfig.h:: 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
|
|
@end menu
|
|
|
|
@node Obsolete config.status Use
|
|
@section Obsolete @file{config.status} Invocation
|
|
|
|
@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.
|
|
|
|
@defvar CONFIG_COMMANDS
|
|
@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
|
|
@file{configure.ac}.
|
|
@end defvar
|
|
|
|
@defvar CONFIG_FILES
|
|
@evindex CONFIG_FILES
|
|
The files in which to perform @samp{@@@var{variable}@@} substitutions.
|
|
The default is the arguments given to @code{AC_OUTPUT} and
|
|
@code{AC_CONFIG_FILES} in @file{configure.ac}.
|
|
@end defvar
|
|
|
|
@defvar CONFIG_HEADERS
|
|
@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.
|
|
@end defvar
|
|
|
|
@defvar CONFIG_LINKS
|
|
@evindex CONFIG_LINKS
|
|
The symbolic links to establish. The default is the arguments given to
|
|
@code{AC_CONFIG_LINKS}; if that macro was not called,
|
|
@file{config.status} ignores this variable.
|
|
@end defvar
|
|
|
|
In @ref{config.status Invocation}, using this old interface, the example
|
|
would be:
|
|
|
|
@example
|
|
@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
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
(If @file{configure.ac} does not call @code{AC_CONFIG_HEADERS}, there is
|
|
no need to set @code{CONFIG_HEADERS} in the @code{make} rules. Equally
|
|
for @code{CONFIG_COMMANDS} etc.)
|
|
|
|
|
|
@node acconfig.h
|
|
@section @file{acconfig.h}
|
|
|
|
@cindex @file{acconfig.h}
|
|
@cindex @file{config.h.top}
|
|
@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
|
|
@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
|
|
@code{AH_BOTTOM} if you need to prepend/append some information to
|
|
@file{config.h.in}. Ancient versions of Autoconf had a similar feature:
|
|
if @file{./acconfig.h} contains the string @samp{@@TOP@@},
|
|
@command{autoheader} copies the lines before the line containing
|
|
@samp{@@TOP@@} into the top of the file that it generates. Similarly,
|
|
if @file{./acconfig.h} contains the string @samp{@@BOTTOM@@},
|
|
@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
|
|
@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:
|
|
@example
|
|
@group
|
|
configure.ac --. .------> autoconf* -----> configure
|
|
+---+
|
|
[aclocal.m4] --+ `---.
|
|
[acsite.m4] ---' |
|
|
+--> [autoheader*] -> [config.h.in]
|
|
[acconfig.h] ----. |
|
|
+-----'
|
|
[config.h.top] --+
|
|
[config.h.bot] --'
|
|
@end group
|
|
@end example
|
|
|
|
Using only the @code{AH_} macros, @file{configure.ac} should be
|
|
self-contained, and should not depend upon @file{acconfig.h} etc.
|
|
|
|
|
|
@node autoupdate Invocation
|
|
@section Using @command{autoupdate} to Modernize @file{configure.ac}
|
|
@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.
|
|
|
|
@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.
|
|
|
|
@noindent
|
|
@command{autoupdate} accepts the following options:
|
|
|
|
@table @option
|
|
@item --help
|
|
@itemx -h
|
|
Print a summary of the command line options and exit.
|
|
|
|
@item --version
|
|
@itemx -V
|
|
Print the version number of Autoconf and exit.
|
|
|
|
@item --verbose
|
|
@itemx -v
|
|
Report processing steps.
|
|
|
|
@item --debug
|
|
@itemx -d
|
|
Don't remove the temporary files.
|
|
|
|
@item --force
|
|
@itemx -f
|
|
Force the update even if the file has not changed. Disregard the cache.
|
|
|
|
@item --include=@var{dir}
|
|
@itemx -I @var{dir}
|
|
Also look for input files in @var{dir}. Multiple invocations accumulate.
|
|
Directories are browsed from last to first.
|
|
@end table
|
|
|
|
@node Obsolete Macros
|
|
@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.
|
|
|
|
@defmac AC_ALLOCA
|
|
@acindex{ALLOCA}
|
|
@code{AC_FUNC_ALLOCA}
|
|
@end defmac
|
|
|
|
@defmac AC_ARG_ARRAY
|
|
@acindex{ARG_ARRAY}
|
|
removed because of limited usefulness
|
|
@end defmac
|
|
|
|
@defmac AC_C_CROSS
|
|
@acindex{C_CROSS}
|
|
This macro is obsolete; it does nothing.
|
|
@end defmac
|
|
|
|
@defmac AC_CANONICAL_SYSTEM
|
|
@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
|
|
@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.
|
|
@end defmac
|
|
|
|
@defmac AC_CHAR_UNSIGNED
|
|
@acindex{CHAR_UNSIGNED}
|
|
@code{AC_C_CHAR_UNSIGNED}
|
|
@end defmac
|
|
|
|
@defmac AC_CHECK_TYPE (@var{type}, @var{default})
|
|
@acindex{CHECK_TYPE}
|
|
Autoconf, up to 2.13, used to provide this version of
|
|
@code{AC_CHECK_TYPE}, deprecated because of its flaws. Firstly, although
|
|
it is a member of the @code{CHECK} clan, singular sub-family, it does
|
|
more than just checking. Secondly, missing types are not
|
|
@code{typedef}'d, they are @code{#define}'d, which can lead to
|
|
incompatible code in the case of pointer types.
|
|
|
|
This use of @code{AC_CHECK_TYPE} is obsolete and discouraged; see
|
|
@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} or @samp{unsigned}.
|
|
|
|
This macro is equivalent to:
|
|
|
|
@example
|
|
AC_CHECK_TYPE([@var{type}],,
|
|
[AC_DEFINE_UNQUOTED([@var{type}], [@var{default}],
|
|
[Define to `@var{default}' if
|
|
<sys/types.h> does not define.])])
|
|
@end example
|
|
|
|
In order to keep backward compatibility, the two versions of
|
|
@code{AC_CHECK_TYPE} are implemented, selected by a simple heuristics:
|
|
|
|
@enumerate
|
|
@item
|
|
If there are three or four arguments, the modern version is used.
|
|
|
|
@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++
|
|
@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}.
|
|
|
|
@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.
|
|
|
|
@item
|
|
Otherwise, the modern version is used.
|
|
@end enumerate
|
|
|
|
@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
|
|
@code{AC_CHECK_TYPES} together with
|
|
|
|
@example
|
|
#if !HAVE_LOFF_T
|
|
typedef loff_t off_t;
|
|
#endif
|
|
@end example
|
|
@end defmac
|
|
@c end of AC_CHECK_TYPE
|
|
|
|
@defmac AC_CHECKING (@var{feature-description})
|
|
@acindex{CHECKING}
|
|
Same as @samp{AC_MSG_NOTICE([checking @var{feature-description}@dots{}]}.
|
|
@end defmac
|
|
|
|
@defmac AC_COMPILE_CHECK (@var{echo-text}, @var{includes}, @var{function-body}, @var{action-if-found}, @ovar{action-if-not-found})
|
|
@acindex{COMPILE_CHECK}
|
|
This is an obsolete version of @code{AC_TRY_COMPILE} itself replaced by
|
|
@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
|
|
@code{AC_MSG_CHECKING} and @code{AC_MSG_RESULT} instead to print
|
|
messages (@pxref{Printing Messages}).
|
|
@end defmac
|
|
|
|
@defmac AC_CONST
|
|
@acindex{CONST}
|
|
@code{AC_C_CONST}
|
|
@end defmac
|
|
|
|
@defmac AC_CROSS_CHECK
|
|
@acindex{CROSS_CHECK}
|
|
Same as @code{AC_C_CROSS}, which is obsolete too, and does nothing
|
|
@code{:-)}.
|
|
@end defmac
|
|
|
|
@defmac AC_CYGWIN
|
|
@acindex{CYGWIN}
|
|
Check for the Cygwin environment in which case the shell variable
|
|
@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}. As a matter of fact this macro is defined as:
|
|
|
|
@example
|
|
AC_REQUIRE([AC_CANONICAL_HOST])[]dnl
|
|
case $host_os in
|
|
*cygwin* ) CYGWIN=yes;;
|
|
* ) CYGWIN=no;;
|
|
esac
|
|
@end example
|
|
|
|
Beware that the variable @code{CYGWIN} has a very special meaning when
|
|
running CygWin32, and should not be changed. That's yet another reason
|
|
not to use this macro.
|
|
@end defmac
|
|
|
|
@defmac AC_DECL_SYS_SIGLIST
|
|
@acindex{DECL_SYS_SIGLIST}
|
|
@cvindex SYS_SIGLIST_DECLARED
|
|
Same as:
|
|
|
|
@example
|
|
AC_CHECK_DECLS([sys_siglist],,,
|
|
[#include <signal.h>
|
|
/* NetBSD declares sys_siglist in unistd.h. */
|
|
#if HAVE_UNISTD_H
|
|
# include <unistd.h>
|
|
#endif
|
|
])
|
|
@end example
|
|
@end defmac
|
|
|
|
@defmac AC_DECL_YYTEXT
|
|
@acindex{DECL_YYTEXT}
|
|
Does nothing, now integrated in @code{AC_PROG_LEX}.
|
|
@end defmac
|
|
|
|
@defmac AC_DIR_HEADER
|
|
@acindex{DIR_HEADER}
|
|
@cvindex DIRENT
|
|
@cvindex SYSNDIR
|
|
@cvindex SYSDIR
|
|
@cvindex NDIR
|
|
Like calling @code{AC_FUNC_CLOSEDIR_VOID} and@code{AC_HEADER_DIRENT},
|
|
but defines a different set of C preprocessor macros to indicate which
|
|
header file is found:
|
|
|
|
@multitable {@file{sys/ndir.h}} {Old Symbol} {@code{HAVE_SYS_NDIR_H}}
|
|
@item Header @tab Old Symbol @tab New Symbol
|
|
@item @file{dirent.h} @tab @code{DIRENT} @tab @code{HAVE_DIRENT_H}
|
|
@item @file{sys/ndir.h} @tab @code{SYSNDIR} @tab @code{HAVE_SYS_NDIR_H}
|
|
@item @file{sys/dir.h} @tab @code{SYSDIR} @tab @code{HAVE_SYS_DIR_H}
|
|
@item @file{ndir.h} @tab @code{NDIR} @tab @code{HAVE_NDIR_H}
|
|
@end multitable
|
|
@end defmac
|
|
|
|
@defmac AC_DYNIX_SEQ
|
|
@acindex{DYNIX_SEQ}
|
|
If on DYNIX/ptx, add @option{-lseq} to output variable
|
|
@code{LIBS}. This macro used to be defined as
|
|
|
|
@example
|
|
AC_CHECK_LIB(seq, getmntent, LIBS="-lseq $LIBS")
|
|
@end example
|
|
|
|
@noindent
|
|
now it is just @code{AC_FUNC_GETMNTENT}.
|
|
@end defmac
|
|
|
|
@defmac AC_EXEEXT
|
|
@acindex{EXEEXT}
|
|
@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 Unix and @samp{.exe} if Win32 or OS/2.
|
|
@end defmac
|
|
|
|
@defmac AC_EMXOS2
|
|
@acindex{EMXOS2}
|
|
Similar to @code{AC_CYGWIN} but checks for the EMX environment on OS/2
|
|
and sets @code{EMXOS2}.
|
|
@end defmac
|
|
|
|
@defmac AC_ERROR
|
|
@acindex{ERROR}
|
|
@code{AC_MSG_ERROR}
|
|
@end defmac
|
|
|
|
@defmac AC_FIND_X
|
|
@acindex{FIND_X}
|
|
@code{AC_PATH_X}
|
|
@end defmac
|
|
|
|
@defmac AC_FIND_XTRA
|
|
@acindex{FIND_XTRA}
|
|
@code{AC_PATH_XTRA}
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_CHECK
|
|
@acindex{FUNC_CHECK}
|
|
@code{AC_CHECK_FUNC}
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_WAIT3
|
|
@acindex{FUNC_WAIT3}
|
|
@cvindex HAVE_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
|
|
@code{HAVE_WAIT3}.
|
|
|
|
These days portable programs should use @code{waitpid}, not
|
|
@code{wait3}, as @code{wait3} is being removed from the Open Group
|
|
standards, and will not appear in the next revision of POSIX@.
|
|
@end defmac
|
|
|
|
@defmac AC_GCC_TRADITIONAL
|
|
@acindex{GCC_TRADITIONAL}
|
|
@code{AC_PROG_GCC_TRADITIONAL}
|
|
@end defmac
|
|
|
|
@defmac AC_GETGROUPS_T
|
|
@acindex{GETGROUPS_T}
|
|
@code{AC_TYPE_GETGROUPS}
|
|
@end defmac
|
|
|
|
@defmac AC_GETLOADAVG
|
|
@acindex{GETLOADAVG}
|
|
@code{AC_FUNC_GETLOADAVG}
|
|
@end defmac
|
|
|
|
@defmac AC_HAVE_FUNCS
|
|
@acindex{HAVE_FUNCS}
|
|
@code{AC_CHECK_FUNCS}
|
|
@end defmac
|
|
|
|
@defmac AC_HAVE_HEADERS
|
|
@acindex{HAVE_HEADERS}
|
|
@code{AC_CHECK_HEADERS}
|
|
@end defmac
|
|
|
|
@defmac AC_HAVE_LIBRARY (@var{library}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
|
|
@acindex{HAVE_LIBRARY}
|
|
This macro is equivalent to calling @code{AC_CHECK_LIB} with a
|
|
@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,
|
|
@var{library} cannot be a shell variable; it must be a literal name.
|
|
@end defmac
|
|
|
|
@defmac AC_HAVE_POUNDBANG
|
|
@acindex{HAVE_POUNDBANG}
|
|
@code{AC_SYS_INTERPRETER} (different calling convention)
|
|
@end defmac
|
|
|
|
@defmac AC_HEADER_CHECK
|
|
@acindex{HEADER_CHECK}
|
|
@code{AC_CHECK_HEADER}
|
|
@end defmac
|
|
|
|
@defmac AC_HEADER_EGREP
|
|
@acindex{HEADER_EGREP}
|
|
@code{AC_EGREP_HEADER}
|
|
@end defmac
|
|
|
|
@defmac AC_HELP_STRING
|
|
@acindex{HELP_STRING}
|
|
@code{AS_HELP_STRING}
|
|
@end defmac
|
|
|
|
@defmac AC_INIT (@var{unique-file-in-source-dir})
|
|
@acindex{INIT}
|
|
Formerly @code{AC_INIT} used to have a single argument, and was
|
|
equivalent to:
|
|
|
|
@example
|
|
AC_INIT
|
|
AC_CONFIG_SRCDIR(@var{unique-file-in-source-dir})
|
|
@end example
|
|
@end defmac
|
|
|
|
@defmac AC_INLINE
|
|
@acindex{INLINE}
|
|
@code{AC_C_INLINE}
|
|
@end defmac
|
|
|
|
@defmac AC_INT_16_BITS
|
|
@acindex{INT_16_BITS}
|
|
@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.
|
|
@end defmac
|
|
|
|
@defmac AC_IRIX_SUN
|
|
@acindex{IRIX_SUN}
|
|
If on @sc{irix} (Silicon Graphics @sc{unix}), add @option{-lsun} to output
|
|
@code{LIBS}. If you were using it to get @code{getmntent}, use
|
|
@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
|
|
|
|
@example
|
|
AC_CHECK_LIB(sun, getmntent, LIBS="-lsun $LIBS")
|
|
@end example
|
|
|
|
@noindent
|
|
now it is defined as
|
|
|
|
@example
|
|
AC_FUNC_GETMNTENT
|
|
AC_CHECK_LIB(sun, getpwnam)
|
|
@end example
|
|
@end defmac
|
|
|
|
@defmac AC_LANG_C
|
|
@acindex{LANG_C}
|
|
Same as @samp{AC_LANG(C)}.
|
|
@end defmac
|
|
|
|
@defmac AC_LANG_CPLUSPLUS
|
|
@acindex{LANG_CPLUSPLUS}
|
|
Same as @samp{AC_LANG(C++)}.
|
|
@end defmac
|
|
|
|
@defmac AC_LANG_FORTRAN77
|
|
@acindex{LANG_FORTRAN77}
|
|
Same as @samp{AC_LANG(Fortran 77)}.
|
|
@end defmac
|
|
|
|
@defmac AC_LANG_RESTORE
|
|
@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
|
|
@code{AC_LANG(@var{language})}.
|
|
@end defmac
|
|
|
|
@defmac AC_LANG_SAVE
|
|
@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.
|
|
@end defmac
|
|
|
|
@defmac AC_LINK_FILES (@var{source}@dots{}, @var{dest}@dots{})
|
|
@acindex{LINK_FILES}
|
|
This is an obsolete version of @code{AC_CONFIG_LINKS}. An updated
|
|
version of:
|
|
|
|
@example
|
|
AC_LINK_FILES(config/$machine.h config/$obj_format.h,
|
|
host.h object.h)
|
|
@end example
|
|
|
|
@noindent
|
|
is:
|
|
|
|
@example
|
|
AC_CONFIG_LINKS(host.h:config/$machine.h
|
|
object.h:config/$obj_format.h)
|
|
@end example
|
|
@end defmac
|
|
|
|
@defmac AC_LN_S
|
|
@acindex{LN_S}
|
|
@code{AC_PROG_LN_S}
|
|
@end defmac
|
|
|
|
@defmac AC_LONG_64_BITS
|
|
@acindex{LONG_64_BITS}
|
|
@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.
|
|
@end defmac
|
|
|
|
@defmac AC_LONG_DOUBLE
|
|
@acindex{LONG_DOUBLE}
|
|
@code{AC_C_LONG_DOUBLE}
|
|
@end defmac
|
|
|
|
@defmac AC_LONG_FILE_NAMES
|
|
@acindex{LONG_FILE_NAMES}
|
|
@code{AC_SYS_LONG_FILE_NAMES}
|
|
@end defmac
|
|
|
|
@defmac AC_MAJOR_HEADER
|
|
@acindex{MAJOR_HEADER}
|
|
@code{AC_HEADER_MAJOR}
|
|
@end defmac
|
|
|
|
@defmac AC_MEMORY_H
|
|
@acindex{MEMORY_H}
|
|
@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
|
|
@samp{AC_CHECK_HEADERS(memory.h)}. Adjust your code to depend upon
|
|
@code{HAVE_MEMORY_H}, not @code{NEED_MEMORY_H}; see @ref{Standard
|
|
Symbols}.
|
|
@end defmac
|
|
|
|
@defmac AC_MINGW32
|
|
@acindex{MINGW32}
|
|
Similar to @code{AC_CYGWIN} but checks for the MingW32 compiler
|
|
environment and sets @code{MINGW32}.
|
|
@end defmac
|
|
|
|
@defmac AC_MINUS_C_MINUS_O
|
|
@acindex{MINUS_C_MINUS_O}
|
|
@code{AC_PROG_CC_C_O}
|
|
@end defmac
|
|
|
|
@defmac AC_MMAP
|
|
@acindex{MMAP}
|
|
@code{AC_FUNC_MMAP}
|
|
@end defmac
|
|
|
|
@defmac AC_MODE_T
|
|
@acindex{MODE_T}
|
|
@code{AC_TYPE_MODE_T}
|
|
@end defmac
|
|
|
|
@defmac AC_OBJEXT
|
|
@acindex{OBJEXT}
|
|
@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 Unix, @samp{obj} if Win32. Now the compiler checking macros handle
|
|
this automatically.
|
|
@end defmac
|
|
|
|
@defmac AC_OBSOLETE (@var{this-macro-name}, @ovar{suggestion})
|
|
@acindex{OBSOLETE}
|
|
Make M4 print a message to the standard error output warning that
|
|
@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
|
|
|
|
@example
|
|
AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl
|
|
@end example
|
|
|
|
You are encouraged to use @code{AU_DEFUN} instead, since it gives better
|
|
services to the user.
|
|
@end defmac
|
|
|
|
@defmac AC_OFF_T
|
|
@acindex{OFF_T}
|
|
@code{AC_TYPE_OFF_T}
|
|
@end defmac
|
|
|
|
@defmac AC_OUTPUT (@ovar{file}@dots{}, @ovar{extra-cmds}, @ovar{init-cmds})
|
|
@acindex{OUTPUT}
|
|
The use of @code{AC_OUTPUT} with argument is deprecated. This obsoleted
|
|
interface is equivalent to:
|
|
|
|
@example
|
|
@group
|
|
AC_CONFIG_FILES(@var{file}@dots{})
|
|
AC_CONFIG_COMMANDS([default],
|
|
@var{extra-cmds}, @var{init-cmds})
|
|
AC_OUTPUT
|
|
@end group
|
|
@end example
|
|
@end defmac
|
|
|
|
@defmac AC_OUTPUT_COMMANDS (@var{extra-cmds}, @ovar{init-cmds})
|
|
@acindex{OUTPUT_COMMANDS}
|
|
Specify additional shell commands to run at the end of
|
|
@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}.
|
|
|
|
Here is an unrealistic example:
|
|
|
|
@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])
|
|
@end example
|
|
|
|
Aside from the fact that @code{AC_CONFIG_COMMANDS} requires an
|
|
additional key, an important difference is that
|
|
@code{AC_OUTPUT_COMMANDS} is quoting its arguments twice, unlike
|
|
@code{AC_CONFIG_COMMANDS}. This means that @code{AC_CONFIG_COMMANDS}
|
|
can safely be given macro calls as arguments:
|
|
|
|
@example
|
|
AC_CONFIG_COMMANDS(foo, [my_FOO()])
|
|
@end example
|
|
|
|
@noindent
|
|
Conversely, where one level of quoting was enough for literal strings
|
|
with @code{AC_OUTPUT_COMMANDS}, you need two with
|
|
@code{AC_CONFIG_COMMANDS}. The following lines are equivalent:
|
|
|
|
@example
|
|
@group
|
|
AC_OUTPUT_COMMANDS([echo "Square brackets: []"])
|
|
AC_CONFIG_COMMANDS([default], [[echo "Square brackets: []"]])
|
|
@end group
|
|
@end example
|
|
@end defmac
|
|
|
|
@defmac AC_PID_T
|
|
@acindex{PID_T}
|
|
@code{AC_TYPE_PID_T}
|
|
@end defmac
|
|
|
|
@defmac AC_PREFIX
|
|
@acindex{PREFIX}
|
|
@code{AC_PREFIX_PROGRAM}
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_CC_STDC
|
|
@acindex{PROG_CC_STDC}
|
|
This macro has been integrated into @code{AC_PROG_CC}.
|
|
@end defmac
|
|
|
|
@defmac AC_PROGRAMS_CHECK
|
|
@acindex{PROGRAMS_CHECK}
|
|
@code{AC_CHECK_PROGS}
|
|
@end defmac
|
|
|
|
@defmac AC_PROGRAMS_PATH
|
|
@acindex{PROGRAMS_PATH}
|
|
@code{AC_PATH_PROGS}
|
|
@end defmac
|
|
|
|
@defmac AC_PROGRAM_CHECK
|
|
@acindex{PROGRAM_CHECK}
|
|
@code{AC_CHECK_PROG}
|
|
@end defmac
|
|
|
|
@defmac AC_PROGRAM_EGREP
|
|
@acindex{PROGRAM_EGREP}
|
|
@code{AC_EGREP_CPP}
|
|
@end defmac
|
|
|
|
@defmac AC_PROGRAM_PATH
|
|
@acindex{PROGRAM_PATH}
|
|
@code{AC_PATH_PROG}
|
|
@end defmac
|
|
|
|
@defmac AC_REMOTE_TAPE
|
|
@acindex{REMOTE_TAPE}
|
|
removed because of limited usefulness
|
|
@end defmac
|
|
|
|
@defmac AC_RESTARTABLE_SYSCALLS
|
|
@acindex{RESTARTABLE_SYSCALLS}
|
|
@code{AC_SYS_RESTARTABLE_SYSCALLS}
|
|
@end defmac
|
|
|
|
@defmac AC_RETSIGTYPE
|
|
@acindex{RETSIGTYPE}
|
|
@code{AC_TYPE_SIGNAL}
|
|
@end defmac
|
|
|
|
@defmac AC_RSH
|
|
@acindex{RSH}
|
|
removed because of limited usefulness
|
|
@end defmac
|
|
|
|
@defmac AC_SCO_INTL
|
|
@acindex{SCO_INTL}
|
|
@ovindex LIBS
|
|
If on SCO UNIX, add @option{-lintl} to output variable @code{LIBS}. This
|
|
macro used to
|
|
|
|
@example
|
|
AC_CHECK_LIB(intl, strftime, LIBS="-lintl $LIBS")
|
|
@end example
|
|
|
|
@noindent
|
|
Now it just calls @code{AC_FUNC_STRFTIME} instead.
|
|
@end defmac
|
|
|
|
@defmac AC_SETVBUF_REVERSED
|
|
@acindex{SETVBUF_REVERSED}
|
|
@code{AC_FUNC_SETVBUF_REVERSED}
|
|
@end defmac
|
|
|
|
@defmac AC_SET_MAKE
|
|
@acindex{SET_MAKE}
|
|
@code{AC_PROG_MAKE_SET}
|
|
@end defmac
|
|
|
|
@defmac AC_SIZEOF_TYPE
|
|
@acindex{SIZEOF_TYPE}
|
|
@code{AC_CHECK_SIZEOF}
|
|
@end defmac
|
|
|
|
@defmac AC_SIZE_T
|
|
@acindex{SIZE_T}
|
|
@code{AC_TYPE_SIZE_T}
|
|
@end defmac
|
|
|
|
@defmac AC_STAT_MACROS_BROKEN
|
|
@acindex{STAT_MACROS_BROKEN}
|
|
@code{AC_HEADER_STAT}
|
|
@end defmac
|
|
|
|
@defmac AC_STDC_HEADERS
|
|
@acindex{STDC_HEADERS}
|
|
@code{AC_HEADER_STDC}
|
|
@end defmac
|
|
|
|
@defmac AC_STRCOLL
|
|
@acindex{STRCOLL}
|
|
@code{AC_FUNC_STRCOLL}
|
|
@end defmac
|
|
|
|
@defmac AC_ST_BLKSIZE
|
|
@acindex{ST_BLKSIZE}
|
|
@code{AC_CHECK_MEMBERS}
|
|
@end defmac
|
|
|
|
@defmac AC_ST_BLOCKS
|
|
@acindex{ST_BLOCKS}
|
|
@code{AC_STRUCT_ST_BLOCKS}
|
|
@end defmac
|
|
|
|
@defmac AC_ST_RDEV
|
|
@acindex{ST_RDEV}
|
|
@code{AC_CHECK_MEMBERS}
|
|
@end defmac
|
|
|
|
@defmac AC_SYS_RESTARTABLE_SYSCALLS
|
|
@acindex{SYS_RESTARTABLE_SYSCALLS}
|
|
@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 if system calls are restarted in general--it tests whether a
|
|
signal handler installed with @code{signal} (but not @code{sigaction})
|
|
causes system calls to be restarted. It does not test if system calls
|
|
can be restarted when interrupted by signals that have no handler.
|
|
|
|
These days portable programs should use @code{sigaction} with
|
|
@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.
|
|
@end defmac
|
|
|
|
@defmac AC_SYS_SIGLIST_DECLARED
|
|
@acindex{SYS_SIGLIST_DECLARED}
|
|
@code{AC_DECL_SYS_SIGLIST}
|
|
@end defmac
|
|
|
|
@defmac AC_TEST_CPP
|
|
@acindex{TEST_CPP}
|
|
@code{AC_TRY_CPP}, replaced by @code{AC_PREPROC_IFELSE}.
|
|
@end defmac
|
|
|
|
@defmac AC_TEST_PROGRAM
|
|
@acindex{TEST_PROGRAM}
|
|
@code{AC_TRY_RUN}, replaced by @code{AC_RUN_IFELSE}.
|
|
@end defmac
|
|
|
|
@defmac AC_TIMEZONE
|
|
@acindex{TIMEZONE}
|
|
@code{AC_STRUCT_TIMEZONE}
|
|
@end defmac
|
|
|
|
@defmac AC_TIME_WITH_SYS_TIME
|
|
@acindex{TIME_WITH_SYS_TIME}
|
|
@code{AC_HEADER_TIME}
|
|
@end defmac
|
|
|
|
@defmac AC_TRY_COMPILE (@var{includes}, @var{function-body}, @ovar{action-if-found}, @ovar{action-if-not-found})
|
|
@acindex{TRY_COMPILE}
|
|
Same as @samp{AC_COMPILE_IFELSE([AC_LANG_SOURCE([[@var{includes}]],
|
|
[[@var{function-body}]])], [@var{action-if-true}],
|
|
[@var{action-if-false}])} (@pxref{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} will be 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}).
|
|
@end defmac
|
|
|
|
@defmac AC_TRY_CPP (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
|
|
@acindex{TRY_CPP}
|
|
Same as @samp{AC_PREPROC_IFELSE([AC_LANG_SOURCE([[@var{input}]])],
|
|
[@var{action-if-true}], [@var{action-if-false}])} (@pxref{Running the
|
|
Preprocessor}).
|
|
|
|
This macro double quotes the @var{input}.
|
|
@end defmac
|
|
|
|
@defmac AC_TRY_LINK (@var{includes}, @var{function-body}, @ovar{action-if-found}, @ovar{action-if-not-found})
|
|
@acindex{TRY_LINK}
|
|
Same as @samp{AC_LINK_IFELSE([AC_LANG_SOURCE([[@var{includes}]],
|
|
[[@var{function-body}]])], [@var{action-if-true}],
|
|
[@var{action-if-false}])} (@pxref{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
|
|
@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} will be 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
|
|
@code{LIBS} are used for linking.
|
|
@end defmac
|
|
|
|
@defmac AC_TRY_LINK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found})
|
|
@acindex{TRY_LINK_FUNC}
|
|
This macro is equivalent to
|
|
@samp{AC_LINK_IFELSE([AC_LANG_CALL([[@var{includes}]],
|
|
[[@var{function-body}]])], [@var{action-if-true}],
|
|
[@var{action-if-false}])}.
|
|
@end defmac
|
|
|
|
@defmac AC_TRY_RUN (@var{program}, @ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-cross-compiling})
|
|
@acindex{TRY_RUN}
|
|
Same as @samp{AC_RUN_IFELSE([AC_LANG_SOURCE([[@var{program}]],
|
|
[@var{action-if-true}], [@var{action-if-false}],
|
|
[@var{action-if-cross-compiling}])} (@pxref{Run Time}).
|
|
@end defmac
|
|
|
|
|
|
@defmac AC_UID_T
|
|
@acindex{UID_T}
|
|
@code{AC_TYPE_UID_T}
|
|
@end defmac
|
|
|
|
@defmac AC_UNISTD_H
|
|
@acindex{UNISTD_H}
|
|
Same as @samp{AC_CHECK_HEADERS(unistd.h)}.
|
|
@end defmac
|
|
|
|
@defmac AC_USG
|
|
@acindex{USG}
|
|
@cvindex USG
|
|
Define @code{USG} if the @acronym{BSD} string functions are defined in
|
|
@file{strings.h}. You should no longer depend upon @code{USG}, but on
|
|
@code{HAVE_STRING_H}; see @ref{Standard Symbols}.
|
|
@end defmac
|
|
|
|
@defmac AC_UTIME_NULL
|
|
@acindex{UTIME_NULL}
|
|
@code{AC_FUNC_UTIME_NULL}
|
|
@end defmac
|
|
|
|
@defmac AC_VALIDATE_CACHED_SYSTEM_TUPLE (@ovar{cmd})
|
|
@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.
|
|
@end defmac
|
|
|
|
@defmac AC_VERBOSE (@var{result-description})
|
|
@acindex{VERBOSE}
|
|
@code{AC_MSG_RESULT}.
|
|
@end defmac
|
|
|
|
@defmac AC_VFORK
|
|
@acindex{VFORK}
|
|
@code{AC_FUNC_VFORK}
|
|
@end defmac
|
|
|
|
@defmac AC_VPRINTF
|
|
@acindex{VPRINTF}
|
|
@code{AC_FUNC_VPRINTF}
|
|
@end defmac
|
|
|
|
@defmac AC_WAIT3
|
|
@acindex{WAIT3}
|
|
@code{AC_FUNC_WAIT3}
|
|
@end defmac
|
|
|
|
@defmac AC_WARN
|
|
@acindex{WARN}
|
|
@code{AC_MSG_WARN}
|
|
@end defmac
|
|
|
|
@defmac AC_WORDS_BIGENDIAN
|
|
@acindex{WORDS_BIGENDIAN}
|
|
@code{AC_C_BIGENDIAN}
|
|
@end defmac
|
|
|
|
@defmac AC_XENIX_DIR
|
|
@acindex{XENIX_DIR}
|
|
@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
|
|
@option{-ldir} to @code{LIBS}. Now it is merely an alias of
|
|
@code{AC_HEADER_DIRENT} instead, plus some code to detect whether
|
|
running @sc{xenix} on which you should not depend:
|
|
|
|
@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=])
|
|
@end example
|
|
@end defmac
|
|
|
|
@defmac AC_YYTEXT_POINTER
|
|
@acindex{YYTEXT_POINTER}
|
|
@code{AC_DECL_YYTEXT}
|
|
@end defmac
|
|
|
|
@node Autoconf 1
|
|
@section Upgrading From Version 1
|
|
|
|
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
|
|
@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.
|
|
|
|
@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
|
|
@end menu
|
|
|
|
@node Changed File Names
|
|
@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
|
|
@file{acsite.m4}. @xref{autoconf Invocation}.
|
|
|
|
If you distribute @file{install.sh} with your package, rename it to
|
|
@file{install-sh} so @code{make} builtin rules won'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
|
|
@file{acconfig.h}, you still can, but you will have less clutter if you
|
|
use the @code{AH_} macros. @xref{Autoheader Macros}.
|
|
|
|
@node Changed Makefiles
|
|
@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
|
|
@code{AC_OUTPUT}, so that the output files will 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
|
|
@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}:
|
|
|
|
@example
|
|
prefix = /usr/local
|
|
exec_prefix = $(prefix)
|
|
@end example
|
|
|
|
@noindent
|
|
you must change it to:
|
|
|
|
@example
|
|
prefix = @@prefix@@
|
|
exec_prefix = @@exec_prefix@@
|
|
@end example
|
|
|
|
@noindent
|
|
The old behavior of replacing those variables without @samp{@@}
|
|
characters around them has been removed.
|
|
|
|
@node Changed Macros
|
|
@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.
|
|
@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 will generally work 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 @code{echo} or @code{AC_VERBOSE} (perhaps
|
|
via @code{AC_COMPILE_CHECK}), your @command{configure} script's output will
|
|
look better if you switch to @code{AC_MSG_CHECKING} and
|
|
@code{AC_MSG_RESULT}. @xref{Printing Messages}. Those macros work best
|
|
in conjunction with cache variables. @xref{Caching Results}.
|
|
|
|
|
|
|
|
@node Changed Results
|
|
@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
|
|
@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:
|
|
|
|
@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="$saved_LIBS -l$lib"
|
|
AC_HAVE_FUNCS(syslog)
|
|
case "$DEFS" in
|
|
*-DHAVE_SYSLOG*) break ;;
|
|
*) ;;
|
|
esac
|
|
LIBS="$saved_LIBS"
|
|
done ;;
|
|
esac
|
|
@end example
|
|
|
|
Here is a way to write it for version 2:
|
|
|
|
@example
|
|
AC_CHECK_FUNCS(syslog)
|
|
if test $ac_cv_func_syslog = no; 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="$LIBS -l$lib"; break])
|
|
done
|
|
fi
|
|
@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.
|
|
@xref{Setting Output Variables}.
|
|
|
|
All of the Boolean shell variables set by Autoconf macros now use
|
|
@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
|
|
@samp{t} for true, you need to change your tests.
|
|
|
|
@node Changed Macro Writing
|
|
@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
|
|
@code{AC_PROVIDE} and ensures that macros called via @code{AC_REQUIRE}
|
|
do not interrupt other macros, to prevent nested @samp{checking@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.
|
|
|
|
|
|
@node Autoconf 2.13
|
|
@section Upgrading From Version 2.13
|
|
|
|
The introduction of the previous section (@pxref{Autoconf 1}) perfectly
|
|
suits this section@enddots{}
|
|
|
|
@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
|
|
@file{NEWS} in the Autoconf distribution.
|
|
@end quotation
|
|
|
|
@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_FOO_IFELSE vs AC_TRY_FOO:: A more generic scheme for testing sources
|
|
@end menu
|
|
|
|
@node Changed Quotation
|
|
@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:
|
|
|
|
@example
|
|
AC_INIT
|
|
AC_CHECK_HEADERS(foo.h,,
|
|
AC_MSG_ERROR(cannot find foo.h, bailing out))
|
|
AC_OUTPUT
|
|
@end example
|
|
|
|
@noindent
|
|
Autoconf 2.13 simply ignores it:
|
|
|
|
@example
|
|
$ @kbd{autoconf-2.13; ./configure --silent}
|
|
creating cache ./config.cache
|
|
configure: error: cannot find foo.h
|
|
$
|
|
@end example
|
|
|
|
@noindent
|
|
while Autoconf 2.50 will produce a broken @file{configure}:
|
|
|
|
@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'
|
|
$
|
|
@end example
|
|
|
|
The message needs to be quoted, and the @code{AC_MSG_ERROR} invocation
|
|
too!
|
|
|
|
@example
|
|
AC_INIT
|
|
AC_CHECK_HEADERS(foo.h,,
|
|
[AC_MSG_ERROR([cannot find foo.h, bailing out])])
|
|
AC_OUTPUT
|
|
@end example
|
|
|
|
Many many (and many more) Autoconf macros were lacking proper quotation,
|
|
including no less than@dots{} @code{AC_DEFUN} itself!
|
|
|
|
@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}
|
|
$
|
|
@end example
|
|
|
|
|
|
@node New Macros
|
|
@subsection New Macros
|
|
|
|
@cindex undefined macro
|
|
@cindex @code{_m4_divert_diversion}
|
|
|
|
Because Autoconf has been dormant for years, Automake provided
|
|
Autoconf-like macros for a while. Autoconf 2.50 now provides better
|
|
versions of these macros, integrated in the @code{AC_} namespace,
|
|
instead of @code{AM_}. But in order to ease the upgrading via
|
|
@command{autoupdate}, bindings to such @code{AM_} macros are provided.
|
|
|
|
Unfortunately Automake did not quote the names of these macros!
|
|
Therefore, when @command{m4} finds something like
|
|
@samp{AC_DEFUN(AM_TYPE_PTRDIFF_T, @dots{})} in @file{aclocal.m4},
|
|
@code{AM_TYPE_PTRDIFF_T} is
|
|
expanded, replaced with its Autoconf definition.
|
|
|
|
Fortunately Autoconf catches pre-@code{AC_INIT} expansions, and will
|
|
complain, in its own words:
|
|
|
|
@example
|
|
$ @kbd{cat configure.in}
|
|
AC_INIT
|
|
AM_TYPE_PTRDIFF_T
|
|
$ @kbd{aclocal-1.4}
|
|
$ @kbd{autoconf}
|
|
./aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion
|
|
actypes.m4:289: AM_TYPE_PTRDIFF_T is expanded from...
|
|
./aclocal.m4:17: the top level
|
|
$
|
|
@end example
|
|
|
|
Future versions of Automake will simply no longer define most of these
|
|
macros, and will properly quote the names of the remaining macros.
|
|
But you don't have to wait for it to happen to do the right thing right
|
|
now: do not depend upon macros from Automake as it is simply not its job
|
|
to provide macros (but the one it requires itself):
|
|
|
|
@example
|
|
$ @kbd{cat configure.in}
|
|
AC_INIT
|
|
AM_TYPE_PTRDIFF_T
|
|
$ @kbd{rm aclocal.m4}
|
|
$ @kbd{autoupdate}
|
|
autoupdate: `configure.in' is updated
|
|
$ @kbd{cat configure.in}
|
|
AC_INIT
|
|
AC_CHECK_TYPES([ptrdiff_t])
|
|
$ @kbd{aclocal-1.4}
|
|
$ @kbd{autoconf}
|
|
$
|
|
@end example
|
|
|
|
|
|
@node Hosts and Cross-Compilation
|
|
@subsection Hosts and Cross-Compilation
|
|
|
|
Based on the experience of compiler writers, and after long public
|
|
debates, many aspects of the cross-compilation chain have changed:
|
|
|
|
@itemize @minus
|
|
@item
|
|
the relationship between the build, host, and target architecture types,
|
|
|
|
@item
|
|
the command line interface for specifying them to @command{configure},
|
|
|
|
@item
|
|
the variables defined in @command{configure},
|
|
|
|
@item
|
|
the enabling of cross-compilation mode.
|
|
@end itemize
|
|
|
|
@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} will enter cross compilation
|
|
mode, so it won'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}. In the future,
|
|
@option{--host} will not override the name of the build system type.
|
|
Whenever you specify @code{--host}, be sure to specify @code{--build}
|
|
too.
|
|
|
|
@sp 1
|
|
|
|
For backward compatibility, @command{configure} will accept a system
|
|
type as an option by itself. Such an option will override the
|
|
defaults for build, host, and target system types. The following
|
|
configure statement will configure a cross toolchain that will run on
|
|
Net@acronym{BSD}/alpha but generate code for @acronym{GNU} Hurd/sparc, which is
|
|
also the build platform.
|
|
|
|
@example
|
|
./configure --host=alpha-netbsd sparc-gnu
|
|
@end example
|
|
|
|
@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
|
|
@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 will be assumed to be the same as @option{--host}, and
|
|
@samp{build_alias} will be set to that value. Eventually, this
|
|
historically incorrect behavior will go away.
|
|
|
|
@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.
|
|
@command{configure} could even enter cross-compilation mode only
|
|
because the compiler was not functional. This is mainly because
|
|
@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
|
|
@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
|
|
@command{configure} performs the first compiler test it will try to run
|
|
an executable produced by the compiler. If the execution fails, it will
|
|
enter 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 @code{--host}, be sure to specify
|
|
@code{--build} too.
|
|
|
|
@example
|
|
./configure --build=i686-pc-linux-gnu --host=m68k-coff
|
|
@end example
|
|
|
|
@noindent
|
|
will enter cross-compilation mode. The former interface, which
|
|
consisted in setting the compiler to a cross-compiler without informing
|
|
@command{configure} is obsolete. For instance, @command{configure} will
|
|
fail if it can't run the code generated by the specified compiler if you
|
|
configure as follows:
|
|
|
|
@example
|
|
./configure CC=m68k-coff-gcc
|
|
@end example
|
|
|
|
|
|
@node AC_LIBOBJ vs LIBOBJS
|
|
@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
|
|
@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 @acronym{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.
|
|
|
|
@sp 1
|
|
|
|
As for function replacement, the fix is immediate: use
|
|
@code{AC_LIBOBJ}. For instance:
|
|
|
|
@example
|
|
LIBOBJS="$LIBOBJS fnmatch.o"
|
|
LIBOBJS="$LIBOBJS malloc.$ac_objext"
|
|
@end example
|
|
|
|
@noindent
|
|
should be replaced with:
|
|
|
|
@example
|
|
AC_LIBOBJ([fnmatch])
|
|
AC_LIBOBJ([malloc])
|
|
@end example
|
|
|
|
@sp 1
|
|
|
|
@ovindex U
|
|
@cindex @code{$U}
|
|
When asked for automatic de-ANSI-fication, Automake needs
|
|
@code{LIBOBJS}'ed filenames to have @samp{$U} appended to the base
|
|
names. Libtool requires the definition of @code{LTLIBOBJS}, whose
|
|
suffixes are mapped to @samp{.lo}. People used to run snippets such as:
|
|
|
|
@example
|
|
# This is necessary so that .o files in LIBOBJS are also built via
|
|
# the ANSI2KNR-filtering rules.
|
|
LIBOBJS=`echo "$LIBOBJS" | sed 's/\.o /\$U.o /g;s/\.o$/\$U.o/'`
|
|
LTLIBOBJS=`echo "$LIBOBJS" | sed 's/\.o/\.lo/g'`
|
|
AC_SUBST(LTLIBOBJS)
|
|
@end example
|
|
|
|
@noindent
|
|
Note that this code is @emph{wrong}, because @samp{.o} is not the only
|
|
possible extension@footnote{
|
|
@c
|
|
Yet another reason why assigning @code{LIBOBJS} directly is discouraged.
|
|
@c
|
|
}! It should have read:
|
|
|
|
@example
|
|
# This is necessary so that .o files in LIBOBJS are also built via
|
|
# the ANSI2KNR-filtering rules.
|
|
LIB@@&t@@OBJS=`echo "$LIB@@&t@@OBJS" |
|
|
sed 's,\.[[^.]]* ,$U&,g;s,\.[[^.]]*$,$U&,'`
|
|
LTLIBOBJS=`echo "$LIB@@&t@@OBJS" |
|
|
sed 's,\.[[^.]]* ,.lo ,g;s,\.[[^.]]*$,.lo,'`
|
|
AC_SUBST(LTLIBOBJS)
|
|
@end example
|
|
|
|
@sp 1
|
|
|
|
You no longer have to use this: @code{AC_OUTPUT} normalizes
|
|
@code{LIBOBJS} and @code{LTLIBOBJS} (hence it works with any version of
|
|
Automake and Libtool). Just remove these lines (@command{autoupdate}
|
|
cannot handle this task, since this is not a macro).
|
|
|
|
Note that @code{U} must not be used in your Makefiles.
|
|
|
|
|
|
@node AC_FOO_IFELSE vs AC_TRY_FOO
|
|
@subsection @code{AC_FOO_IFELSE} vs.@: @code{AC_TRY_FOO}
|
|
|
|
Since Autoconf 2.50, internal codes uses @code{AC_PREPROC_IFELSE},
|
|
@code{AC_COMPILE_IFELSE}, @code{AC_LINK_IFELSE}, and
|
|
@code{AC_RUN_IFELSE} on one hand and @code{AC_LANG_SOURCES},
|
|
and @code{AC_LANG_PROGRAM} on the other hand instead of the deprecated
|
|
@code{AC_TRY_CPP}, @code{AC_TRY_COMPILE}, @code{AC_TRY_LINK}, and
|
|
@code{AC_TRY_RUN}. The motivations where:
|
|
@itemize @minus
|
|
@item
|
|
a more consistent interface: @code{AC_TRY_COMPILE} etc.@: were double
|
|
quoting their arguments;
|
|
|
|
@item
|
|
the combinatoric explosion is solved by decomposing on the one hand the
|
|
generation of sources, and on the other hand executing the program;
|
|
|
|
@item
|
|
this scheme helps supporting more languages than plain C and C++.
|
|
@end itemize
|
|
|
|
In addition to the change of syntax, the philosphy 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..., 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
|
|
@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 @samp{#include}s.
|
|
|
|
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}:
|
|
|
|
@example
|
|
@group
|
|
AC_EGREP_CPP(yes,
|
|
[#ifdef _AIX
|
|
yes
|
|
#endif
|
|
], is_aix=yes, is_aix=no)
|
|
@end group
|
|
@end example
|
|
|
|
The above example, properly written would (i) use
|
|
@code{AC_LANG_PROGRAM}, and (ii) run the compiler:
|
|
|
|
@example
|
|
@group
|
|
AC_COMPILE_IFELSE([AC_LANG_PROGRAM(
|
|
[[#if !defined _AIX
|
|
# error _AIX not defined
|
|
#endif
|
|
]])],
|
|
[is_aix=yes],
|
|
[is_aix=no])
|
|
@end group
|
|
@end example
|
|
|
|
|
|
@c ============================= Generating Test Suites with Autotest
|
|
|
|
@node Using Autotest
|
|
@chapter Generating Test Suites with Autotest
|
|
|
|
@cindex Autotest
|
|
|
|
@display
|
|
@strong{N.B.: This section describes an experimental feature which will
|
|
be part of Autoconf in a forthcoming release. Although we believe
|
|
Autotest is stabilizing, this documentation describes an interface which
|
|
might change in the future: do not depend upon Autotest without
|
|
subscribing to the Autoconf mailing lists.}
|
|
@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 Deja@acronym{GNU}, a rich and complex testing
|
|
framework, but which is far from being standard on Unix 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 output
|
|
are their exit status: the test succeeded, or failed. In addition, most
|
|
of these tests share some common patterns, what results in lots of
|
|
duplicated code, tedious maintenance etc.
|
|
|
|
Following exactly the same reasoning that yielded to the inception of
|
|
Autoconf, Autotest provides a test suite generation frame work, 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, @acronym{GNU} Tar, each of
|
|
them having different needs, what slowly polishes Autotest as a general
|
|
testing framework.
|
|
|
|
Nonetheless, compared to Deja@acronym{GNU}, Autotest is inadequate for
|
|
interactive tool testing, which is probably its main limitation.
|
|
|
|
@menu
|
|
* Using an Autotest Test Suite:: Autotest and the user
|
|
* Writing testsuite.at:: Autotest macros
|
|
* testsuite Invocation:: Running @command{testsuite} scripts
|
|
* Making testsuite Scripts:: Using autom4te to create @command{testsuite}
|
|
@end menu
|
|
|
|
@node Using an Autotest Test Suite
|
|
@section Using an Autotest Test Suite
|
|
|
|
@menu
|
|
* testsuite Scripts:: The concepts of Autotest
|
|
* Autotest Logs:: Their contents
|
|
@end menu
|
|
|
|
@node testsuite Scripts
|
|
@subsection @command{testsuite} Scripts
|
|
|
|
@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
|
|
@command{autom4te}, itself using @acronym{GNU} M4 under the scene, to
|
|
produce a stand-alone Bourne shell script which then gets distributed.
|
|
Neither @command{autom4te} nor @acronym{GNU} M4 are not needed anymore at
|
|
the installer end.
|
|
|
|
@cindex test group
|
|
Each test of the validation suite should be part of some test group. A
|
|
@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 than a later test in the same group needs to read. Complex test
|
|
groups make later debugging more tedious. It is much better keeping
|
|
keep only a few tests per test group, and if you can put only one test
|
|
per test group, this is just ideal.
|
|
|
|
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 @file{testsuite.at}
|
|
only initializes the whole validation suite, and sometimes do 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
|
|
@file{testsuite.at} be a simple list of @code{m4_include} 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
|
|
@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
|
|
@file{testsuite.dir/@var{nn}}, where @var{nn} is the sequence number of
|
|
the test group, and they include:
|
|
|
|
@itemize @bullet
|
|
@item a debugging script named @file{run} which reruns the test in
|
|
@dfn{debug mode} (@pxref{testsuite Invocation}). The automatic generation
|
|
of debugging scripts has the purpose of easing the chase for bugs.
|
|
|
|
@item all the files created with @code{AT_DATA}
|
|
|
|
@item a log of the run, named @file{testsuite.log}
|
|
@end itemize
|
|
|
|
In the ideal situation, none of the tests fail, and consequently, no
|
|
debugging directory is left out of 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
|
|
@code{AC_CONFIG_TESTDIR}. For configuration informations 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.
|
|
|
|
@noindent
|
|
Files used in preparing a software package for distribution:
|
|
|
|
@example
|
|
[package.m4] -->.
|
|
\
|
|
subfile-1.at ->. [local.at] ---->+
|
|
... \ \
|
|
subfile-i.at ---->-- testsuite.at -->-- autom4te* -->testsuite
|
|
... /
|
|
subfile-n.at ->'
|
|
@end example
|
|
|
|
@noindent
|
|
Files used in configuring a software package:
|
|
|
|
@example
|
|
.--> atconfig
|
|
/
|
|
[atlocal.in] --> config.status* --<
|
|
\
|
|
`--> [atlocal]
|
|
@end example
|
|
|
|
@noindent
|
|
Files created during the test suite execution:
|
|
|
|
@example
|
|
atconfig -->. .--> testsuite.log
|
|
\ /
|
|
>-- testsuite* --<
|
|
/ \
|
|
[atlocal] ->' `--> [testsuite.dir]
|
|
@end example
|
|
|
|
|
|
@node Autotest Logs
|
|
@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:
|
|
|
|
@table @asis
|
|
@item command line arguments
|
|
@c akim s/to consist in/to consist of/
|
|
A very bad Unix habit which is unfortunately wide spread consists of
|
|
setting environment variables before the command, such as in
|
|
@samp{CC=my-home-grown-cc ./testsuite}. This results in the test suite
|
|
not knowing this change, hence (i) it can't 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 the user changed.
|
|
|
|
@item @file{ChangeLog} excerpts
|
|
The topmost lines of all the @file{ChangeLog}s 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
|
|
@file{ChangeLog}.
|
|
|
|
@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,
|
|
@var{host} = @var{build}. The log contains relevant information on the
|
|
state of the build machine, including some important environment
|
|
variables.
|
|
@c FIXME: How about having an M4sh macro to say `hey, log the value
|
|
@c of `@dots{}'? This would help both Autoconf and Autotest.
|
|
|
|
@item tested programs
|
|
The absolute path and answers to @option{--version} of the tested
|
|
programs (see @ref{Writing testsuite.at}, @code{AT_TESTED}).
|
|
|
|
@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.
|
|
@end table
|
|
|
|
|
|
@node Writing testsuite.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} nears
|
|
its beginning followed by one call to @code{m4_include} per source file
|
|
for tests. Each such included file, or the remainder of
|
|
@file{testsuite.at} if include files are not used, contain a sequence of
|
|
test groups. Each test group begins with one call to @code{AT_SETUP},
|
|
it contains an arbitrary number of shell commands or calls to
|
|
@code{AT_CHECK}, and it completes with one call to @code{AT_CLEANUP}.
|
|
|
|
@defmac AT_INIT (@ovar{name})
|
|
@atindex INIT
|
|
@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. In any case,
|
|
the test suite always displays the package name and version. It also
|
|
inherits the package bug report address.
|
|
@end defmac
|
|
|
|
@defmac AT_TESTED (@var{executables})
|
|
@atindex TESTED
|
|
Log the path 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.
|
|
@end defmac
|
|
|
|
Autotest test suites rely on the @code{PATH} to find the tested program.
|
|
This saves from generating the absolute paths to the various tools, and
|
|
makes it possible to test installed programs. Therefore, knowing what
|
|
programs are being exercised is crucial to understand some problems in
|
|
the test suite itself, or its occasional misuses. It is a good idea to
|
|
also subscribe foreign programs you depend upon, to ease incompatibility
|
|
diagnostics.
|
|
|
|
@sp 1
|
|
|
|
@defmac AT_SETUP (@var{test-group-name})
|
|
@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.
|
|
@end defmac
|
|
|
|
@defmac AT_KEYWORDS (@var{keywords})
|
|
@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
|
|
@samp{./testsuite -k foo} to run exclusively these test groups. The
|
|
@var{title} of the test group is automatically recorded to
|
|
@code{AT_KEYWORDS}.
|
|
|
|
Several invocations within a test group accumulate new keywords. In
|
|
other words, don't fear registering several times the same keyword in a
|
|
test group.
|
|
@end defmac
|
|
|
|
@defmac AT_XFAIL_IF (@var{shell-condition})
|
|
@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).
|
|
@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 will be enough to turn
|
|
the test into an expected failure.
|
|
@end defmac
|
|
|
|
@defmac AT_CLEANUP
|
|
@atindex CLEANUP
|
|
End the current test group.
|
|
@end defmac
|
|
|
|
@sp 1
|
|
|
|
@defmac AT_DATA (@var{file}, @var{contents})
|
|
@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. The contents ought to end with an end of line.
|
|
@end defmac
|
|
|
|
@defmac AT_CHECK (@var{commands}, @dvar{status, @samp{0}}, @dvar{stdout, @samp{}}, @dvar{stderr, @samp{}}, @ovar{run-if-fail}, @ovar{run-if-pass})
|
|
@atindex CHECK
|
|
Execute a test by performing given shell @var{commands}. These commands
|
|
should normally exit with @var{status}, while producing expected
|
|
@var{stdout} and @var{stderr} contents. If @var{commands} exit with
|
|
status 77, then the whole test group is skipped. Otherwise, if this test
|
|
fails, run shell commands @var{run-if-fail} or, if this test passes, run shell
|
|
commands @var{run-if-pass}.
|
|
|
|
The @var{commands} @emph{must not} redirect the standard output, nor the
|
|
standard error.
|
|
|
|
If @var{status}, or @var{stdout}, or @var{stderr} is @samp{ignore}, then
|
|
the corresponding value is not checked.
|
|
|
|
The special value @samp{expout} for @var{stdout} means the expected
|
|
output of the @var{commands} is the content of the file @file{expout}.
|
|
If @var{stdout} is @samp{stdout}, then the standard output of the
|
|
@var{commands} is available for further tests in the file @file{stdout}.
|
|
Similarly for @var{stderr} with @samp{expout} and @samp{stderr}.
|
|
@end defmac
|
|
|
|
|
|
@node testsuite Invocation
|
|
@section Running @command{testsuite} Scripts
|
|
@cindex @command{testsuite}
|
|
|
|
Autotest test suites support the following arguments:
|
|
|
|
@table @option
|
|
@item --help
|
|
@itemx -h
|
|
Display the list of options and exit successfully.
|
|
|
|
@item --version
|
|
@itemx -V
|
|
Display the version of the test suite and exit successfully.
|
|
|
|
@item --clean
|
|
@itemx -c
|
|
Remove all the files the test suite might have created and exit. Meant
|
|
for @code{clean} Makefile targets.
|
|
|
|
@item --list
|
|
@itemx -l
|
|
List all the tests (or only the selection), including their possible
|
|
keywords.
|
|
@end table
|
|
|
|
@sp 1
|
|
|
|
By default all the tests are performed (or described with
|
|
@option{--list}) in the default environment first silently, then
|
|
verbosely, but the environment, set of tests, and verbosity level can be
|
|
tuned:
|
|
|
|
@table @samp
|
|
@item @var{variable}=@var{value}
|
|
Set the environment @var{variable} to @var{value}. Do not run
|
|
@samp{FOO=foo ./testsuite} as debugging scripts would then run in a
|
|
different environment.
|
|
|
|
@cindex @code{AUTOTEST_PATH}
|
|
The variable @code{AUTOTEST_PATH} specifies the testing path to prepend
|
|
to @code{PATH}. It handles specially relative paths (not starting with
|
|
@samp{/}): they are considered to be relative to the top level of the
|
|
package being built. All the directories are made absolute, first
|
|
starting from the top level @emph{build} tree, then from the
|
|
@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
|
|
@code{PATH}.
|
|
|
|
@item @var{number}
|
|
@itemx @var{number}-@var{number}
|
|
@itemx @var{number}-
|
|
@itemx -@var{number}
|
|
Add the corresponding test groups, with obvious semantics, to the
|
|
selection.
|
|
|
|
@item --keywords=@var{keywords}
|
|
@itemx -k @var{keywords}
|
|
Add to the selection the test groups which title or keywords (arguments
|
|
to @code{AT_SETUP} or @code{AT_KEYWORDS}) match @emph{all} the keywords
|
|
of the comma separated list @var{keywords}.
|
|
|
|
Running @samp{./testsuite -k autoupdate,FUNC} will select all the tests
|
|
tagged with @samp{autoupdate} @emph{and} @samp{FUNC} (as in
|
|
@samp{AC_CHECK_FUNC}, @samp{AC_FUNC_FNMATCH} etc.) while
|
|
@samp{./testsuite -k autoupdate -k FUNC} runs all the tests tagged with
|
|
@samp{autoupdate} @emph{or} @samp{FUNC}.
|
|
|
|
@item --errexit
|
|
@itemx -e
|
|
If any test fails, immediately abort testing. It implies
|
|
@option{--debug}: post test group clean up, debugging script generation,
|
|
and logging are inhibited. This option is meant for the full test
|
|
suite, it is not really useful for generated debugging scripts.
|
|
|
|
@item --verbose
|
|
@itemx -v
|
|
Force more verbosity in the detailed output of what is being done. This
|
|
is the default for debugging scripts.
|
|
|
|
@item --debug
|
|
@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. Do not create debugging scripts. Do not
|
|
log (in order to preserve supposedly existing full log file). This is
|
|
the default for debugging scripts, but it can also be useful to debug
|
|
the testsuite itself.
|
|
|
|
@item --trace
|
|
@itemx -x
|
|
Trigger shell tracing of the test groups.
|
|
@end table
|
|
|
|
|
|
@node Making testsuite Scripts
|
|
@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 @file{Makefile}. Here is a
|
|
check list of things to do.
|
|
|
|
@itemize @minus
|
|
|
|
@item
|
|
@cindex @file{package.m4}
|
|
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},
|
|
@code{AT_PACKAGE_TARNAME}, and @code{AT_PACKAGE_VERSION}.
|
|
@xref{Initializing configure}, for a description of these variables. We
|
|
suggest the following Makefile excerpt:
|
|
|
|
@smallexample
|
|
$(srcdir)/package.m4: $(top_srcdir)/configure.ac
|
|
@{ \
|
|
echo '# Signature of the current package.'; \
|
|
echo 'm4_define([AT_PACKAGE_NAME], [@@PACKAGE_NAME@@])'; \
|
|
echo 'm4_define([AT_PACKAGE_TARNAME], [@@PACKAGE_TARNAME@@])'; \
|
|
echo 'm4_define([AT_PACKAGE_VERSION], [@@PACKAGE_VERSION@@])'; \
|
|
echo 'm4_define([AT_PACKAGE_STRING], [@@PACKAGE_STRING@@])'; \
|
|
echo 'm4_define([AT_PACKAGE_BUGREPORT], [@@PACKAGE_BUGREPORT@@])'; \
|
|
@} >$(srcdir)/package.m4
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Be sure to distribute @file{package.m4} and to put it into the source
|
|
hierarchy: the test suite ought to be shipped!
|
|
|
|
@item
|
|
Invoke @code{AC_CONFIG_TESTDIR}.
|
|
|
|
@defmac AC_CONFIG_TESTDIR (@var{directory}, @dvar{test-path, @var{directory}})
|
|
@acindex{CONFIG_TESTDIR}
|
|
An Autotest test suite is to be configured in @var{directory}. This
|
|
macro requires the instantiation of @file{@var{directory}/atconfig} from
|
|
@file{@var{directory}/atconfig.in}, and sets the default
|
|
@code{AUTOTEST_PATH} to @var{test-path} (@pxref{testsuite Invocation}).
|
|
@end defmac
|
|
|
|
@item
|
|
Still within @file{configure.ac}, as appropriate, ensure that some
|
|
@code{AC_CONFIG_FILES} command includes substitution for
|
|
@file{tests/atlocal}.
|
|
|
|
@item
|
|
The @file{tests/Makefile.in} should be modified so the validation in
|
|
your package is triggered by @samp{make check}. An example is provided
|
|
below.
|
|
@end itemize
|
|
|
|
With Automake, here is a minimal example about how to link @samp{make
|
|
check} with a validation suite.
|
|
|
|
@example
|
|
EXTRA_DIST = testsuite.at testsuite
|
|
TESTSUITE = $(srcdir)/testsuite
|
|
check-local: atconfig atlocal $(TESTSUITE)
|
|
$(SHELL) $(TESTSUITE)
|
|
|
|
AUTOTEST = $(AUTOM4TE) --language=autotest
|
|
$(TESTSUITE): $(srcdir)/testsuite.at
|
|
$(AUTOTEST) -I $(srcdir) $@@.at -o $@@.tmp
|
|
mv $@@.tmp $@@
|
|
@end example
|
|
|
|
You might want to list explicitly the dependencies, i.e., the list of
|
|
the files @file{testsuite.at} includes.
|
|
|
|
With strict Autoconf, you might need to add lines inspired from the
|
|
following:
|
|
|
|
@example
|
|
subdir = tests
|
|
|
|
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)/$@@
|
|
@end example
|
|
|
|
@noindent
|
|
and manage to have @file{atconfig.in} and @code{$(EXTRA_DIST)}
|
|
distributed.
|
|
|
|
|
|
|
|
@c =============================== Frequent Autoconf Questions, with answers
|
|
|
|
@node FAQ
|
|
@chapter Frequent Autoconf Questions, with answers
|
|
|
|
Several questions about Autoconf come up occasionally. Here some of them
|
|
are addressed.
|
|
|
|
@menu
|
|
* Distributing:: Distributing @command{configure} scripts
|
|
* Why GNU m4:: Why not use the standard M4?
|
|
* Bootstrapping:: Autoconf and @acronym{GNU} M4 require each other?
|
|
* Why Not Imake:: Why @acronym{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
|
|
@end menu
|
|
|
|
@node Distributing
|
|
@section Distributing @command{configure} Scripts
|
|
|
|
@display
|
|
What are the restrictions on distributing @command{configure}
|
|
scripts that Autoconf generates? How does that affect my
|
|
programs that use them?
|
|
@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 @acronym{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},
|
|
@file{config.h.in} is under whatever copyright you use for your
|
|
@file{configure.ac}. @file{config.sub} and @file{config.guess} have an
|
|
exception to the GPL when they are used with an Autoconf-generated
|
|
@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.
|
|
|
|
@node Why GNU m4
|
|
@section Why Require @acronym{GNU} M4?
|
|
|
|
@display
|
|
Why does Autoconf require @acronym{GNU} M4?
|
|
@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:
|
|
|
|
@example
|
|
m4_builtin
|
|
m4_indir
|
|
m4_bpatsubst
|
|
__file__
|
|
__line__
|
|
@end example
|
|
|
|
Autoconf requires version 1.4 or above of @acronym{GNU} M4 because it uses
|
|
frozen state files.
|
|
|
|
Since only software maintainers need to use Autoconf, and since @acronym{GNU}
|
|
M4 is simple to configure and install, it seems reasonable to require
|
|
@acronym{GNU} M4 to be installed also. Many maintainers of @acronym{GNU} and
|
|
other free software already have most of the @acronym{GNU} utilities
|
|
installed, since they prefer them.
|
|
|
|
@node Bootstrapping
|
|
@section How Can I Bootstrap?
|
|
|
|
@display
|
|
If Autoconf requires @acronym{GNU} M4 and @acronym{GNU} M4 has an Autoconf
|
|
@command{configure} script, how do I bootstrap? It seems like a chicken
|
|
and egg problem!
|
|
@end display
|
|
|
|
This is a misunderstanding. Although @acronym{GNU} M4 does come with a
|
|
@command{configure} script produced by Autoconf, Autoconf is not required
|
|
in order to run the script and install @acronym{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).
|
|
|
|
@node Why Not Imake
|
|
@section Why Not Imake?
|
|
|
|
@display
|
|
Why not use Imake instead of @command{configure} scripts?
|
|
@end display
|
|
|
|
Several people have written addressing this question, so I include
|
|
adaptations of their explanations here.
|
|
|
|
The following answer is based on one written by Richard Pixley:
|
|
|
|
@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.
|
|
|
|
@acronym{GNU} tools are not released this way. Each @acronym{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 @acronym{GNU} suite as a collection of native tools, then the
|
|
problems are similar. But the @acronym{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 @acronym{GNU} coding
|
|
standards address the same issues without necessarily imposing the same
|
|
restrictions.
|
|
@end quotation
|
|
|
|
|
|
Here is some further explanation, written by Per Bothner:
|
|
|
|
@quotation
|
|
One of the advantages of Imake is that it easy to generate large
|
|
Makefiles using @code{cpp}'s @samp{#include} and macro mechanisms.
|
|
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
|
|
@code{cpp}. The shell is fully programmable, has macro substitution,
|
|
can execute (or source) other shell scripts, and can inspect its
|
|
environment.
|
|
@end quotation
|
|
|
|
|
|
Paul Eggert elaborates more:
|
|
|
|
@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
|
|
@command{make} and the installer's C preprocessor. The fundamental problem
|
|
here is that the C preprocessor was designed to preprocess C programs,
|
|
not @file{Makefile}s. 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.
|
|
@end quotation
|
|
|
|
|
|
Finally, Mark Eichin notes:
|
|
|
|
@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}:
|
|
@file{Imakefile}s tend to be much shorter (likewise, less redundant)
|
|
than @file{Makefile.in}s. There is a fix to this, however---at least
|
|
for the Kerberos V5 tree, we've modified things to call in common
|
|
@file{post.in} and @file{pre.in} @file{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.
|
|
@end quotation
|
|
|
|
|
|
@node Defining Directories
|
|
@section How Do I @code{#define} Installation Directories?
|
|
|
|
@display
|
|
My program needs library files, installed in @code{datadir} and
|
|
similar. If I use
|
|
|
|
@example
|
|
AC_DEFINE_UNQUOTED([DATADIR], [$datadir],
|
|
[Define to the read-only architecture-independent
|
|
data directory.])
|
|
@end example
|
|
|
|
@noindent
|
|
I get
|
|
|
|
@example
|
|
#define DATADIR "$@{prefix@}/share"
|
|
@end example
|
|
@end display
|
|
|
|
As already explained, this behavior is on purpose, mandated by the
|
|
@acronym{GNU} Coding Standards, see @ref{Installation Directory
|
|
Variables}. There are several means to achieve a similar goal:
|
|
|
|
@itemize @minus
|
|
@item
|
|
Do not use @code{AC_DEFINE} but use your @file{Makefile} to pass the
|
|
actual value of @code{datadir} via compilation flags, see
|
|
@ref{Installation Directory Variables}, for the details.
|
|
|
|
@item
|
|
This solution can be simplified when compiling a program: you may either
|
|
extend the @code{CPPFLAGS}:
|
|
|
|
@example
|
|
CPPFLAGS = -DDATADIR=\"$(datadir)\" @@CPPFLAGS@@
|
|
@end example
|
|
|
|
@noindent
|
|
or create a dedicated header file:
|
|
|
|
@example
|
|
DISTCLEANFILES = datadir.h
|
|
datadir.h: Makefile
|
|
echo '#define DATADIR "$(datadir)"' >$@@
|
|
@end example
|
|
|
|
@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 instance, the macro @code{AC_DEFINE_DIR} from
|
|
the @href{http://www.gnu.org/software/ac-archive/, Autoconf Macro
|
|
Archive}.
|
|
|
|
This solution does not conform to the @acronym{GNU} Coding Standards.
|
|
|
|
@item
|
|
Note that all the previous solutions hard wire the absolute path to
|
|
these directories in the executables, which is not a good property. You
|
|
may try to compute the paths relatively to @code{prefix}, and try to
|
|
find @code{prefix} at runtime, this way your package is relocatable.
|
|
Some macros are already available to address this issue: see
|
|
@code{adl_COMPUTE_RELATIVE_PATHS} and
|
|
@code{adl_COMPUTE_STANDARD_RELATIVE_PATHS} on the
|
|
@href{http://www.gnu.org/software/ac-archive/, Autoconf Macro Archive}.
|
|
@end itemize
|
|
|
|
|
|
@node autom4te.cache
|
|
@section What is @file{autom4te.cache}?
|
|
|
|
@display
|
|
What is this directory @file{autom4te.cache}? Can I safely remove it?
|
|
@end display
|
|
|
|
In the @acronym{GNU} Build System, @file{configure.ac} plays a central
|
|
role and is read by many tools: @command{autoconf} to create
|
|
@file{configure}, @command{autoheader} to create @file{config.h.in},
|
|
@command{automake} to create @file{Makefile.in}, @command{autoscan} to
|
|
check the completeness of @file{configure.ac}, @command{autoreconf} to
|
|
check the @acronym{GNU} Build System components that are used. To
|
|
``read @file{configure.ac}'' actually means to compile it with M4,
|
|
which can be a very long process for complex @file{configure.ac}.
|
|
|
|
This is why all these tools, instead of running directly M4, invoke
|
|
@command{autom4te} (@pxref{autom4te Invocation}) which, while answering to
|
|
a specific demand, stores additional information in
|
|
@file{autom4te.cache} for future runs. For instance, if you run
|
|
@command{autoconf}, behind the scenes, @command{autom4te} will also
|
|
store information for the other tools, so that when you invoke
|
|
@command{autoheader} or @command{automake} etc., re-processing
|
|
@file{configure.ac} is not needed. The speed up is frequently of 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.
|
|
|
|
@sp 1
|
|
|
|
@display
|
|
Can I permanently get rid of it?
|
|
@end display
|
|
|
|
The creation of this cache can be disabled from
|
|
@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 @acronym{GNU} Build System
|
|
components are used, the more the cache is useful; for instance
|
|
running @samp{autoreconf -f} on the Coreutils is twice slower without
|
|
the cache @emph{although @option{--force} implies that the cache is
|
|
not fully exploited}, and eight times slower than without
|
|
@option{--force}.
|
|
|
|
|
|
@node Present But Cannot Be Compiled
|
|
@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
|
|
@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.
|
|
|
|
As of Autoconf 2.56 both checks are performed, and @code{configure}
|
|
complains loudly if the compiler and the preprocessor do not agree.
|
|
For the time being the result used is that of the preprocessor, to give
|
|
maintainers time to adjust their @file{configure.ac}, but in the near
|
|
future, only the compiler will be considered.
|
|
|
|
Consider the following example:
|
|
|
|
@example
|
|
$ @kbd{cat number.h}
|
|
typedef int number;
|
|
$ @kbd{cat pi.h}
|
|
const number pi = 3;
|
|
$ @kbd{cat configure.ac}
|
|
AC_INIT
|
|
AC_CHECK_HEADERS(pi.h)
|
|
$ @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 how to run the C preprocessor... gcc -E
|
|
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: proceeding with the preprocessor's result
|
|
configure: WARNING: ## ------------------------------------ ##
|
|
configure: WARNING: ## Report this to bug-autoconf@@gnu.org. ##
|
|
configure: WARNING: ## ------------------------------------ ##
|
|
checking for pi.h... yes
|
|
@end example
|
|
|
|
@noindent
|
|
The proper way the handle this case is using the fourth argument
|
|
(@pxref{Generic Headers}):
|
|
|
|
@example
|
|
$ @kbd{cat configure.ac}
|
|
AC_INIT
|
|
AC_CHECK_HEADERS(number.h pi.h,,,
|
|
[[#if 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
|
|
@end example
|
|
|
|
See @ref{Particular Headers}, for a list of headers with their
|
|
prerequisite.
|
|
|
|
@c ===================================================== History of Autoconf.
|
|
|
|
@node History
|
|
@chapter History of Autoconf
|
|
|
|
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@enddots{}
|
|
|
|
@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
|
|
@end menu
|
|
|
|
@node Genesis
|
|
@section Genesis
|
|
|
|
In June 1991 I was maintaining many of the @acronym{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 @file{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 @acronym{GNU} utilities packages. Brian Berliner
|
|
also adapted one of my scripts for his @acronym{CVS} revision control system.
|
|
|
|
Later that summer, I learned that Richard Stallman and Richard Pixley
|
|
were developing similar scripts to use in the @acronym{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
|
|
@file{config.status} files.
|
|
|
|
@node Exodus
|
|
@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 @acronym{GNU} utilities packages to use
|
|
@command{configure} scripts, updating them all by hand became impractical.
|
|
Rich Murphey, the maintainer of the @acronym{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
|
|
@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
|
|
@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 very 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 @acronym{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.
|
|
|
|
@node Leviticus
|
|
@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 @sc{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@,cois 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
|
|
@file{Makefile}, so he could use Autoconf for his @acronym{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.
|
|
|
|
@node Numbers
|
|
@section Numbers
|
|
|
|
In July 1992, after months of alpha testing, I released Autoconf 1.0,
|
|
and converted many @acronym{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 @acronym{GNU} Project (such as TCL, FSP, and Kerberos V5).
|
|
Autoconf continued to improve rapidly, as many people using the
|
|
@command{configure} scripts reported problems they encountered.
|
|
|
|
Autoconf turned out to be a good torture test for M4 implementations.
|
|
@sc{unix} M4 started to dump core because of the length of the
|
|
macros that Autoconf defined, and several bugs showed up in @acronym{GNU}
|
|
M4 as well. Eventually, we realized that we needed to use some
|
|
features that only @acronym{GNU} M4 has. 4.3@acronym{BSD} 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@,cois Pinard made it diagnose
|
|
invalid arguments. Jim Blandy bravely coerced it into configuring
|
|
@acronym{GNU} Emacs, laying the groundwork for several later improvements.
|
|
Roland McGrath got it to configure the @acronym{GNU} C Library, wrote the
|
|
@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
|
|
@code{AC_MACRODIR} environment variable. (He also coined the term
|
|
@dfn{autoconfiscate} to mean ``adapt a software package to use
|
|
Autoconf''.) Roland and Noah improved the quoting protection in
|
|
@code{AC_DEFINE} and fixed many bugs, especially when I got sick of
|
|
dealing with portability problems from February through June, 1993.
|
|
|
|
@node Deuteronomy
|
|
@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
|
|
@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
|
|
@file{config.sub}, @file{config.guess}, @option{--host}, and
|
|
@option{--target}; making links to files; and running @command{configure}
|
|
scripts in subdirectories. Adding these features enabled Ken to convert
|
|
@acronym{GNU} @code{as}, and Rob Savoye to convert Deja@acronym{GNU}, 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
|
|
@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@,cois Pinard, I made
|
|
the macros not interrupt each others' messages. (That feature revealed
|
|
some performance bottlenecks in @acronym{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@,cois 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.)
|
|
|
|
|
|
@c ========================================================== Appendices
|
|
|
|
@node Copying This Manual
|
|
@appendix Copying This Manual
|
|
|
|
@menu
|
|
* GNU Free Documentation License:: License for copying this manual
|
|
@end menu
|
|
|
|
@include fdl.texi
|
|
|
|
@node Indices
|
|
@appendix Indices
|
|
|
|
@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
|
|
* 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
|
|
@end menu
|
|
|
|
@node Environment Variable Index
|
|
@appendixsec Environment Variable Index
|
|
|
|
This is an alphabetical list of the environment variables that Autoconf
|
|
checks.
|
|
|
|
@printindex ev
|
|
|
|
@node Output Variable Index
|
|
@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
|
|
@file{Makefile}s. @xref{Setting Output Variables}, for more information
|
|
on how this is done.
|
|
|
|
@printindex ov
|
|
|
|
@node Preprocessor Symbol Index
|
|
@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} directives.
|
|
|
|
@printindex cv
|
|
|
|
@node Autoconf Macro Index
|
|
@appendixsec Autoconf Macro Index
|
|
|
|
This is an alphabetical list of the Autoconf macros.
|
|
@ifset shortindexflag
|
|
To make the list easier to use, the macros are listed without their
|
|
preceding @samp{AC_}.
|
|
@end ifset
|
|
|
|
@printindex AC
|
|
|
|
@node M4 Macro Index
|
|
@appendixsec M4 Macro Index
|
|
|
|
This is an alphabetical list of the M4, M4sugar, and M4sh macros.
|
|
@ifset shortindexflag
|
|
To make the list easier to use, the macros are listed without their
|
|
preceding @samp{m4_} or @samp{AS_}.
|
|
@end ifset
|
|
|
|
@printindex MS
|
|
|
|
@node Autotest Macro Index
|
|
@appendixsec Autotest Macro Index
|
|
|
|
This is an alphabetical list of the Autotest macros.
|
|
@ifset shortindexflag
|
|
To make the list easier to use, the macros are listed without their
|
|
preceding @samp{AT_}.
|
|
@end ifset
|
|
|
|
@printindex AT
|
|
|
|
@node Program & Function Index
|
|
@appendixsec Program and Function Index
|
|
|
|
This is an alphabetical list of the programs and functions which
|
|
portability is discussed in this document.
|
|
|
|
@printindex pr
|
|
|
|
@node Concept Index
|
|
@appendixsec Concept Index
|
|
|
|
This is an alphabetical list of the files, tools, and concepts
|
|
introduced in this document.
|
|
|
|
@printindex cp
|
|
|
|
@bye
|
|
|
|
@c Local Variables:
|
|
@c fill-column: 72
|
|
@c ispell-local-dictionary: "american"
|
|
@c End:
|