mirror of
git://git.sv.gnu.org/autoconf
synced 2024-12-27 02:39:00 +08:00
1328e61cb7
* doc/autoconf.texi (Compilers and Preprocessors): Likewise.
* acgeneral.m4 (AC_TRY_CPP): Comment changes.
9498 lines
338 KiB
Plaintext
9498 lines
338 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
|
@c %**start of header
|
|
@setfilename autoconf.info
|
|
@settitle Autoconf
|
|
|
|
@finalout
|
|
@setchapternewpage odd
|
|
@setcontentsaftertitlepage
|
|
|
|
@include version.texi
|
|
|
|
@c A simple macro for optional variables.
|
|
@macro ovar{varname}
|
|
@r{[}@var{\varname\}@r{]}
|
|
@end macro
|
|
|
|
@c I don't like the way URL are displayed in TeX with @uref.
|
|
@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
|
|
|
|
|
|
@dircategory GNU admin
|
|
@direntry
|
|
* Autoconf: (autoconf). Create source code configuration scripts
|
|
@end direntry
|
|
|
|
@dircategory Individual utilities
|
|
@direntry
|
|
* autoscan: (autoconf)autoscan Invocation.
|
|
Semi-automatic @file{configure.in} writing
|
|
* ifnames: (autoconf)ifnames Invocation.
|
|
Listing the conditionals in source code
|
|
* autoconf: (autoconf)autoconf Invocation.
|
|
How to create configuration scripts
|
|
* autoreconf: (autoconf)autoreconf Invocation.
|
|
Remaking multiple @code{configure} scripts
|
|
* configure: (autoconf)configure Invocation.
|
|
Configuring a package
|
|
* config.status: (autoconf)config.status Invocation.
|
|
Recreating a configuration
|
|
@end direntry
|
|
|
|
@ifinfo
|
|
Autoconf: Creating Automatic Configuration Scripts, by David MacKenzie.
|
|
|
|
This file documents the GNU Autoconf package for creating scripts to
|
|
configure source code packages using templates and an @code{m4} macro
|
|
package.
|
|
|
|
Copyright (C) 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000 Free Software
|
|
Foundation, Inc.
|
|
|
|
Permission is granted to make and distribute verbatim copies of this
|
|
manual provided the copyright notice and this permission notice are
|
|
preserved on all copies.
|
|
|
|
@ignore
|
|
Permission is granted to process this file through TeX and print the
|
|
results, provided the printed document carries copying permission notice
|
|
identical to this one except for the removal of this paragraph (this
|
|
paragraph not being relevant to the printed manual).
|
|
|
|
@end ignore
|
|
Permission is granted to copy and distribute modified versions of this
|
|
manual under the conditions for verbatim copying, provided that the
|
|
entire resulting derived work is distributed under the terms of a
|
|
permission notice identical to this one.
|
|
|
|
Permission is granted to copy and distribute translations of this manual
|
|
into another language, under the above conditions for modified versions,
|
|
except that this permission notice may be stated in a translation
|
|
approved by the Foundation.
|
|
@end ifinfo
|
|
|
|
@titlepage
|
|
@title Autoconf
|
|
@subtitle Creating Automatic Configuration Scripts
|
|
@subtitle Edition @value{EDITION}, for Autoconf version @value{VERSION}
|
|
@subtitle @value{UPDATED}
|
|
@author David MacKenzie and Ben Elliston
|
|
@c I think I've rewritten all of Noah and Roland's contributions by now.
|
|
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
Copyright @copyright{} 1992, 93, 94, 95, 96, 98, 99, 2000 Free Software
|
|
Foundation, Inc.
|
|
|
|
Permission is granted to make and distribute verbatim copies of this
|
|
manual provided the copyright notice and this permission notice are
|
|
preserved on all copies.
|
|
|
|
Permission is granted to copy and distribute modified versions of this
|
|
manual under the conditions for verbatim copying, provided that the
|
|
entire resulting derived work is distributed under the terms of a
|
|
permission notice identical to this one.
|
|
|
|
Permission is granted to copy and distribute translations of this manual
|
|
into another language, under the above conditions for modified versions,
|
|
except that this permission notice may be stated in a translation
|
|
approved by the Foundation.
|
|
@end titlepage
|
|
|
|
@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 a macro index that @@defmac doesn't write to.
|
|
@defcodeindex ma
|
|
|
|
@node Top, Introduction, (dir), (dir)
|
|
@comment node-name, next, previous, up
|
|
|
|
@ifinfo
|
|
This file documents the GNU Autoconf package for creating scripts to
|
|
configure source code packages using templates and the GNU M4 macro
|
|
package. This is edition @value{EDITION}, for Autoconf version
|
|
@value{VERSION}.
|
|
|
|
@end ifinfo
|
|
|
|
@c The master menu, created with texinfo-master-menu, goes here.
|
|
|
|
@menu
|
|
* Introduction:: Autoconf's purpose, strengths, and weaknesses
|
|
* The GNU build system::
|
|
* 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
|
|
* Writing Macros:: Adding new macros to Autoconf
|
|
* Manual Configuration:: Selecting features that can't be guessed
|
|
* Site Configuration:: Local defaults for @code{configure}
|
|
* Running configure scripts:: How to use the Autoconf output
|
|
* config.status Invocation:: Recreating a configuration
|
|
* Obsolete Constructs:: Kept for backward compatibility
|
|
* Questions:: Questions about Autoconf, with answers
|
|
* History:: History of Autoconf
|
|
* 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
|
|
* Macro Index:: Index of Autoconf macros
|
|
* Concept Index:: General index
|
|
|
|
@detailmenu --- The Detailed Node Listing ---
|
|
|
|
Making @code{configure} Scripts
|
|
|
|
* Writing configure.in:: What to put in an Autoconf input file
|
|
* autoscan Invocation:: Semi-automatic @file{configure.in} writing
|
|
* ifnames Invocation:: Listing the conditionals in source code
|
|
* autoconf Invocation:: How to create configuration scripts
|
|
* autoreconf Invocation:: Remaking multiple @code{configure} scripts
|
|
|
|
Writing @file{configure.in}
|
|
|
|
* Shell Script Compiler:: Autoconf as solution of a problem
|
|
* Autoconf Language:: Programming in Autoconf
|
|
* configure.in Layout:: Standard organization of configure.in
|
|
|
|
Initialization and Output Files
|
|
|
|
* Notices:: Copyright, version numbers in @code{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 from 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
|
|
* 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
|
|
* C Compiler Characteristics::
|
|
* Fortran 77 Compiler Characteristics::
|
|
* 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
|
|
|
|
* Particular Functions:: Special handling to find certain functions
|
|
* Generic Functions:: How to find other functions
|
|
|
|
Header Files
|
|
|
|
* 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
|
|
|
|
Writing Tests
|
|
|
|
* Examining Declarations:: Detecting header files and declarations
|
|
* Examining Syntax:: Detecting language syntax features
|
|
* Examining Libraries:: Detecting functions and global variables
|
|
* Run Time:: Testing for run-time features
|
|
* Portable Shell:: Shell script portability pitfalls
|
|
* Multiple Cases:: Tests for several possible values
|
|
* Language Choice:: Selecting which language to use for testing
|
|
|
|
Checking Run Time Behavior
|
|
|
|
* Test Programs:: Running test programs
|
|
* Guidelines:: General rules for writing test programs
|
|
* Test Functions:: Avoiding pitfalls in test programs
|
|
|
|
Portable Shell Programming
|
|
|
|
* Shellology:: A zoology of shells
|
|
* Special Shell Variables:: Variables you should not change
|
|
* Shell Substitutions:: Test and assign
|
|
* Limitations of Builtins:: Portable use of not so portable /bin/sh
|
|
* Limitations of Usual Tools:: Portable use of portable tools
|
|
|
|
Results of Tests
|
|
|
|
* Defining Symbols:: Defining C preprocessor symbols
|
|
* Setting Output Variables:: Replacing variables in output files
|
|
* Caching Results:: Speeding up subsequent @code{configure} runs
|
|
* Printing Messages:: Notifying @code{configure} users
|
|
|
|
Caching Results
|
|
|
|
* Cache Variable Names:: Shell variables used in caches
|
|
* Cache Files:: Files @code{configure} uses for caching
|
|
|
|
Writing Macros
|
|
|
|
* Macro Definitions:: Basic format of an Autoconf macro
|
|
* Macro Names:: What to call your new macros
|
|
* Quoting:: Protecting macros from unwanted expansion
|
|
* Reporting Messages:: Notifying @code{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
|
|
|
|
Quoting
|
|
|
|
* Active Characters:: Characters that change the behavior of m4
|
|
* One Macro Call:: Quotation and one macro call
|
|
* Quotation and Nested Macros:: Macros calling macros
|
|
* Quotation Rule Of Thumb:: One parenthesis, one quote
|
|
|
|
Dependencies Between Macros
|
|
|
|
* Prerequisite Macros:: Ensuring required information
|
|
* Suggested Ordering:: Warning about possible ordering problems
|
|
|
|
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:: Formating help string
|
|
* Site Details:: Configuring site details
|
|
* Transforming Names:: Changing program names when installing
|
|
* Site Defaults:: Giving @code{configure} local defaults
|
|
|
|
Transforming Program Names When Installing
|
|
|
|
* Transformation Options:: @code{configure} options to transform names
|
|
* Transformation Examples:: Sample uses of transforming names
|
|
* Transformation Rules:: @file{Makefile} uses of transforming names
|
|
|
|
Running @code{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 @code{configure}
|
|
* Environment Variables:: Defining environment variables.
|
|
* configure Invocation:: Changing how @code{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.in}
|
|
* Obsolete Macros:: Backward compatibility macros
|
|
* Autoconf 1:: Tips for upgrading your files
|
|
|
|
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
|
|
|
|
Questions About Autoconf
|
|
|
|
* Distributing:: Distributing @code{configure} scripts
|
|
* Why GNU m4:: Why not use the standard M4?
|
|
* Bootstrapping:: Autoconf and GNU M4 require each other?
|
|
* Why Not Imake:: Why GNU uses @code{configure} instead of Imake
|
|
|
|
History of Autoconf
|
|
|
|
* Genesis:: Prehistory and naming of @code{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 detailmenu
|
|
@end menu
|
|
|
|
@c ============================================================= Introduction.
|
|
|
|
@node Introduction, The GNU build system, Top, Top
|
|
@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 electro-magnetic
|
|
waves, the relativist 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.
|
|
|
|
@c FIXME: Tom, your cue is here.
|
|
There are several jobs related to making portable software packages that
|
|
Autoconf currently does not do. Among these are automatically creating
|
|
@file{Makefile} files with all of the standard targets, and supplying
|
|
replacements for standard library functions and header files on systems
|
|
that lack them. Work is in progress to add those features in the
|
|
future.
|
|
|
|
Autoconf imposes some restrictions on the names of macros used with
|
|
@code{#if} in C programs (@pxref{Preprocessor Symbol Index}).
|
|
|
|
Autoconf requires @sc{gnu} M4 in order to generate the scripts. It uses
|
|
features that some @sc{unix} versions of M4, including @sc{gnu} M4 1.3,
|
|
do not have. You must use version 1.4 or later of @sc{gnu} M4.
|
|
|
|
@xref{Autoconf 1}, for information about upgrading from version 1.
|
|
@xref{History}, for the story of Autoconf's development.
|
|
@xref{Questions}, 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://sources.redhat.com/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.in} that demonstrates the problem.
|
|
|
|
Autoconf's development tree is accessible via @sc{cvs}, see the Autoconf
|
|
web page for details. There is also a
|
|
@href{http://subversions.gnu.org/cgi-bin/cvsweb/autoconf/, @sc{cvs}web
|
|
interface to the Autoconf development tree}.
|
|
|
|
Patches relative to the current @sc{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 highly used
|
|
macros that have already demonstrated their usefulness. Nevertheless,
|
|
if you wish to share your macros, or find existing ones, see the
|
|
@href{http://research.cys.de/autoconf-archive/, Autoconf Macro
|
|
Repository}, which is kindly run by @email{simons@@research.cys.de,
|
|
Peter Simons}.
|
|
|
|
|
|
@c ================================================= The GNU build system
|
|
|
|
@node The GNU build system, Making configure Scripts, Introduction, Top
|
|
@chapter The GNU build system
|
|
|
|
@emph{This chapter is still under work. It will be ready for the
|
|
release, but most probably not for the next betas.}
|
|
|
|
I'm unsure about the title.
|
|
|
|
Move the dissertation `A shell script compiler' here. The text above,
|
|
probably starting at `There are several jobs...', should be moved here.
|
|
Hm?
|
|
|
|
Talk about Automake, Libtool.
|
|
|
|
Explain the concept of system.h.
|
|
|
|
Promote Bison, Flex and other GNU tools.
|
|
|
|
Provide pointers to the various documentations and tutorials (books, web
|
|
etc.).
|
|
|
|
Explain that learning is painful, agreed, but getting inspiration is the
|
|
way out. Fetish, libit, liberty.
|
|
|
|
|
|
@c ================================================= Making configure Scripts.
|
|
|
|
@node Making configure Scripts, Setup, The GNU build system, Top
|
|
@chapter Making @code{configure} Scripts
|
|
@cindex @file{aclocal.m4}
|
|
@cindex @code{configure}
|
|
|
|
The configuration scripts that Autoconf produces are by convention
|
|
called @code{configure}. When run, @code{configure} creates several
|
|
files, replacing configuration parameters in them with appropriate
|
|
values. The files that @code{configure} creates are:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
one or more @file{Makefile} files, 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 --cache-file=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 @code{configure} makes a mistake.
|
|
@end itemize
|
|
|
|
To create a @code{configure} script with Autoconf, you need to write an
|
|
Autoconf input file @file{configure.in} and run @code{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 @code{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{[]}).
|
|
@code{autoconf} and @code{autoheader} also read the installed Autoconf
|
|
macro files (by reading @file{autoconf.m4}).
|
|
|
|
@noindent
|
|
Files used in preparing a software package for distribution:
|
|
@example
|
|
@group
|
|
your source files --> [autoscan*] --> [configure.scan] --> configure.in
|
|
|
|
configure.in --. .------> autoconf* -----> configure
|
|
+---+
|
|
[aclocal.m4] --+ `---.
|
|
[acsite.m4] ---' |
|
|
+--> [autoheader*] -> [config.h.in]
|
|
[acconfig.h] ----. |
|
|
+-----'
|
|
[config.h.top] --+
|
|
[config.h.bot] --'
|
|
|
|
Makefile.in -------------------------------> Makefile.in
|
|
@end group
|
|
@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.in:: What to put in an Autoconf input file
|
|
* autoscan Invocation:: Semi-automatic @file{configure.in} writing
|
|
* ifnames Invocation:: Listing the conditionals in source code
|
|
* autoconf Invocation:: How to create configuration scripts
|
|
* autoreconf Invocation:: Remaking multiple @code{configure} scripts
|
|
@end menu
|
|
|
|
@node Writing configure.in, autoscan Invocation, Making configure Scripts, Making configure Scripts
|
|
@section Writing @file{configure.in}
|
|
|
|
To produce a @code{configure} script for a software package, create a
|
|
file called @file{configure.in} 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.in} might need to contain some
|
|
hand-crafted shell commands. The @code{autoscan} program can give you a
|
|
good start in writing @file{configure.in} (@pxref{autoscan Invocation},
|
|
for more information).
|
|
|
|
|
|
|
|
@menu
|
|
* Shell Script Compiler:: Autoconf as solution of a problem
|
|
* Autoconf Language:: Programming in Autoconf
|
|
* configure.in Layout:: Standard organization of configure.in
|
|
@end menu
|
|
|
|
@node Shell Script Compiler, Autoconf Language, Writing configure.in, Writing configure.in
|
|
@subsection A Shell Script Compiler
|
|
|
|
Like for any other language, to properly program in Autoconf, i.e., the
|
|
language in which you write @file{configure.in}, you must understand
|
|
@emph{what} is the problem it tries to answer, and @emph{how} it does.
|
|
|
|
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 sort of different systems, some of them being extremely hostile.
|
|
But Autoconf itself suffers from these differences: @code{configure}
|
|
must run on all those systems, hence @code{configure} must use the
|
|
least common divisor between all supported system.
|
|
|
|
Naturally, you orient yourself towards shell scripts. And in fact,
|
|
there is not even the need for a tool like @code{autoconf}: a set of
|
|
properly written shell functions is way enough to make it easy to write
|
|
@code{configure} scripts by hand. Sigh! Unfortunately, shell functions
|
|
do not belong to the least common divisor, therefore, where you'd define
|
|
a function and use it ten times, you need to write ten times its body.
|
|
|
|
Therefore, what is really needed is some kind of compiler,
|
|
@code{autoconf}, which takes an Autoconf program, @file{configure.in},
|
|
and transform it in a portable shell script, @code{configure}.
|
|
|
|
How does @code{autoconf} perform this task?
|
|
|
|
Two obvious solutions: creating a brand new language, or extending an
|
|
existing one. The former option is very attractive: all sort of
|
|
optimizations could easily be implemented in the compiler, many rigorous
|
|
checks could be performed on the Autoconf program, and in particular, it
|
|
would be extremely easy to reject any non portable construct etc.
|
|
Alternatively, you can extend an existing language, of course, the
|
|
@code{sh} language.
|
|
|
|
Autoconf does the latter: it is an layer on top of @code{sh}. Quite
|
|
naturally then, it has been chosen to implement @code{autoconf} as a
|
|
macro expander, i.e., a program that takes a text in input and
|
|
repeatedly performs @dfn{macro expansions}, repeatedly replaces macro
|
|
uses with macro bodies. Instead of implementing a dedicated Autoconf
|
|
macro expander, it is natural to use an existing general purpose macro
|
|
expander, such as M4, and implement the extensions as a set of M4
|
|
macros.
|
|
|
|
|
|
@node Autoconf Language, configure.in Layout, Shell Script Compiler, Writing configure.in
|
|
@subsection The Autoconf Language
|
|
@cindex quotation
|
|
|
|
The Autoconf language is very different from usual languages because you
|
|
handle actual code just as plain text. Where 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
|
|
are separated by a comma. 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 recursively applies for each macro
|
|
call, including macro 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 perfectly quoted. You may safely simplify 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 understood 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
|
|
|
|
You may have to use text that also resembles a macro call. In this
|
|
case, you must quote this text at top level:
|
|
|
|
@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
|
|
in @code{configure}. Since there is an additional quoting level for each
|
|
macro invocation, this results in @emph{double quoting all the literal
|
|
strings}:
|
|
|
|
@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 continuously been misunderstood... 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];],, (exit 1); exit)
|
|
@end example
|
|
|
|
@noindent
|
|
is incorrect: here the first argument of @code{AC_COMPILE_IFELSE}, is
|
|
@samp{char b[10];}, and it will be expanded once, which results in
|
|
@samp{char b10;}. There was a idiom developed in the Autoconf world to
|
|
address this issue, based on 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];]],, (exit 1); exit)
|
|
@end example
|
|
|
|
@noindent
|
|
and voil@`a! You really produced @samp{char b[10];}.
|
|
|
|
The careful reader will note that the so-called perfectly quoted
|
|
@code{AC_CHECK_HEADER} example above is actually lacking three pairs of
|
|
quotes! Nevertheless, for sake of readability, double quotation of
|
|
literals is used only where needed.
|
|
|
|
|
|
Some macros take optional arguments, which this documentation represents
|
|
@ovar{arg} (not to be confounded with the quote characters). You may
|
|
just leave them empty, or use @samp{[]} to make explicit the emptiness
|
|
of the argument. Finally you may simply leave out 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.in}. 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 @code{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.in} files by starting them
|
|
with the @samp{#}. For example, it is helpful to begin
|
|
@file{configure.in} files with a line like this:
|
|
|
|
@example
|
|
# Process this file with autoconf to produce a configure script.
|
|
@end example
|
|
|
|
@node configure.in Layout, , Autoconf Language, Writing configure.in
|
|
@subsection Standard @file{configure.in} Layout
|
|
|
|
The order in which @file{configure.in} calls the Autoconf macros is not
|
|
important, with a few exceptions. Every @file{configure.in} 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 creating @code{configure} 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 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, ifnames Invocation, Writing configure.in, Making configure Scripts
|
|
@section Using @code{autoscan} to Create @file{configure.in}
|
|
@cindex @code{autoscan}
|
|
|
|
The @code{autoscan} program can help you create a @file{configure.in}
|
|
file for a software package. @code{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.in} for
|
|
that package.
|
|
|
|
You should manually examine @file{configure.scan} before renaming it to
|
|
@file{configure.in}; it will probably need some adjustments.
|
|
Occasionally @code{autoscan} outputs a macro in the wrong order relative
|
|
to another macro, so that @code{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).
|
|
|
|
@code{autoscan} uses several data files, which are installed along with the
|
|
distributed Autoconf macro files, to determine which macros to output
|
|
when it finds particular symbols in a package's source files. These
|
|
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.
|
|
|
|
@code{autoscan} is only installed if you already have Perl installed.
|
|
@code{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 --autoconf-dir=@var{dir}
|
|
@itemx -A
|
|
@evindex AC_MACRODIR
|
|
Overwrite the location where Autoconf files were installed. You can
|
|
also set the @code{AC_MACRODIR} environment variable to a directory;
|
|
this option overrides the environment variable.
|
|
|
|
This option is rarely needed and dangerous: only when you play with
|
|
different versions of Autoconf.
|
|
@end table
|
|
|
|
@node ifnames Invocation, autoconf Invocation, autoscan Invocation, Making configure Scripts
|
|
@section Using @code{ifnames} to List Conditionals
|
|
@cindex @code{ifnames}
|
|
|
|
@code{ifnames} can help when writing a @file{configure.in} 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, this program can help you figure out what
|
|
its @code{configure} needs to check for. It may help fill in some gaps
|
|
in a @file{configure.in} generated by @code{autoscan} (@pxref{autoscan
|
|
Invocation}).
|
|
|
|
@code{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
|
|
@code{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, autoreconf Invocation, ifnames Invocation, Making configure Scripts
|
|
@section Using @code{autoconf} to Create @code{configure}
|
|
@cindex @code{autoconf}
|
|
|
|
To create @code{configure} from @file{configure.in}, run the
|
|
@code{autoconf} program with no arguments. @code{autoconf} processes
|
|
@file{configure.in} with the @code{m4} macro processor, using the
|
|
Autoconf macros. If you give @code{autoconf} an argument, it reads that
|
|
file instead of @file{configure.in} and writes the configuration script
|
|
to the standard output instead of to @code{configure}. If you give
|
|
@code{autoconf} the argument @option{-}, it reads the standard input
|
|
instead of @file{configure.in} and writes the configuration script on
|
|
the standard output.
|
|
|
|
The Autoconf macros are defined in several files. Some of the files are
|
|
distributed with Autoconf; @code{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 Macros}, for more information). If a macro is defined
|
|
in more than one of the files that @code{autoconf} reads, the last
|
|
definition it reads overrides the earlier ones.
|
|
|
|
@code{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 --autoconf-dir=@var{dir}
|
|
@itemx -A
|
|
@evindex AC_MACRODIR
|
|
Overwrite the location where Autoconf files were installed. You can
|
|
also set the @code{AC_MACRODIR} environment variable to a directory;
|
|
this option overrides the environment variable.
|
|
|
|
This option is rarely needed and dangerous: only when you play with
|
|
different versions of Autoconf.
|
|
|
|
@item --localdir=@var{dir}
|
|
@itemx -l @var{dir}
|
|
Look for the package file @file{aclocal.m4} in directory @var{dir}
|
|
instead of in the current directory.
|
|
|
|
@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. @command{autoconf} will actually behave as if you had run
|
|
|
|
@example
|
|
autoconf --warnings=syntax,$WARNINGS,@var{categories}
|
|
@end example
|
|
|
|
@noindent
|
|
If you want to disable @command{autoconf}'s defaults and @code{WARNING}
|
|
but enable the warnings about obsolete constructs, use @samp{-W
|
|
none,obsolete}.
|
|
|
|
@item --trace=@var{macro}[:@var{format}]
|
|
@itemx -t @var{macro}[:@var{format}]
|
|
Do not create the @code{configure} script, but list the calls to
|
|
@var{macro} according to the @var{format}. Multiple @option{--trace} list
|
|
several macros. Multiple @option{--trace} for a single macro do not
|
|
accumulate, nevertheless, @var{format} can be arbitrarily long.
|
|
|
|
The @var{format} is a regular string, with new lines if wanted. It
|
|
defaults to @samp{$f:$l:$n:$%}, see below 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.in} file,
|
|
but it is extremely fragile and error prone to try to parse it. It is
|
|
suggested to rely upon @option{--trace} to scan @file{configure.in}.
|
|
|
|
The @var{format} of @option{--trace} can use the following special
|
|
escapes:
|
|
|
|
@table @samp
|
|
@item $$
|
|
The character @samp{$}.
|
|
|
|
@item $f
|
|
The filename from where @var{macro} is called.
|
|
|
|
@item $l
|
|
The line number from where @var{macro} is called.
|
|
|
|
@item $d
|
|
The depth of the @var{macro} call. This is an M4 technical detail which
|
|
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 given to the @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 bracket.
|
|
|
|
@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 traces that hold in a single line (unless
|
|
you put new lines in the @samp{separator}), while @samp{$@@} and
|
|
@samp{$*} do not.
|
|
@end table
|
|
|
|
For instance, to know the list of variables that are substituted:
|
|
|
|
@example
|
|
@group
|
|
% autoconf -t AC_SUBST
|
|
configure.in:2:AC_SUBST:ECHO_C
|
|
configure.in:2:AC_SUBST:ECHO_N
|
|
configure.in: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
|
|
% cat configure.in
|
|
AC_DEFINE(This, is, [an
|
|
[example]])
|
|
% autoconf -t 'AC_DEFINE:@@: $@@
|
|
*: $*
|
|
%: $%'
|
|
@@: [This],[is],[an
|
|
[example]]
|
|
*: This,is,an
|
|
[example]
|
|
%: This:is:an [example]
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
Much freedom is given over the @var{format}:
|
|
|
|
@example
|
|
@group
|
|
% autoconf -t 'AC_SUBST:ac_subst@{"$1"@} = "$f:$l";'
|
|
ac_subst@{"ECHO_C"@} = "configure.in:2";
|
|
ac_subst@{"ECHO_N"@} = "configure.in:2";
|
|
ac_subst@{"ECHO_T"@} = "configure.in:2";
|
|
@i{More traces deleted}
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
The long @var{separator}s can be used to ease parsing of complex
|
|
structures:
|
|
|
|
@example
|
|
@group
|
|
% 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, , autoconf Invocation, Making configure Scripts
|
|
@section Using @code{autoreconf} to Update @code{configure} Scripts
|
|
@cindex @code{autoreconf}
|
|
|
|
If you have a lot of Autoconf-generated @code{configure} scripts, the
|
|
@code{autoreconf} program can save you some work. It runs
|
|
@code{autoconf} (and @code{autoheader}, where appropriate) repeatedly to
|
|
remake the Autoconf @code{configure} scripts and configuration header
|
|
templates in the directory tree rooted at the current directory. By
|
|
default, it only remakes those files that are older than their
|
|
@file{configure.in} or (if present) @file{aclocal.m4}. Since
|
|
@code{autoheader} does not change the timestamp of its output file if
|
|
the file wouldn't be changing, this is not necessarily the minimum
|
|
amount of work. If you install a new version of Autoconf, you can make
|
|
@code{autoreconf} remake @emph{all} of the files by giving it the
|
|
@option{--force} option.
|
|
|
|
If you give @code{autoreconf} the @option{--autoconf-dir=@var{dir}} or
|
|
@option{--localdir=@var{dir}} options, it passes them down to
|
|
@code{autoconf} and @code{autoheader} (with relative paths adjusted
|
|
properly).
|
|
|
|
@code{autoreconf} does not support having, in the same directory tree,
|
|
both directories that are parts of a larger package (sharing
|
|
@file{aclocal.m4} and @file{acconfig.h}), and directories that are
|
|
independent packages (each with their own @file{aclocal.m4} and
|
|
@file{acconfig.h}). It assumes that they are all part of the same
|
|
package, if you use @option{--localdir}, or that each directory is a
|
|
separate package, if you don't use it. This restriction may be removed
|
|
in the future.
|
|
|
|
@xref{Automatic Remaking}, for @file{Makefile} rules to automatically
|
|
remake @code{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
|
|
@code{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 @code{autoreconf} runs
|
|
@code{autoconf} (and @code{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.in} and, if present,
|
|
@file{aclocal.m4}).
|
|
|
|
@item --localdir=@var{dir}
|
|
@itemx -l @var{dir}
|
|
Have @code{autoconf} and @code{autoheader} look for the package files
|
|
@file{aclocal.m4} and (@code{autoheader} only) @file{acconfig.h} (but
|
|
not @file{@var{file}.top} and @file{@var{file}.bot}) in directory
|
|
@var{dir} instead of in the directory containing each @file{configure.in}.
|
|
|
|
@item --autoconf-dir=@var{dir}
|
|
@itemx -A
|
|
@evindex AC_MACRODIR
|
|
Overwrite the location where Autoconf files were installed. You can
|
|
also set the @code{AC_MACRODIR} environment variable to a directory;
|
|
this option overrides the environment variable.
|
|
|
|
This option is rarely needed and dangerous: only when you play with
|
|
different versions of Autoconf.
|
|
@end table
|
|
|
|
|
|
@c ========================================= Initialization and Output Files.
|
|
|
|
@node Setup, Existing Tests, Making configure Scripts, Top
|
|
@chapter Initialization and Output Files
|
|
|
|
Autoconf-generated @code{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
|
|
initialization and creating output files.
|
|
|
|
@menu
|
|
* Notices:: Copyright, version numbers in @code{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 from the configuration
|
|
* Subdirectories:: Configuring independent packages together
|
|
* Default Prefix:: Changing the default installation prefix
|
|
@end menu
|
|
|
|
@node Notices, Input, Setup, Setup
|
|
@section Notices in @code{configure}
|
|
|
|
The following macros manage version numbers for @code{configure}
|
|
scripts. Using them is optional.
|
|
|
|
@c FIXME: AC_PREREQ should not be here, but where should it go?
|
|
@defmac AC_PREREQ (@var{version})
|
|
@maindex PREREQ
|
|
@cindex Version
|
|
Ensure that a recent enough version of Autoconf is being used. If the
|
|
version of Autoconf being used to create @code{configure} is earlier
|
|
than @var{version}, print an error message on the standard error output
|
|
and do not create @code{configure}. 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})
|
|
@maindex COPYRIGHT
|
|
@cindex Copyright Notice
|
|
State that in addition to the Free Software Foundation's copyright over
|
|
the Autoconf macros, parts of your @code{configure} are covered by the
|
|
@var{copyright-notice}.
|
|
|
|
The @var{copyright-notice} will show up in both the head of
|
|
@code{configure}, and in @samp{configure --version}.
|
|
@end defmac
|
|
|
|
|
|
@defmac AC_REVISION (@var{revision-info})
|
|
@maindex REVISION
|
|
@cindex Revision
|
|
Copy revision stamp @var{revision-info} into the @code{configure}
|
|
script, with any dollar signs or double-quotes removed. This macro lets
|
|
you put a revision stamp from @file{configure.in} into @code{configure}
|
|
without @sc{rcs} or @code{cvs} changing it when you check in
|
|
@code{configure}. That way, you can determine easily which revision of
|
|
@file{configure.in} a particular @code{configure} corresponds to.
|
|
|
|
For example, this line in @file{configure.in}:
|
|
|
|
@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 @code{configure}:
|
|
|
|
@example
|
|
#! /bin/sh
|
|
# From configure.in Revision: 1.30
|
|
@end example
|
|
@end defmac
|
|
|
|
|
|
@node Input, Output, Notices, Setup
|
|
@section Finding @code{configure} Input
|
|
|
|
Every @code{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-address})
|
|
@maindex INIT
|
|
Process any command-line arguments and perform various initializations
|
|
and verifications. Set the name of the @var{package} and its
|
|
@var{version}. The optional argument @var{bug-report-address} should be
|
|
the email to which users should send bug reports.
|
|
@end defmac
|
|
|
|
@defmac AC_CONFIG_SRCDIR (@var{unique-file-in-source-dir})
|
|
@maindex CONFIG_SRCDIR
|
|
@var{unique-file-in-source-dir} is some file that is in the package's
|
|
source directory; @code{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}...)
|
|
@c @maindex 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 @code{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})
|
|
@maindex CONFIG_AUX_DIR
|
|
Use the @file{install-sh}, @file{config.sub}, @file{config.guess}, and
|
|
Cygnus @code{configure} scripts 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} programs have a rule that
|
|
creates @file{install} from it if there is no @file{Makefile}.
|
|
@end defmac
|
|
|
|
|
|
@node Output, Configuration Actions, Input, Setup
|
|
@section Outputting Files
|
|
|
|
Every Autoconf-generated @code{configure} script must finish by calling
|
|
@code{AC_OUTPUT}. It is the macro that generates @file{config.status}
|
|
which will create the @file{Makefile}s and optional other files
|
|
resulting from configuration. The only other required macro is
|
|
@code{AC_INIT} (@pxref{Input}).
|
|
|
|
Because of history, this macro is described twice below. The first
|
|
definition describes the use that is now recommended. The second
|
|
describes the former use, and its modern equivalent.
|
|
|
|
@defmac AC_OUTPUT
|
|
@maindex OUTPUT
|
|
@cindex Instantiation
|
|
Generate @file{config.status} and launch it. Call this macro once, at
|
|
the end of @file{configure.in}.
|
|
|
|
@file{config.status} will take 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.
|
|
@end defmac
|
|
|
|
@xref{Obsolete Macros}, for a description of the arguments @code{AC_OUTPUT}
|
|
used to support.
|
|
|
|
|
|
If you run @code{make} on subdirectories, you should run it using the
|
|
@code{make} variable @code{MAKE}. Most versions of @code{make} set
|
|
@code{MAKE} to the name of the @code{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 @code{make} do not set this variable. The
|
|
following macro allows you to use it even with those versions.
|
|
|
|
@defmac AC_PROG_MAKE_SET
|
|
@maindex PROG_MAKE_SET
|
|
@ovindex SET_MAKE
|
|
If @code{make} predefines the 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
|
|
|
|
To 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, Configuration Files, Output, Setup
|
|
@section Taking Configuration Actions
|
|
|
|
While everything is made so that you imagine @file{configure} does
|
|
everything by itself, 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},
|
|
macro @code{AC_CONFIG_COMMANDS}, and @code{AC_CONFIG_LINKS}. They all
|
|
have this prototype:
|
|
|
|
@c Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
|
|
@c awful.
|
|
@example
|
|
AC_CONFIG_FOOS(@var{tag}..., [@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.
|
|
|
|
@item commands
|
|
They are output into @file{config.status} as literally. These commands
|
|
are always associated to a tag which the user can use to tell
|
|
@file{config.status} what are the commands she wants to run. These
|
|
commands are run each time a @var{tag} request is given to
|
|
@file{config.status}, i.e., typically each time the file
|
|
@file{@var{tag}} is created.
|
|
|
|
@item init-cmds
|
|
They are output via an @emph{unquoted} here-doc. As a consequence
|
|
@samp{$var} will be output as the value of @var{var}. This is typically
|
|
used by @file{configure} to give @file{config.status} some variables it
|
|
needs to run the @var{cmds}. At the difference of @var{cmds}, the
|
|
@var{init-cmds} are always run.
|
|
@end table
|
|
|
|
All these macros can be called multiple times, with different
|
|
@var{tag}s, of course!
|
|
|
|
You are encouraged to use literals as @var{tags}. In particular, you
|
|
should avoid
|
|
|
|
@example
|
|
... && my_foos="$my_foos fooo"
|
|
... && my_foos="$my_foos foooo"
|
|
AC_CONFIG_FOOS($my_foos)
|
|
@end example
|
|
|
|
@noindent
|
|
and use this instead:
|
|
|
|
@example
|
|
... && AC_CONFIG_FOOS(fooo)
|
|
... && AC_CONFIG_FOOS(foooo)
|
|
@end example
|
|
|
|
The macro @code{AC_CONFIG_FILES} and @code{AC_CONFIG_HEADERS} use
|
|
specials @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} if specified, 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.in}, 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.
|
|
|
|
|
|
@node Configuration Files, Makefile Substitutions, Configuration Actions, Setup
|
|
@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})
|
|
@maindex 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 FIXME: 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, Configuration Headers, Configuration Files, Setup
|
|
@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 @code{configure} will create a @file{Makefile} in that directory.
|
|
To create a @file{Makefile}, @code{configure} performs a simple variable
|
|
substitution, replacing occurrences of @samp{@@@var{variable}@@} in
|
|
@file{Makefile.in} with the value that @code{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 @code{configure}. To make @code{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 @code{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
|
|
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, Installation Directory Variables, Makefile Substitutions, Makefile Substitutions
|
|
@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.
|
|
|
|
@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 @code{configure} runs, the default value is set
|
|
when you call @code{AC_PROG_CC} (or empty if you don't). @code{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
|
|
@code{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 @code{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 @code{configure} runs, the default
|
|
value is empty. @code{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 @code{configure} runs, the default value is
|
|
set when you call @code{AC_PROG_CXX} (or empty if you don't).
|
|
@code{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, @code{configure} replaces @samp{@@DEFS@@} with
|
|
@option{-DHAVE_CONFIG_H} instead (@pxref{Configuration Headers}). This
|
|
variable is not defined while @code{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 to suppress the trailing newline from @code{echo} for
|
|
question... answer reports:
|
|
|
|
@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} 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 FFLAGS
|
|
@ovindex FFLAGS
|
|
Debugging and optimization options for the Fortran 77 compiler. If it
|
|
is not set in the environment when @code{configure} runs, the default
|
|
value is set when you call @code{AC_PROG_F77} (or empty if you don't).
|
|
@code{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 @code{configure} runs, the default value is empty.
|
|
@code{configure} uses this variable when linking programs to test for
|
|
C, C++ and Fortran 77 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}. @code{configure} uses this variable when linking
|
|
programs to test for C, C++ and Fortran 77 features.
|
|
@end defvar
|
|
|
|
@defvar srcdir
|
|
@ovindex srcdir
|
|
The directory that contains the source code for that @file{Makefile}.
|
|
@end defvar
|
|
|
|
@defvar top_srcdir
|
|
@ovindex top_srcdir
|
|
The top-level source code directory for the package. In the top-level
|
|
directory, this is the same as @code{srcdir}.
|
|
@end defvar
|
|
|
|
@node Installation Directory Variables, Build Directories, Preset Output Variables, Makefile Substitutions
|
|
@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 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.
|
|
@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 installation prefix 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 on purpose 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 @sc{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 to her late desires.
|
|
|
|
@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 but in
|
|
Makefiles. For instance instead of trying to resolve the dependencies
|
|
of @code{datadir} upon @code{prefix} and using
|
|
@samp{AC_DEFINE_UNQUOTED(DATADIR, "$datadir")}, you should add
|
|
@samp{-DDATADIR="$(datadir)"} to your @code{CFLAGS}.
|
|
|
|
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{.sh}, and uses this
|
|
Makefile snippet:
|
|
|
|
@example
|
|
.sh:
|
|
rm -f $@@ $@@.tmp
|
|
sed 's,@@datadir\@@,$(pkgdatadir),g' $< >$@@.tmp
|
|
chmod +x $@@.tmp
|
|
mv $@@.tmp $@@
|
|
@end example
|
|
|
|
Three things 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 probably the
|
|
variables you use, such as @samp{$(pkgdatadir)}, will contain
|
|
some.
|
|
@end table
|
|
|
|
|
|
@node Build Directories, Automatic Remaking, Installation Directory Variables, Makefile Substitutions
|
|
@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, @code{make} uses the @code{VPATH} variable to
|
|
find the files that are in the source directory. @sc{gnu} @code{make}
|
|
and most other recent @code{make} programs can do this. Older
|
|
@code{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 @code{make} do not do
|
|
variable substitutions on the value of @code{VPATH}.
|
|
|
|
@code{configure} substitutes in 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 @code{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, , Build Directories, Makefile Substitutions
|
|
@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 @code{make} will consider @file{config.h.in}
|
|
up to date. On some old @sc{bsd} systems, @code{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.
|
|
@c Using @code{date} would cause needless CVS conflicts.
|
|
|
|
@example
|
|
@group
|
|
$(srcdir)/configure: configure.in 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.in aclocal.m4 acconfig.h \
|
|
config.h.top config.h.bot
|
|
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
|
|
|
|
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, Configuration Commands, Makefile Substitutions, Setup
|
|
@section Configuration Header Files
|
|
@cindex Configuration Header
|
|
@cindex @file{config.h}
|
|
|
|
When a package tests more than a few 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 @code{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, @code{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})
|
|
@maindex 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
|
|
some changes in 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, autoheader Invocation, Configuration Headers, Configuration Headers
|
|
@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.in} 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}, @code{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
|
|
|
|
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.
|
|
|
|
Since it is a tedious task to keep a template header up to date, you may
|
|
use @code{autoheader} to generate it, see @ref{autoheader Invocation}.
|
|
|
|
|
|
@node autoheader Invocation, Autoheader Macros, Header Templates, Configuration Headers
|
|
@subsection Using @code{autoheader} to Create @file{config.h.in}
|
|
@cindex @code{autoheader}
|
|
|
|
The @command{autoheader} program can create a template file of C
|
|
@samp{#define} statements for @code{configure} to use. If
|
|
@file{configure.in} 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 that you document all
|
|
the symbols that you might use, i.e., that there is at least one
|
|
@code{AC_DEFINE} or one @code{AC_DEFINE_UNQUOTED} using its third
|
|
argument, see @ref{Defining Symbols}. An additional constraint is that
|
|
the first argument must be a literal.
|
|
|
|
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 losing our
|
|
time maintaining @command{autoheader}: generating directly
|
|
@file{config.h} is just what is needed.
|
|
|
|
But when things go wrong, you'll thank the Autoconf team for
|
|
@command{autoheader}...
|
|
|
|
The fact that the symbols are documented is precious 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 precious 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...
|
|
|
|
If you give @command{autoheader} an argument, it uses that file instead
|
|
of @file{configure.in} 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.in} and writes the header file to the standard output.
|
|
|
|
@code{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 --debug
|
|
@itemx -d
|
|
Don't remove the temporary files.
|
|
|
|
@item --autoconf-dir=@var{dir}
|
|
@itemx -A
|
|
@evindex AC_MACRODIR
|
|
Overwrite the location where Autoconf files were installed. You can
|
|
also set the @code{AC_MACRODIR} environment variable to a directory;
|
|
this option overrides the environment variable.
|
|
|
|
This option is rarely needed and dangerous: only when you play with
|
|
different versions of Autoconf.
|
|
|
|
@item --localdir=@var{dir}
|
|
@itemx -l @var{dir}
|
|
Look for the package files @file{aclocal.m4} and @file{acconfig.h} (but
|
|
not @file{@var{file}.top} and @file{@var{file}.bot}) in directory
|
|
@var{dir} instead of in the current directory.
|
|
|
|
@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, , autoheader Invocation, Configuration Headers
|
|
@subsection Autoheader Macros
|
|
|
|
@code{autoheader} scans @file{configure.in} 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. @code{autoheader} diagnoses
|
|
missing templates, and fails.
|
|
|
|
The simplest means to create a template for a @var{symbol} is simply to
|
|
document one of the @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})
|
|
@maindex AH_VERBATIM
|
|
@maindex VERBATIM
|
|
Inform @code{autoheader} that it must include the @var{template} as is
|
|
in the header template file. This @var{template} is associated to the
|
|
@var{key}, which is used to sort all the different templates, and
|
|
guarantee their uniqueness. It should be the symbol that can be
|
|
@code{AC_DEFINE}'d.
|
|
|
|
For instance:
|
|
|
|
@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})
|
|
@maindex AH_TEMPLATE
|
|
@maindex TEMPLATE
|
|
Inform @code{autoheader} that it must generate a template for @var{key}.
|
|
This macro generates standard templates, as @code{AC_DEFINE} does when a
|
|
@var{description} is given.
|
|
|
|
For instance:
|
|
|
|
@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})
|
|
@maindex AH_TOP
|
|
@maindex TOP
|
|
Include @var{text} at the top of the header template file.
|
|
@end defmac
|
|
|
|
|
|
@defmac AH_BOTTOM (@var{text})
|
|
@maindex AH_BOTTOM
|
|
@maindex BOTTOM
|
|
Include @var{text} at the bottom of the header template file.
|
|
@end defmac
|
|
|
|
|
|
@node Configuration Commands, Configuration Links, Configuration Headers, Setup
|
|
@section Running Arbitrary Configuration Commands
|
|
|
|
You execute arbitrary commands either 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})
|
|
@maindex CONFIG_COMMANDS
|
|
Specify additional shell commands to run at the end of
|
|
@file{config.status}, and shell commands to initialize any variables
|
|
from @code{configure}. Associate the commands to the @var{tag}. Since
|
|
typically the @var{cmds} create a file, @var{tag} should naturally be
|
|
the name of that file. 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})
|
|
@maindex OUTPUT_COMMANDS_PRE
|
|
Execute the @var{cmds} right before creating @file{config.status}. A
|
|
typical use is computing values derived from variables built during the
|
|
execution of @code{configure}:
|
|
|
|
@example
|
|
AC_CONFIG_COMMANDS_PRE(
|
|
[LTLIBOBJS=`echo $LIBOBJS | sed 's/\.o/\.lo/g'`
|
|
AC_SUBST(LTLIBOBJS)])
|
|
@end example
|
|
@end defmac
|
|
|
|
@defmac AC_CONFIG_COMMANDS_POST (@var{cmds})
|
|
@maindex OUTPUT_COMMANDS_POST
|
|
Execute the @var{cmds} right after creating @file{config.status}.
|
|
@end defmac
|
|
|
|
|
|
|
|
|
|
@node Configuration Links, Subdirectories, Configuration Commands, Setup
|
|
@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 another directory than its sources.
|
|
|
|
@defmac AC_CONFIG_LINKS (@var{dest}:@var{source}@dots{}, @ovar{cmds}, @ovar{init-cmds})
|
|
@maindex 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. 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. It
|
|
is then valid to run:
|
|
@example
|
|
./config.status host.h object.h
|
|
@end example
|
|
to establish the links.
|
|
@end defmac
|
|
|
|
|
|
|
|
@node Subdirectories, Default Prefix, Configuration Links, Setup
|
|
@section Configuring Other Packages in Subdirectories
|
|
|
|
In most situations, calling @code{AC_OUTPUT} is sufficient to produce
|
|
@file{Makefile}s in subdirectories. However, @code{configure} scripts
|
|
that control more than one independent package can use
|
|
@code{AC_CONFIG_SUBDIRS} to run @code{configure} scripts for other
|
|
packages in subdirectories.
|
|
|
|
@defmac AC_CONFIG_SUBDIRS (@var{dir} @dots{})
|
|
@maindex CONFIG_SUBDIRS
|
|
@ovindex subdirs
|
|
Make @code{AC_OUTPUT} run @code{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, no error is reported, so a
|
|
@code{configure} script can configure whichever parts of a large source
|
|
tree are present. If a given @var{dir} contains @code{configure.gnu},
|
|
it is run instead of @code{configure}. This is for packages that might
|
|
use a non-autoconf script @code{Configure}, which can't be called
|
|
through a wrapper @code{configure} since it would be the same file on
|
|
case-insensitive filesystems. Likewise, if a @var{dir} contains
|
|
@file{configure.in} but no @code{configure}, the Cygnus @code{configure}
|
|
script found by @code{AC_CONFIG_AUXDIR} is used.
|
|
|
|
The subdirectory @code{configure} scripts are given the same command
|
|
line options that were given to this @code{configure} script, with minor
|
|
changes if needed (e.g., to adjust a relative path for the cache file or
|
|
source directory). 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, , Subdirectories, Setup
|
|
@section Default Prefix
|
|
|
|
By default, @code{configure} sets the prefix for files it installs to
|
|
@file{/usr/local}. The user of @code{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
|
|
@code{configure}, and when running it.
|
|
|
|
Some software packages might want to install in a directory besides
|
|
@file{/usr/local} by default. To accomplish that, use the
|
|
@code{AC_PREFIX_DEFAULT} macro.
|
|
|
|
@defmac AC_PREFIX_DEFAULT (@var{prefix})
|
|
Set the default installation prefix to @var{prefix} instead of
|
|
@file{/usr/local}.
|
|
@end defmac
|
|
|
|
It may be convenient for users to have @code{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})
|
|
@maindex 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}; otherwise leave the prefix specified in
|
|
@file{Makefile.in} unchanged. 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, Writing Tests, Setup, Top
|
|
@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
|
|
@code{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
|
|
* 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
|
|
* C Compiler Characteristics::
|
|
* Fortran 77 Compiler Characteristics::
|
|
* System Services:: Operating system services
|
|
* UNIX Variants:: Special kludges for specific UNIX variants
|
|
@end menu
|
|
|
|
@node Common Behavior, Alternative Programs, Existing Tests, Existing Tests
|
|
@section Common Behavior
|
|
|
|
Much effort was put into Autoconf to make it easy to learn. The most
|
|
obvious way to reach this goal is simply to enforce standard and
|
|
rigorous schemes, and to avoid as much as possible exceptions. Because
|
|
of history and momentum, 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, Default Includes, Common Behavior, Common Behavior
|
|
@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 mapped to upper case and any star @samp{*} to
|
|
@samp{P}. Any characters that remain that are not alpha-numerical or
|
|
underscores are mapped to underscores.
|
|
|
|
For instance
|
|
|
|
@example
|
|
AC_CHECK_TYPES(struct $Expensive*)
|
|
@end example
|
|
|
|
@noindent
|
|
may define the symbol @samp{HAVE_STRUCT__EXPENSIVEP}.
|
|
|
|
|
|
@node Default Includes, , Standard Symbols, Common Behavior
|
|
@subsection Default Includes
|
|
@cindex Includes, default
|
|
|
|
Several tests depend upon a set of headers. Since headers are not
|
|
universally available, you 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 provide the following default set of includes:
|
|
|
|
@example
|
|
@group
|
|
#include <stdio.h>
|
|
#include <sys/types.h>
|
|
#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>
|
|
#else
|
|
# if HAVE_STRINGS_H
|
|
# include <strings.h>
|
|
# endif
|
|
#endif
|
|
#if HAVE_INTTYPES_H
|
|
# include <inttypes.h>
|
|
#endif
|
|
#if HAVE_UNISTD_H
|
|
# include <unistd.h>
|
|
#endif
|
|
@end group
|
|
@end example
|
|
|
|
|
|
@node Alternative Programs, Libraries, Common Behavior, Existing Tests
|
|
@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, Generic Programs, Alternative Programs, Alternative 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
|
|
@maindex PROG_AWK
|
|
@ovindex AWK
|
|
Check for @code{mawk}, @code{gawk}, @code{nawk}, and @code{awk}, in that
|
|
order, and set output variable @code{AWK} to the first one that is found.
|
|
It tries @code{mawk} first because that is reported to be the
|
|
fastest implementation.
|
|
@end defmac
|
|
|
|
|
|
@defmac AC_PROG_INSTALL
|
|
@maindex PROG_INSTALL
|
|
@ovindex INSTALL
|
|
@ovindex INSTALL_PROGRAM
|
|
@ovindex INSTALL_DATA
|
|
@ovindex INSTALL_SCRIPT
|
|
Set output variable @code{INSTALL} to the path of a @sc{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 @code{make} programs have a rule
|
|
that creates @file{install} from it if there is no @file{Makefile}.
|
|
|
|
A copy of @file{install-sh} which you may use comes with Autoconf. If
|
|
you use @code{AC_PROG_INSTALL}, you must include either
|
|
@file{install-sh} or @file{install.sh} in your distribution, or
|
|
@code{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 @sc{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
|
|
@maindex 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. But in order to ensure portability, you must either provide a
|
|
function @code{yywrap}, or if you don't use it (i.e., 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 (well, 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.
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_LN_S
|
|
@maindex 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 output variable @code{LN_S}
|
|
to @samp{ln -s}, otherwise if @samp{ln} works, set @code{LN_S} to
|
|
@samp{ln}, and otherwise set to @samp{cp}.
|
|
|
|
If the link is put 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
|
|
@maindex PROG_RANLIB
|
|
@ovindex RANLIB
|
|
Set output variable @code{RANLIB} to @samp{ranlib} if @code{ranlib}
|
|
is found, otherwise to @samp{:} (do nothing).
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_YACC
|
|
@maindex 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, , Particular Programs, Alternative 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
|
|
|
|
@defmac AC_CHECK_FILE (@var{file}, @ovar{action-if-found}, @ovar{action-if-not-found})
|
|
@maindex 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})
|
|
@maindex 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
|
|
|
|
@defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @var{value-if-found}, @ovar{value-if-not-found}, @ovar{path}, @ovar{reject})
|
|
@maindex 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})
|
|
@maindex CHECK_PROGS
|
|
Check for each program in the whitespace-separated list
|
|
@var{progs-to-check-for} exists on the @code{PATH}. If it 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})
|
|
@maindex 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 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})
|
|
@maindex 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})
|
|
@maindex 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})
|
|
@maindex 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})
|
|
@maindex PATH_TOOL
|
|
Like @code{AC_PATH_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_PATH_TOOL(FILE, file, :, /usr/bin:$PATH)
|
|
@end example
|
|
@noindent
|
|
sets @code{FILE} to @file{/usr/bin/i386-gnu-file}, for example, if
|
|
that program is found at @file{/usr/bin} in @code{PATH}, or to
|
|
@samp{/usr/bin/file}, for example, if @emph{that} program is found at
|
|
@file{/usr/bin} in @code{PATH}, or to @samp{:} if neither program can
|
|
be found.
|
|
@end defmac
|
|
|
|
|
|
@node Libraries, Library Functions, Alternative Programs, Existing Tests
|
|
@section Library Files
|
|
@cindex Library, checking
|
|
|
|
The following macros check for the presence of certain C, C++ or Fortran
|
|
77 library archive files.
|
|
|
|
@defmac AC_CHECK_LIB (@var{library}, @var{function}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
|
|
@maindex CHECK_LIB
|
|
Depending on the current language(@pxref{Language Choice}), try to
|
|
ensure that the C, C++ or Fortran 77 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 of @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 that @code{LIBS} is generated in is important to reliable
|
|
detection of libraries.
|
|
|
|
If linking with @var{library} results in unresolved symbols, which would
|
|
be resolved by linking with additional libraries, give those libraries
|
|
as the @var{other-libraries} argument, separated by spaces: @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 the library in the presence of
|
|
another (which may not already be 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})
|
|
@maindex SEARCH_LIBS
|
|
Search for a library defining @var{function}, if it's not already
|
|
available. This equates to calling @code{AC_TRY_LINK_FUNC} 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, which would
|
|
be resolved by linking with additional libraries, give those libraries
|
|
as the @var{other-libraries} argument, separated by spaces: @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, Header Files, Libraries, Existing Tests
|
|
@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
|
|
* Particular Functions:: Special handling to find certain functions
|
|
* Generic Functions:: How to find other functions
|
|
@end menu
|
|
|
|
@node Particular Functions, Generic Functions, Library Functions, Library 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
|
|
@maindex FUNC_ALLOCA
|
|
@cvindex C_ALLOCA
|
|
@cvindex HAVE_ALLOCA_H
|
|
@ovindex ALLOCA
|
|
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 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-@sc{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
|
|
@maindex FUNC_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
|
|
@maindex FUNC_CLOSEDIR_VOID
|
|
@cvindex CLOSEDIR_VOID
|
|
If the @code{closedir} function does not return a meaningful value,
|
|
define @code{CLOSEDIR_VOID}. Otherwise, callers ought to check its
|
|
return value for an error indicator.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_ERROR_AT_LINE
|
|
@maindex FUNC_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
|
|
@maindex FUNC_FNMATCH
|
|
If the @code{fnmatch} function is available and works (unlike the one on
|
|
SunOS 5.4), define @code{HAVE_FNMATCH}.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_GETGROUPS
|
|
@maindex FUNC_GETGROUPS
|
|
@ovindex GETGROUPS_LIBS
|
|
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
|
|
@maindex FUNC_GETLOADAVG
|
|
@cvindex SVR4
|
|
@cvindex DGUX
|
|
@cvindex UMAX
|
|
@cvindex UMAX4_3
|
|
@cvindex NLIST_STRUCT
|
|
@cvindex NLIST_NAME_UNION
|
|
@cvindex GETLODAVG_PRIVILEGED
|
|
@cvindex NEED_SETGID
|
|
@cvindex C_GETLOADAVG
|
|
@ovindex LIBOBJS
|
|
@ovindex NEED_SETGID
|
|
@ovindex KMEM_GROUP
|
|
@ovindex GETLOADAVG_LIBS
|
|
Check how to get the system load averages. 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 of @samp{getloadavg},
|
|
and possibly define several other C preprocessor macros and output
|
|
variables:
|
|
|
|
@enumerate
|
|
@item
|
|
Define @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if on
|
|
those systems.
|
|
|
|
@item
|
|
If @file{nlist.h} is found, define @code{NLIST_STRUCT}.
|
|
|
|
@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
|
|
@c FIXME: I don't understand anything to this sentence :(
|
|
If compiling @file{getloadavg.c} define @code{C_GETLOADAVG} and
|
|
@code{LDAV_PRIVILEGED}, programs need to be installed specially on this
|
|
system for @code{getloadavg} to work, and this macro defines
|
|
@code{GETLOADAVG_PRIVILEGED}.
|
|
|
|
@item
|
|
This macro sets the output variable @code{NEED_SETGID}. The value is
|
|
@samp{true} if special installation is required, @samp{false} if not.
|
|
If @code{NEED_SETGID} is @samp{true}, this macro sets @code{KMEM_GROUP}
|
|
to the name of the group that should own the installed program.
|
|
@end enumerate
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_GETMNTENT
|
|
@maindex FUNC_GETMNTENT
|
|
@cvindex HAVE_GETMNTENT
|
|
Check for @code{getmntent} in the @file{sun}, @file{seq}, and @file{gen}
|
|
libraries, for Irix 4, PTX, and Unixware, respectively. Then, if
|
|
@code{getmntent} is available, define @code{HAVE_GETMNTENT}.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_GETPGRP
|
|
@maindex FUNC_GETPGRP
|
|
@cvindex GETPGRP_VOID
|
|
If @code{getpgrp} takes no argument (the @sc{posix.1} version), define
|
|
@code{GETPGRP_VOID}. Otherwise, it is the @sc{bsd} version, which takes
|
|
a process ID as an argument. 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
|
|
@maindex FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK
|
|
@cvindex LSTAT_FOLLOWS_SLASHED_SYMLINK
|
|
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} and @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
|
|
@maindex FUNC_MALLOC
|
|
If the @code{malloc} works correctly (@samp{malloc (0)} returns a valid
|
|
pointer), define @code{HAVE_MALLOC}.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_MEMCMP
|
|
@maindex FUNC_MEMCMP
|
|
@ovindex LIBOBJS
|
|
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_MKTIME
|
|
@maindex FUNC_MKTIME
|
|
@ovindex LIBOBJS
|
|
If the @code{mktime} function is not available, or does not work
|
|
correctly, require an @code{AC_LIBOBJ} replacement for @samp{mktime}.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_MMAP
|
|
@maindex FUNC_MMAP
|
|
@cvindex HAVE_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
|
|
@maindex 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_SELECT_ARGTYPES
|
|
@maindex FUNC_SELECT_ARGTYPES
|
|
@cvindex SELECT_TYPE_ARG1
|
|
@cvindex SELECT_TYPE_ARG234
|
|
@cvindex SELECT_TYPE_ARG5
|
|
Determines the correct type to be passed to 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
|
|
@maindex FUNC_SETPGRP
|
|
@cvindex SETPGRP_VOID
|
|
If @code{setpgrp} takes no argument (the @sc{posix.1} version), define
|
|
@code{SETPGRP_VOID}. Otherwise, it is the @sc{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
|
|
@maindex FUNC_STAT
|
|
@maindex FUNC_LSTAT
|
|
@cvindex HAVE_STAT_EMPTY_STRING_BUG
|
|
@cvindex HAVE_LSTAT_EMPTY_STRING_BUG
|
|
Determine whether @code{stat} or @code{lstat} have the bug that it
|
|
succeeds when given the zero-length file name argument. The @code{stat}
|
|
and @code{lstat} from SunOS4.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
|
|
@maindex FUNC_SETVBUF_REVERSED
|
|
@cvindex SETVBUF_REVERSED
|
|
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
|
|
@maindex FUNC_STRCOLL
|
|
@cvindex HAVE_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
|
|
@maindex FUNC_STRTOD
|
|
@ovindex POW_LIB
|
|
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
|
|
@maindex FUNC_STRERROR_R
|
|
@cvindex HAVE_STRERROR_R
|
|
@cvindex HAVE_WORKING_STRERROR_R
|
|
If @code{strerror_r} is available, define @code{HAVE_STRERROR_R}. If
|
|
its implementation correctly returns a @code{char *}, define
|
|
@code{HAVE_WORKING_STRERROR_R}. On at least DEC UNIX 4.0[A-D] and HP-UX
|
|
B.10.20, @code{strerror_r} returns @code{int}. Actually, this tests
|
|
only whether it returns a scalar or an array, but that should be enough.
|
|
This is used by the common @file{error.c}.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_STRFTIME
|
|
@maindex FUNC_STRFTIME
|
|
@cvindex HAVE_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_UTIME_NULL
|
|
@maindex FUNC_UTIME_NULL
|
|
@cvindex HAVE_UTIME_NULL
|
|
If @samp{utime(@var{file}, NULL)} sets @var{file}'s timestamp to
|
|
the present, define @code{HAVE_UTIME_NULL}.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_VFORK
|
|
@maindex FUNC_VFORK
|
|
@cvindex HAVE_VFORK_H
|
|
@cvindex vfork
|
|
If @file{vfork.h} is found, define @code{HAVE_VFORK_H}. If a working
|
|
@code{vfork} is not found, define @code{vfork} to be @code{fork}. 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.
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_VPRINTF
|
|
@maindex FUNC_VPRINTF
|
|
@cvindex HAVE_VPRINTF
|
|
@cvindex HAVE_DOPRNT
|
|
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_FUNC_WAIT3
|
|
@maindex 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}.
|
|
@end defmac
|
|
|
|
@node Generic Functions, , Particular Functions, Library 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})
|
|
@maindex 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 is. (@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})
|
|
@maindex CHECK_FUNCS
|
|
@cvindex HAVE_@var{function}
|
|
For each given @var{function} in the whitespace-separated argument list
|
|
that is available, define @code{HAVE_@var{function}} (in all capitals).
|
|
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
|
|
|
|
Autoconf follows a philosophy that was formed throughout the years by the
|
|
people who fought for portability: isolate the portability issues in
|
|
specific files, and program as if you were in a @sc{posix} environment.
|
|
Some functions cannot be repaired or are completely missing; your
|
|
package must be ready to replace them.
|
|
|
|
Use the two following macros to specify the function that might be
|
|
replaced, and use the third one to check and replace a function if
|
|
needed.
|
|
|
|
@defmac AC_LIBOBJ (@var{function})
|
|
@maindex 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}, nevertheless you must not directly change
|
|
@code{LIBOBJS} since this is not traceable.
|
|
@end defmac
|
|
|
|
@defmac AC_LIBOBJ_DECL (@var{function})
|
|
@maindex LIBOBJ_DECL
|
|
@ovindex LIBOBJS
|
|
Specify that @samp{@var{function}.c} might be needed to compile the
|
|
project. You must use this macro when you are calling @code{AC_LIBOBJ}
|
|
with a shell variable, since shell variables cannot be traced
|
|
statically. @var{function} must be a literal.
|
|
|
|
For instance you might need to:
|
|
|
|
@example
|
|
AC_LIBOBJ_DECL(foo)
|
|
AC_LIBOBJ_DECL(bar)
|
|
AC_LIBOBJ($foo_or_bar)
|
|
@end example
|
|
|
|
@noindent
|
|
nevertheless, there is always a means to avoid this, and you are
|
|
encouraged to always uses literals with @code{AC_LIBOBJ}.
|
|
|
|
Conversely, if you need to know what are the files that might be needed
|
|
by a @file{configure.in}, you should trace @code{AC_LIBOBJ_DECL}.
|
|
@end defmac
|
|
|
|
|
|
@defmac AC_REPLACE_FUNCS (@var{function}@dots{})
|
|
@maindex REPLACE_FUNCS
|
|
@ovindex LIBOBJS
|
|
Like calling @code{AC_CHECK_FUNCS} using
|
|
@samp{AC_LIBOBJ(@var{function})} as @var{action-if-not-found}. You can
|
|
declare a function for which your replacement version is used 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, Declarations, Library Functions, Existing Tests
|
|
@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
|
|
* Particular Headers:: Special handling to find certain headers
|
|
* Generic Headers:: How to find other headers
|
|
@end menu
|
|
|
|
@node Particular Headers, Generic Headers, Header Files, Header Files
|
|
@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
|
|
@maindex HEADER_DIRENT
|
|
@cvindex HAVE_DIRENT_H
|
|
@cvindex HAVE_NDIR_H
|
|
@cvindex HAVE_SYS_DIR_H
|
|
@cvindex HAVE_SYS_NDIR_H
|
|
Check for the following header files, and 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 the 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
|
|
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
|
|
@maindex HEADER_MAJOR
|
|
@cvindex MAJOR_IN_MKDEV
|
|
@cvindex MAJOR_IN_SYSMACROS
|
|
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
|
|
@maindex HEADER_STAT
|
|
@maindex STAT_MACROS_BROKEN
|
|
If the macros @code{S_ISDIR}, @code{S_ISREG} et al. 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_STDC
|
|
@maindex HEADER_STDC
|
|
@cvindex STDC_HEADERS
|
|
Define @code{STDC_HEADERS} if the system has @sc{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 @sc{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 @sc{ansi} C requires.
|
|
|
|
Use @code{STDC_HEADERS} instead of @code{__STDC__} to determine whether
|
|
the system has @sc{ansi}-compliant header files (and probably C library
|
|
functions) because many systems that have GCC do not have @sc{ansi} C
|
|
header files.
|
|
|
|
On systems without @sc{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 @sc{ansi} and @sc{bsd}; some are mostly @sc{ansi} but
|
|
lack @samp{memmove}; some define the @sc{bsd} functions as macros in
|
|
@file{string.h} or @file{strings.h}; some have only the @sc{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 @sc{ansi} versions of those then it probably has
|
|
most of the others. If you put the following in @file{configure.in}:
|
|
|
|
@example
|
|
AC_HEADER_STDC
|
|
AC_CHECK_FUNCS(strchr memcpy)
|
|
@end example
|
|
|
|
@noindent
|
|
then, in your code, you can put 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 @sc{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
|
|
@maindex HEADER_SYS_WAIT
|
|
@cvindex HAVE_SYS_WAIT_H
|
|
If @file{sys/wait.h} exists and is compatible with @sc{posix.1}, define
|
|
@code{HAVE_SYS_WAIT_H}. Incompatibility can occur if @file{sys/wait.h}
|
|
does not exist, or if it uses the old @sc{bsd} @code{union wait} instead
|
|
of @code{int} to store a status value. If @file{sys/wait.h} is not
|
|
@sc{posix.1} compatible, then instead of including it, define the
|
|
@sc{posix.1} 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
|
|
@code{_POSIX_VERSION} is defined when @file{unistd.h} is included on
|
|
@sc{posix.1} systems. If there is no @file{unistd.h}, it is definitely
|
|
not a @sc{posix.1} system. However, some non-@sc{posix.1} systems do
|
|
have @file{unistd.h}.
|
|
|
|
The way to check if the system supports @sc{posix.1} is:
|
|
|
|
@example
|
|
@group
|
|
#if HAVE_UNISTD_H
|
|
# include <sys/types.h>
|
|
# include <unistd.h>
|
|
#endif
|
|
|
|
#ifdef _POSIX_VERSION
|
|
/* Code for POSIX.1 systems. */
|
|
#endif
|
|
@end group
|
|
@end example
|
|
|
|
@defmac AC_HEADER_TIME
|
|
@maindex HEADER_TIME
|
|
@cvindex TIME_WITH_SYS_TIME
|
|
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} or @code{struct timezone} 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
|
|
@maindex HEADER_TIOCGWINSZ
|
|
@cvindex GWINSZ_IN_SYS_IOCTL
|
|
@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, , Particular Headers, Header Files
|
|
@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})
|
|
@maindex CHECK_HEADER
|
|
If the system header file @var{header-file} exists, 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.
|
|
@end defmac
|
|
|
|
@defmac AC_CHECK_HEADERS (@var{header-file}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found})
|
|
@maindex 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.
|
|
@end defmac
|
|
|
|
@node Declarations, Structures, Header Files, Existing Tests
|
|
@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 macro (@pxref{Generic
|
|
Declarations}) or, for more complex tests, you may use
|
|
@code{AC_TRY_COMPILE} (@pxref{Examining Syntax}).
|
|
|
|
@menu
|
|
* Particular Declarations:: Macros to check for certain declarations
|
|
* Generic Declarations:: How to find other declarations
|
|
@end menu
|
|
|
|
@node Particular Declarations, Generic Declarations, Declarations, Declarations
|
|
@subsection Particular Declaration Checks
|
|
|
|
The following macros check for certain declarations.
|
|
|
|
@defmac AC_DECL_SYS_SIGLIST
|
|
@maindex DECL_SYS_SIGLIST
|
|
@cvindex SYS_SIGLIST_DECLARED
|
|
Define @code{SYS_SIGLIST_DECLARED} if the variable @code{sys_siglist}
|
|
is declared in a system header file, either @file{signal.h} or
|
|
@file{unistd.h}.
|
|
@end defmac
|
|
|
|
@node Generic Declarations, , Particular Declarations, 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}, @ovar{includes})
|
|
@maindex CHECK_DECL
|
|
If the declaration of @var{symbol} (a function or a variable) is needed
|
|
because it is not declared in @var{includes}, 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 not needed.
|
|
@end defmac
|
|
|
|
@defmac AC_CHECK_DECLS (@var{symbols}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes})
|
|
@maindex CHECK_DECLS
|
|
@cvindex HAVE_DECL_@var{symbol}
|
|
For each of the @var{symbols} (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
|
|
But if the test may have not been performed, 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
|
|
char *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, Types, Declarations, Existing Tests
|
|
@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 macro
|
|
(@pxref{Generic Structures}) or, for more complex tests, you may use
|
|
@code{AC_TRY_COMPILE} (@pxref{Examining Syntax}).
|
|
|
|
@menu
|
|
* Particular Structures:: Macros to check for certain structure members
|
|
* Generic Structures:: How to find other structure members
|
|
@end menu
|
|
|
|
@node Particular Structures, Generic Structures, Structures, Structures
|
|
@subsection Particular Structure Checks
|
|
|
|
The following macros check for certain structures or structure members.
|
|
|
|
@defmac AC_STRUCT_ST_BLKSIZE
|
|
@maindex 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
|
|
@maindex 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
|
|
@maindex 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, @code{HAVE_ST_RDEV}
|
|
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_rdev))
|
|
@end example
|
|
|
|
@end defmac
|
|
|
|
@defmac AC_STRUCT_TM
|
|
@maindex STRUCT_TM
|
|
@cvindex TM_IN_SYS_TIME
|
|
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
|
|
@maindex 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, , Particular Structures, 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}, @ovar{includes})
|
|
@maindex 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 `struct 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}, @ovar{includes})
|
|
@maindex CHECK_MEMBERS
|
|
Check for the existence of each @samp{@var{aggregate}.@var{member}} of
|
|
@var{members} using the previous macro. When @var{member} belong to
|
|
@var{aggregate}, define @code{HAVE_@var{aggregate}_@var{member}} (in all
|
|
capitals, with spaces and dot replaced by underscore).
|
|
|
|
This macro uses m4 lists:
|
|
@example
|
|
AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize])
|
|
@end example
|
|
@end defmac
|
|
|
|
|
|
@node Types, Compilers and Preprocessors, Structures, Existing Tests
|
|
@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, Generic Types, Types, Types
|
|
@subsection Particular Type Checks
|
|
|
|
These macros check for particular C types in @file{sys/types.h},
|
|
@file{stdlib.h} and others, if they exist.
|
|
|
|
@defmac AC_TYPE_GETGROUPS
|
|
@maindex 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_MODE_T
|
|
@maindex TYPE_MODE_T
|
|
@cvindex mode_t
|
|
Equivalent to @samp{AC_CHECK_TYPE(mode_t, int)}.
|
|
@end defmac
|
|
|
|
@defmac AC_TYPE_OFF_T
|
|
@maindex TYPE_OFF_T
|
|
@cvindex off_t
|
|
Equivalent to @samp{AC_CHECK_TYPE(off_t, long)}.
|
|
@end defmac
|
|
|
|
@defmac AC_TYPE_PID_T
|
|
@maindex TYPE_PID_T
|
|
@cvindex pid_t
|
|
Equivalent to @samp{AC_CHECK_TYPE(pid_t, int)}.
|
|
@end defmac
|
|
|
|
@defmac AC_TYPE_SIGNAL
|
|
@maindex TYPE_SIGNAL
|
|
@cvindex RETSIGTYPE
|
|
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
|
|
@maindex TYPE_SIZE_T
|
|
@cvindex size_t
|
|
Equivalent to @samp{AC_CHECK_TYPE(size_t, unsigned)}.
|
|
@end defmac
|
|
|
|
@defmac AC_TYPE_UID_T
|
|
@maindex 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, , Particular Types, 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}, @ovar{includes})
|
|
@maindex CHECK_TYPE
|
|
Check whether @var{type} is defined. It may be a compiler builtin type
|
|
or defined by the @ovar{includes} (@pxref{Default Includes}).
|
|
@end defmac
|
|
|
|
|
|
@defmac AC_CHECK_TYPES (@var{types}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes})
|
|
@maindex 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, C Compiler Characteristics, Types, Existing Tests
|
|
@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 CYGWIN
|
|
@ovindex EMXOS2
|
|
@ovindex MINGW32
|
|
They also set the shell variable @code{CYGWIN} to @samp{yes} if run in
|
|
the Cygwin environment, @code{EMXOS2} to @samp{yes} if in the EMX
|
|
environment on OS/2, and @code{MINGW32} to @samp{yes} with the MingW32
|
|
compiler.
|
|
|
|
@ovindex OBJEXT
|
|
Finally, they define the output variable @code{OBJEXT} based on the
|
|
output of the compiler, after .c files have been excluded, typically
|
|
to @samp{o} if Unix, @samp{obj} if Win32.
|
|
|
|
If the compiler being used does not produce executables, they 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.
|
|
|
|
@defmac AC_PROG_CC (@ovar{compiler-search-list})
|
|
@maindex 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 using the @sc{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 @sc{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
|
|
@maindex 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 @sc{gnu} Make to choose the default C compilation
|
|
rule.
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_CC_STDC
|
|
@maindex PROG_CC_STDC
|
|
@ovindex CC
|
|
If the C compiler is not in @sc{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 @sc{ansi} C on some system or another. It
|
|
considers the compiler to be in @sc{ansi} C mode if it handles function
|
|
prototypes correctly.
|
|
|
|
If you use this macro, you should check after calling it whether the C
|
|
compiler has been set to accept @sc{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 @sc{ansi} C, you can make an un-@sc{ansi}fied copy of it by
|
|
using the program @code{ansi2knr}, which comes with Automake.
|
|
@end defmac
|
|
|
|
|
|
@defmac AC_PROG_CPP
|
|
@maindex 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.
|
|
|
|
If the current language is C (@pxref{Language Choice}), many of the
|
|
specific test macros use the value of @code{CPP} indirectly by calling
|
|
@code{AC_TRY_CPP}, @code{AC_CHECK_HEADER}, @code{AC_EGREP_HEADER}, or
|
|
@code{AC_EGREP_CPP}.
|
|
|
|
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.
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_CXX (@ovar{compiler-search-list})
|
|
@maindex 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{gcc}.
|
|
|
|
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 @sc{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 @sc{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
|
|
@maindex 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.
|
|
|
|
If the current language is C++ (@pxref{Language Choice}), many of the
|
|
specific test macros use the value of @code{CXXCPP} indirectly by
|
|
calling @code{AC_TRY_CPP}, @code{AC_CHECK_HEADER},
|
|
@code{AC_EGREP_HEADER}, or @code{AC_EGREP_CPP}.
|
|
|
|
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
|
|
|
|
@defmac AC_PROG_F77 (@ovar{compiler-search-list})
|
|
@maindex PROG_FORTRAN
|
|
@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 cf77 g77 f90 xlf90)
|
|
@end example
|
|
|
|
If using @code{g77} (the @sc{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_F77_C_O
|
|
@maindex PROG_F77_C_O
|
|
@cvindex F77_NO_MINUS_C_MINUS_O
|
|
Test if the Fortran 77 compiler accepts the options @option{-c} and
|
|
@option{-o} simultaneously, and define @code{F77_NO_MINUS_C_MINUS_O} if it
|
|
does not.
|
|
@end defmac
|
|
|
|
@defmac AC_PROG_GCC_TRADITIONAL
|
|
@maindex PROG_GCC_TRADITIONAL
|
|
@ovindex CC
|
|
Add @option{-traditional} to output variable @code{CC} if using the
|
|
@sc{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
|
|
@sc{gnu} C compiler fix the header files automatically when installed,
|
|
this is becoming a less prevalent problem.
|
|
@end defmac
|
|
|
|
|
|
@node C Compiler Characteristics, Fortran 77 Compiler Characteristics, Compilers and Preprocessors, Existing Tests
|
|
@section C Compiler Characteristics
|
|
|
|
The following macros check for C compiler or machine architecture
|
|
features. To check for characteristics not listed here, use
|
|
@code{AC_TRY_COMPILE} (@pxref{Examining Syntax}) or @code{AC_TRY_RUN}
|
|
(@pxref{Run Time})
|
|
|
|
@defmac AC_C_BIGENDIAN
|
|
@maindex C_BIGENDIAN
|
|
@cvindex WORDS_BIGENDIAN
|
|
@cindex Endianness
|
|
If words are stored with the most significant byte first (like Motorola
|
|
and SPARC, but not Intel and VAX, CPUs), define @code{WORDS_BIGENDIAN}.
|
|
@end defmac
|
|
|
|
|
|
@defmac AC_C_CONST
|
|
@maindex C_CONST
|
|
@cvindex const
|
|
If the C compiler does not fully support the @sc{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 @code{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_VOLATILE
|
|
@maindex 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 @sc{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 defined @code{__STDC__}.
|
|
@end defmac
|
|
|
|
@defmac AC_C_INLINE
|
|
@maindex 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
|
|
@maindex 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
|
|
@maindex C_LONG_DOUBLE
|
|
@cvindex HAVE_LONG_DOUBLE
|
|
If the C compiler supports the @code{long double} type, define
|
|
@code{HAVE_LONG_DOUBLE}. Some C compilers that do not define
|
|
@code{__STDC__} do support the @code{long double} type; some compilers
|
|
that define @code{__STDC__} do not support @code{long double}.
|
|
@end defmac
|
|
|
|
@defmac AC_C_STRINGIZE
|
|
@maindex 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
|
|
@maindex C_PROTOTYPES
|
|
@cvindex PROTOTYPES
|
|
@cvindex PARAMS
|
|
Check to see if function prototypes are understood by the compiler. If
|
|
so, define @samp{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
|
|
|
|
@c FIXME: What the heck is this macro doing here? Move it out of
|
|
@c the way, in its proper section!!!
|
|
@defmac AC_CHECK_SIZEOF (@var{type}, @ovar{unused}, @ovar{includes})
|
|
@maindex 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}, make 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
|
|
|
|
|
|
|
|
@node Fortran 77 Compiler Characteristics, System Services, C Compiler Characteristics, Existing Tests
|
|
@section Fortran 77 Compiler Characteristics
|
|
|
|
The following macros check for Fortran 77 compiler characteristics. To
|
|
check for characteristics not listed here, use @code{AC_TRY_COMPILE}
|
|
(@pxref{Examining Syntax}) or @code{AC_TRY_RUN} (@pxref{Run Time}),
|
|
making sure to first set the current language to Fortran 77
|
|
@code{AC_LANG_FORTRAN77} (@pxref{Language Choice}).
|
|
|
|
@defmac AC_F77_LIBRARY_LDFLAGS
|
|
@maindex F77_LIBRARY_LDFLAGS
|
|
@ovindex FLIBS
|
|
Determine the linker flags (e.g. @option{-L} and @option{-l}) for the
|
|
@dfn{Fortran 77 intrinsic and run-time libraries} that are required to
|
|
successfully link a Fortran 77 program or shared library. The output
|
|
variable @code{FLIBS} is set to these flags.
|
|
|
|
This macro is intended to be used in those situations when it is
|
|
necessary to mix, e.g. C++ and Fortran 77 source code into a single
|
|
program or shared library (@pxref{Mixing Fortran 77 With C and C++,,,
|
|
automake, GNU Automake}).
|
|
|
|
For example, if object files from a C++ and Fortran 77 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 77 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, the macro
|
|
@code{AC_F77_LIBRARY_LDFLAGS} was created to determine these Fortran 77
|
|
libraries.
|
|
@end defmac
|
|
|
|
@defmac AC_F77_WRAPPERS
|
|
@maindex F77_WRAPPERS
|
|
@cvindex F77_FUNC
|
|
@cvindex F77_FUNC_
|
|
Defines C macros @code{F77_FUNC(name,NAME)} and
|
|
@code{F77_FUNC_(name,NAME)} to properly mangle the names of C
|
|
identifiers, and C identifiers with underscores, respectively, so that
|
|
they match the name mangling scheme used by the Fortran 77 compiler.
|
|
|
|
Fortran 77 is case-insensitive, and in order to achieve this the Fortran
|
|
77 compiler converts all identifiers into a canonical case and format.
|
|
To call a Fortran 77 subroutine from C or to write a C function that is
|
|
callable from Fortran 77, the C program must explicitly use identifiers
|
|
in the format expected by the Fortran 77 compiler. In order to do this,
|
|
one simply wraps all C identifiers in one of the macros provided by
|
|
@code{AC_F77_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 as:
|
|
|
|
@example
|
|
#ifdef F77_FUNC
|
|
# define FOOBAR_F77 F77_FUNC(foobar,FOOBAR)
|
|
#endif
|
|
#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, GNU
|
|
Automake}).
|
|
|
|
Although Autoconf tries to be intelligent about detecting the
|
|
name-mangling scheme of the Fortran 77 compiler, there may be Fortran 77
|
|
compilers that it doesn't support yet. It is therefore recommended that
|
|
you test whether the @code{F77_FUNC} and @code{F77_FUNC_} macros are
|
|
defined, as we have done in the example above.
|
|
|
|
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 77 identifier contains an underscore
|
|
(e.g. @code{foo_bar}), you should use @code{F77_FUNC_} instead of
|
|
@code{F77_FUNC} (with the same arguments). This is because some Fortran
|
|
77 compilers mangle names differently if they contain an underscore.
|
|
@end defmac
|
|
|
|
@defmac AC_F77_FUNC (@var{name}, @ovar{shellvar})
|
|
@maindex F77_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 77 linker (see also @code{AC_F77_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
|
|
|
|
@node System Services, UNIX Variants, Fortran 77 Compiler Characteristics, Existing Tests
|
|
@section System Services
|
|
|
|
The following macros check for operating system services or capabilities.
|
|
|
|
@defmac AC_PATH_X
|
|
@maindex 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 them 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
|
|
@maindex PATH_XTRA
|
|
@ovindex X_CFLAGS
|
|
@ovindex X_LIBS
|
|
@ovindex X_EXTRA_LIBS
|
|
@ovindex X_PRE_LIBS
|
|
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}. If X is not available, adds @option{-DX_DISPLAY_MISSING} to
|
|
@code{X_CFLAGS}.
|
|
|
|
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
|
|
@maindex 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 @code{configure.in} 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
|
|
@maindex SYS_LARGEFILE
|
|
@cvindex _FILE_OFFSET_BITS
|
|
@cvindex _LARGEFILE_SOURCE
|
|
@cvindex _LARGE_FILES
|
|
@cvindex _XOPEN_SOURCE
|
|
@ovindex CC
|
|
Arrange for
|
|
@uref{http://www.sas.com/standards/large.file/x_open.20Mar96.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}, @code{_LARGEFILE_SOURCE}, @code{_LARGE_FILES},
|
|
and @code{_XOPEN_SOURCE} if necessary.
|
|
|
|
The user can disable large-file support 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)}.
|
|
@end defmac
|
|
|
|
@defmac AC_SYS_LONG_FILE_NAMES
|
|
@maindex 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
|
|
@maindex SYS_POSIX_TERMIOS
|
|
@cindex POSIX termios headers
|
|
@cindex termios POSIX headers
|
|
Check to see if POSIX termios headers and functions are available on the
|
|
system. If so, set the shell variable @code{am_cv_sys_posix_termios} to
|
|
@samp{yes}. If not, set the variable to @samp{no}.
|
|
@end defmac
|
|
|
|
@defmac AC_SYS_RESTARTABLE_SYSCALLS
|
|
@maindex 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.
|
|
@end defmac
|
|
|
|
@node UNIX Variants, , System Services, Existing Tests
|
|
@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
|
|
@maindex AIX
|
|
@cvindex _ALL_SOURCE
|
|
If on AIX, define @code{_ALL_SOURCE}. Allows the use of some @sc{bsd}
|
|
functions. Should be called before any macros that run the C compiler.
|
|
@end defmac
|
|
|
|
@defmac AC_ISC_POSIX
|
|
@maindex ISC_POSIX
|
|
@cvindex _POSIX_SOURCE
|
|
@ovindex CC
|
|
If on a POSIXized ISC @sc{unix}, define @code{_POSIX_SOURCE} and add
|
|
@option{-posix} (for the @sc{gnu} C compiler) or @option{-Xp} (for other C
|
|
compilers) to output variable @code{CC}. This allows the use of
|
|
@sc{posix} facilities. Must be called after @code{AC_PROG_CC} and
|
|
before any other macros that run the C compiler.
|
|
@end defmac
|
|
|
|
@defmac AC_MINIX
|
|
@maindex 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 @sc{posix}
|
|
facilities. Should be called before any macros that run the C compiler.
|
|
@end defmac
|
|
|
|
|
|
|
|
|
|
@c ========================================================= Writing Tests
|
|
|
|
@node Writing Tests, Results, Existing Tests, Top
|
|
@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 C compiler system. 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 C
|
|
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 Macros}, for how to do that.
|
|
|
|
@menu
|
|
* Examining Declarations:: Detecting header files and declarations
|
|
* Examining Syntax:: Detecting language syntax features
|
|
* Examining Libraries:: Detecting functions and global variables
|
|
* Run Time:: Testing for run-time features
|
|
* Portable Shell:: Shell script portability pitfalls
|
|
* Multiple Cases:: Tests for several possible values
|
|
* Language Choice:: Selecting which language to use for testing
|
|
@end menu
|
|
|
|
@node Examining Declarations, Examining Syntax, Writing Tests, Writing Tests
|
|
@section Examining Declarations
|
|
|
|
The macro @code{AC_TRY_CPP} is used to check whether particular header
|
|
files exist. You can check for one at a time, or more than one if you
|
|
need several header files to all exist for some purpose.
|
|
|
|
@defmac AC_TRY_CPP (@var{includes}, @ovar{action-if-true}, @ovar{action-if-false})
|
|
@maindex TRY_CPP
|
|
@var{includes} is C or C++ @code{#include} statements and declarations,
|
|
on which shell variable, back quote, and backslash substitutions are
|
|
performed. (Actually, it can be any C program, but other statements are
|
|
probably not useful.) If the preprocessor produces no error messages
|
|
while processing it, run shell commands @var{action-if-true}. Otherwise
|
|
run shell commands @var{action-if-false}.
|
|
|
|
This macro uses @code{CPPFLAGS}, but not @code{CFLAGS}, because
|
|
@option{-g}, @option{-O}, etc. are not valid options to many C
|
|
preprocessors.
|
|
@end defmac
|
|
|
|
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.
|
|
|
|
@defmac AC_EGREP_HEADER (@var{pattern}, @var{header-file}, @var{action-if-found}, @ovar{action-if-not-found})
|
|
@maindex EGREP_HEADER
|
|
If the output of running the preprocessor on the system header file
|
|
@var{header-file} matches the @code{egrep} regular expression
|
|
@var{pattern}, execute shell commands @var{action-if-found}, otherwise
|
|
execute @var{action-if-not-found}.
|
|
@end defmac
|
|
|
|
To check for C preprocessor symbols, either defined by header files or
|
|
predefined by the C preprocessor, use @code{AC_EGREP_CPP}. Here is an
|
|
example of the latter:
|
|
|
|
@example
|
|
AC_EGREP_CPP(yes,
|
|
[#ifdef _AIX
|
|
yes
|
|
#endif
|
|
], is_aix=yes, is_aix=no)
|
|
@end example
|
|
|
|
@defmac AC_EGREP_CPP (@var{pattern}, @var{program}, @ovar{action-if-found}, @ovar{action-if-not-found})
|
|
@maindex 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
|
|
@code{egrep} regular expression @var{pattern}, execute shell commands
|
|
@var{action-if-found}, otherwise execute @var{action-if-not-found}.
|
|
|
|
This macro calls @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP} (depending
|
|
on which language is current, @pxref{Language Choice}), if it hasn't
|
|
been called already.
|
|
@end defmac
|
|
|
|
@node Examining Syntax, Examining Libraries, Examining Declarations, Writing Tests
|
|
@section Examining Syntax
|
|
|
|
To check for a syntax feature of the C, C++ or Fortran 77 compiler, such
|
|
as whether it recognizes a certain keyword, use @code{AC_TRY_COMPILE} to
|
|
try to compile a small program that uses that feature. You can also use
|
|
it to check for structures and structure members that are not present on
|
|
all systems.
|
|
|
|
@defmac AC_TRY_COMPILE (@var{includes}, @var{function-body}, @ovar{action-if-found}, @ovar{action-if-not-found})
|
|
@maindex TRY_COMPILE
|
|
Create a C, C++ or Fortran 77 test program (depending on which language
|
|
is current, @pxref{Language Choice}), to see whether a function whose
|
|
body consists of @var{function-body} can be compiled.
|
|
|
|
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 77). This macro also uses
|
|
@code{CFLAGS} or @code{CXXFLAGS} if either C or C++ is the currently
|
|
selected language, as well as @code{CPPFLAGS}, when compiling. If
|
|
Fortran 77 is the currently selected language then @code{FFLAGS} will be
|
|
used when compiling.
|
|
|
|
If the file compiles successfully, run shell commands
|
|
@var{action-if-found}, otherwise run @var{action-if-not-found}.
|
|
|
|
This macro does not try to link; use @code{AC_TRY_LINK} if you need to
|
|
do that (@pxref{Examining Libraries}).
|
|
@end defmac
|
|
|
|
@node Examining Libraries, Run Time, Examining Syntax, Writing Tests
|
|
@section Examining Libraries
|
|
|
|
To check for a library, a function, or a global variable, Autoconf
|
|
@code{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 runtime behavior if needed. On the other hand, it
|
|
can be slower than scanning the libraries once.
|
|
|
|
A few systems have linkers that do not return a failure exit status when
|
|
there are unresolved functions in the link. This bug makes the
|
|
configuration scripts produced by Autoconf unusable on those systems.
|
|
However, some of them can be given options that make the exit status
|
|
correct. This is a problem that Autoconf does not currently handle
|
|
automatically. If users encounter this problem, they might be able to
|
|
solve it by setting @code{LDFLAGS} in the environment to pass whatever
|
|
options the linker needs (for example, @option{-Wl,-dn} on @sc{mips
|
|
risc/os}).
|
|
|
|
@code{AC_TRY_LINK} 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_TRY_LINK (@var{includes}, @var{function-body}, @ovar{action-if-found}, @ovar{action-if-not-found})
|
|
@maindex TRY_LINK
|
|
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.
|
|
|
|
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 77). This macro also uses
|
|
@code{CFLAGS} or @code{CXXFLAGS} if either C or C++ is the currently
|
|
selected language, as well as @code{CPPFLAGS}, when compiling. If
|
|
Fortran 77 is the currently selected language then @code{FFLAGS} will be
|
|
used when compiling. However, both @code{LDFLAGS} and @code{LIBS} will
|
|
be used during linking in all cases.
|
|
|
|
If the file compiles and links successfully, run shell commands
|
|
@var{action-if-found}, otherwise run @var{action-if-not-found}.
|
|
@end defmac
|
|
|
|
@defmac AC_TRY_LINK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found})
|
|
@maindex TRY_LINK_FUNC
|
|
Depending on the current language (@pxref{Language Choice}), create a
|
|
test program to see whether a program whose body consists of
|
|
a prototype of and a call to @var{function} 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}.
|
|
@end defmac
|
|
|
|
|
|
|
|
@node Run Time, Portable Shell, Examining Libraries, Writing Tests
|
|
@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_TRY_RUN}. Avoid running test programs if
|
|
possible, because using them prevents people from configuring your
|
|
package for cross-compiling.
|
|
|
|
@menu
|
|
* Test Programs:: Running test programs
|
|
* Guidelines:: General rules for writing test programs
|
|
* Test Functions:: Avoiding pitfalls in test programs
|
|
@end menu
|
|
|
|
@node Test Programs, Guidelines, Run Time, Run Time
|
|
@subsection Running Test Programs
|
|
|
|
Use the following macro if you need to test run-time behavior of the
|
|
system while configuring.
|
|
|
|
@defmac AC_TRY_RUN (@var{program}, @ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-cross-compiling})
|
|
@maindex TRY_RUN
|
|
@var{program} is the text of a C program, on which shell variable and
|
|
back quote substitutions are performed. If it 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 exit status of the program is available in
|
|
the shell variable @samp{$?}. This macro uses @code{CFLAGS} or
|
|
@code{CXXFLAGS}, @code{CPPFLAGS}, @code{LDFLAGS}, and @code{LIBS} when
|
|
compiling.
|
|
|
|
If the C compiler being used does not produce executables that run on
|
|
the system where @code{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, @code{configure} prints
|
|
an error message and exits.
|
|
@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_TRY_RUN}. @code{autoconf} prints a warning
|
|
message when creating @code{configure} each time it encounters a call to
|
|
@code{AC_TRY_RUN} 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_TRY_RUN} that are embedded in
|
|
other macros, including a few of the ones that come with Autoconf, you
|
|
can call @code{AC_PROG_CC} before running them. Then, if the shell
|
|
variable @code{cross_compiling} is set to @samp{yes}, use an alternate
|
|
method to get the results instead of calling the macros.
|
|
|
|
|
|
@node Guidelines, Test Functions, Test Programs, Run Time
|
|
@subsection Guidelines for Test Programs
|
|
|
|
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.in} you can have a test program that includes an
|
|
@sc{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{conftestdata}. The
|
|
@code{configure} script cleans up by running @samp{rm -rf conftest*}
|
|
after running test programs and if the script is interrupted.
|
|
|
|
@node Test Functions, , Guidelines, Run Time
|
|
@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
|
|
char *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, make 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 Portable Shell, Multiple Cases, Run Time, Writing Tests
|
|
@section 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 Bash and the Korn shell
|
|
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. 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@sc{bsd} based systems
|
|
(such as Sequent DYNIX) will ignore the line, because they interpret
|
|
@samp{#! /} as a 4-byte magic number.
|
|
|
|
The set of external programs you should run in a @code{configure} script
|
|
is fairly small. @xref{Utilities in Makefiles,, Utilities in
|
|
Makefiles, standards, 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}.
|
|
|
|
@menu
|
|
* Shellology:: A zoology of shells
|
|
* Special Shell Variables:: Variables you should not change
|
|
* Shell Substitutions:: Test and assign
|
|
* Limitations of Builtins:: Portable use of not so portable /bin/sh
|
|
* Limitations of Usual Tools:: Portable use of portable tools
|
|
@end menu
|
|
|
|
@node Shellology, Special Shell Variables, Portable Shell, Portable Shell
|
|
@subsection 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.
|
|
|
|
Below we describe some of the members of the Bourne shell family.
|
|
|
|
@table @asis
|
|
@item @command{bash}
|
|
@cindex @command{bash}
|
|
To detect whether you are running @command{bash}, test if
|
|
@code{BASH_VERSION} is set. To disable its extensions and require
|
|
@sc{posix} compatibility, run @samp{set -o posix}. @xref{Bash POSIX
|
|
Mode,, Bash @sc{posix} Mode, bash, The GNU Bash Reference Manual}, for
|
|
details.
|
|
|
|
@item @command{zsh}
|
|
@cindex @command{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.
|
|
|
|
@item @command{ash}
|
|
@cindex @command{ash}
|
|
@command{ash} is often used on @sc{gnu}/Linux and @sc{bsd} systems as a
|
|
light-weight Bourne-compatible shell. @command{ash} version 0.2 has
|
|
some bugs that are fixed in the 0.3.x series, but portable shell scripts
|
|
should workaround them, since version 0.2 is still shipped with many
|
|
@sc{gnu}/Linux distributions.
|
|
|
|
To be compatible with @command{ash} 0.2
|
|
|
|
@itemize @bullet
|
|
@item
|
|
don't rely on variable assignment setting @samp{$?} unless the
|
|
assignment involves command substitution:
|
|
|
|
@example
|
|
false || foo=bar && echo "Not portable"
|
|
false || foo=`bar` && echo "Portable"
|
|
@end example
|
|
|
|
@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
|
|
echo $@{FOO=`bar`@}
|
|
@end example
|
|
|
|
@item
|
|
beware that @command{exit} inside command substitution causes the
|
|
current shell exit as well. Use parentheses to prevent @command{ash}
|
|
from exiting:
|
|
|
|
@example
|
|
(`exit 1`) || echo "All right"
|
|
`exit 1` || echo "ash won't print it"
|
|
@end example
|
|
|
|
@end itemize
|
|
@end table
|
|
|
|
|
|
@node Special Shell Variables, Shell Substitutions, Shellology, Portable Shell
|
|
@subsection Special Shell Variables
|
|
|
|
Some shell variables shall not be used or 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 fall back value is
|
|
needed. We list these values below.
|
|
|
|
@c Alphabetical order, case insensitive, `A' before `a'.
|
|
@table @code
|
|
@item CDPATH
|
|
@evindex CDPATH
|
|
Because when this variable is set @code{cd} is verbose, idioms such as
|
|
@samp{abs=`cd $rel && pwd`} break, since @code{abs} receives twice the
|
|
path.
|
|
|
|
@c FIXME: Which shells? How do they behave?
|
|
Setting @code{CDPATH} to the empty value is not enough for most shells.
|
|
A simple colon is enough but for @code{zsh}, which prefers a leading dot:
|
|
|
|
@example
|
|
zsh-3.1.6 % mkdir foo && (CDPATH=: cd foo)
|
|
/tmp/foo
|
|
zsh-3.1.6 % (CDPATH=:. cd foo)
|
|
/tmp/foo
|
|
zsh-3.1.6 % (CDPATH=.: cd foo)
|
|
zsh-3.1.6 %
|
|
@end example
|
|
|
|
@noindent
|
|
(of course we could just @code{unset} @code{CDPATH}, it also behaves
|
|
properly if set to the empty string).
|
|
|
|
Life wouldn't be so much fun if @command{bash} and @command{zsh} had the
|
|
same behavior:
|
|
|
|
@example
|
|
bash-2.02 % (CDPATH=:. cd foo)
|
|
bash-2.02 % (CDPATH=.: cd foo)
|
|
/tmp/foo
|
|
@end example
|
|
|
|
Therefore a portable solution to neutralize @samp{CDPATH} is
|
|
@samp{CDPATH=$@{ZSH_VERSION+.@}:}. Note that since @command{zsh}
|
|
support @command{unset}, you may unset @samp{CDPATH} using @samp{:} as a
|
|
fall back, see @ref{Limitations of Builtins}.
|
|
|
|
@item LANG
|
|
@itemx LC_ALL
|
|
@itemx LC_TIME
|
|
@itemx LC_CTYPE
|
|
@itemx LANGUAGE
|
|
@itemx LC_COLLATE
|
|
@itemx LC_NUMERIC
|
|
@itemx LC_MESSAGES
|
|
@evindex LANG
|
|
@evindex LC_ALL
|
|
@evindex LC_TIME
|
|
@evindex LC_CTYPE
|
|
@evindex LANGUAGE
|
|
@evindex LC_COLLATE
|
|
@evindex LC_NUMERIC
|
|
@evindex LC_MESSAGES
|
|
|
|
These must not be set unconditionally because not all systems understand
|
|
e.g. @samp{LANG=C} (notably SCO). Fixing @env{LC_MESSAGES} prevents
|
|
Solaris @command{sh} from translating var values in @code{set}! Non-C
|
|
@env{LC_CTYPE} values break the ctype check. Fixing @env{LC_COLLATE}
|
|
makes scripts more portable in some cases. For example, it causes the
|
|
regular expression @samp{[a-z]} to match only lower-case letters on
|
|
@sc{ascii} platforms. However, @samp{[a-z]} does not work in general
|
|
even when @env{LC_COLLATE} is fixed; for example, it does not work for
|
|
@sc{ebcdic} platforms. For maximum portability, you should use regular
|
|
expressions like @samp{[abcdefghijklmnopqrstuvwxyz]} that list
|
|
characters explicitly instead of relying on ranges.
|
|
|
|
@emph{If} one of these variables is set, you should try to unset it,
|
|
using @samp{C} as a fall back value. see @ref{Limitations of Builtins},
|
|
builtin @command{unset}, for more details.
|
|
|
|
@item NULLCMD
|
|
@evindex NULLCMD
|
|
When executing the command @samp{>foo}, @command{zsh} executes
|
|
@samp{$NULLCMD >foo}. The Bourne shell considers @code{NULLCMD} is
|
|
@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 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.
|
|
@end table
|
|
|
|
|
|
@node Shell Substitutions, Limitations of Builtins, Special Shell Variables, Portable Shell
|
|
@subsection Shell Substitutions
|
|
|
|
A nonportable shell programming construct is
|
|
|
|
@example
|
|
@var{var}=$@{@var{var}:-@var{value}@}
|
|
@end example
|
|
|
|
@noindent
|
|
The intent is to set @var{var} to @var{value} only if it is not already
|
|
set, but if @var{var} has any value, even the empty string, to leave it
|
|
alone. Old @sc{bsd} shells, including the Ultrix @code{sh}, don't
|
|
accept the colon for any shell substitution, and complain and die. A
|
|
portable equivalent is
|
|
|
|
@example
|
|
: $@{@var{var}=@var{value}@}
|
|
@end example
|
|
|
|
If the value is a literal string, it should be quoted:
|
|
|
|
@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''.
|
|
|
|
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}.
|
|
|
|
@cindex @samp{"$@@"}
|
|
One of the most famous shell portability issues is related to
|
|
@samp{"$@@"}: when there are no positional argument, it is supposed to
|
|
be equivalent to nothing. But some shell, for instance under Digital
|
|
Unix 4.0 and 5.0, will then replace it with an empty argument. To be
|
|
portable, use @samp{$@{1+"$@@"@}}.
|
|
|
|
Contrary to a persistent urban legend, the Bourne shell does not
|
|
systematically split variables and backquoted expressions, in
|
|
particular, 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 with the right-hand side of the assignments, and the
|
|
argument of @code{case} left without quotes:
|
|
|
|
@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 the shells understand properly @samp{"`... "foo"... `"}.
|
|
Worse yet, not all the shells understand @samp{"`... \"foo\"... `"} the
|
|
same way: there is just no portable way to use double-quoted strings
|
|
inside double-quoted backquoted expressions (Pfew!).
|
|
|
|
@node Limitations of Builtins, Limitations of Usual Tools, Shell Substitutions, Portable Shell
|
|
@subsection Limitations of Shell Builtins
|
|
|
|
No no, we are serious: some shells do have limitations :)
|
|
|
|
You should always keep in mind that any built-in 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{!}
|
|
@cindex @command{!}
|
|
You can't use @command{!}, you'll have to rewrite your code.
|
|
|
|
@item @command{break}
|
|
@cindex @command{break}
|
|
The use of @samp{break 2} etc. is safe.
|
|
|
|
@item @command{case}
|
|
@cindex @command{case}
|
|
You don't need to quote the argument, no splitting is performed.
|
|
|
|
You don't need the last @samp{;;}, but you should use it.
|
|
|
|
Because of a bug in its @code{fnmatch}, @command{bash} fails to handle
|
|
properly backslashes in character classes:
|
|
|
|
@example
|
|
bash-2.02$ 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 workaround this bug,
|
|
always put the backslash first:
|
|
|
|
@example
|
|
bash-2.02$ case '\TMP' in [\\/]*) echo OK;; esac
|
|
OK
|
|
bash-2.02$ case /tmp in [\\/]*) echo OK;; esac
|
|
OK
|
|
@end example
|
|
|
|
@item @command{echo}
|
|
@cindex @command{echo}
|
|
The simple @code{echo} is probably the most surprising source of
|
|
portability troubles.
|
|
|
|
Don't expect any option. @xref{Preset Output Variables}, @code{ECHO_N}
|
|
etc. for a means to simulate @option{-c}.
|
|
|
|
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,
|
|
@sc{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 n.
|
|
|
|
@item @command{exit}
|
|
@cindex @command{exit}
|
|
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 status. In these shells, a trap
|
|
cannot determine whether it was invoked by plain @code{exit} or by
|
|
@code{exit 1}. To work around this problem, use @code{(exit 1); exit}
|
|
instead of @samp{exit 1}.
|
|
|
|
@item @command{export}
|
|
@cindex @command{export}
|
|
The builtin @command{export} dubs @dfn{environment variable} a shell
|
|
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, pretty many shells, such as Solaris 2.5, IRIX 6.3, IRIX 5.2, AIX
|
|
4.1.5 and DU 4.0 forget to @command{export} the environment variables
|
|
they receive. As a result two variables are coexisting: 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
|
|
you update.
|
|
|
|
@item @command{if}
|
|
@cindex @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
|
|
|
|
@item @command{set}
|
|
@cindex @command{set}
|
|
This builtin faces the usual problem with arguments starting with a
|
|
dash. Modern shells, such as Bash or Zsh understand @samp{--} to
|
|
specify the end of the options (any argument behind @samp{--} is an
|
|
parameters, even @samp{-x} for instance), but most shell simply stop the
|
|
option processing as soon as a non option argument is found. Therefore
|
|
use @samp{dummy} or simply @samp{x} to neutralize the option processing,
|
|
and use @command{shift} to pop it out:
|
|
|
|
@example
|
|
set x $my_list; shift
|
|
@end example
|
|
|
|
@item @command{shift}
|
|
@cindex @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 @sc{mips
|
|
risc/os} 4.52 refuses it.
|
|
|
|
@item @command{test}
|
|
@cindex @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, @sc{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)
|
|
To enable @code{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 @sc{4.3bsd} does not
|
|
have it. Do not use @samp{test -e} either, because Solaris 2.5 does not
|
|
have it.
|
|
|
|
@item @command{test} (strings)
|
|
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, AIX 3.2, UNICOS 10.0.0.6, Digital Unix 4 etc.) have
|
|
bizarre precedence and may be confused if @var{string} looks like an
|
|
operator:
|
|
|
|
@example
|
|
$ 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 frequent 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
|
|
are always avoidable, and should always be. Rather, use:
|
|
|
|
@example
|
|
echo "$ac_feature" | grep '[^-a-zA-Z0-9_]' >/dev/null 2>&1 &&
|
|
@var{action}
|
|
@end example
|
|
|
|
@noindent
|
|
Where possible, use @code{case} since, being a shell builtin, it is
|
|
faster:
|
|
|
|
@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 not to support the @sc{posix.2} syntax @samp{[!...]}
|
|
(when in interactive mode, @command{zsh} is confused by the
|
|
@samp{[!...]} syntax and looks for an event in its history because of
|
|
@samp{!}). Many shells do not support the alternative syntax
|
|
@samp{[^...]} (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{unset}
|
|
@cindex @command{unset}
|
|
You cannot assume the support of @command{unset}, nevertheless, because
|
|
it is extremely useful to disable embarrassing variables such as
|
|
@code{CDPATH} or @code{LANG}, 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 CDPATH || CDPATH=:
|
|
@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, , Limitations of Builtins, Portable Shell
|
|
@subsection Limitations of Usual Tools
|
|
|
|
The small set of tools you can expect to find on any machine can still
|
|
find some limitations you should be aware of.
|
|
|
|
@table @asis
|
|
@item @command{awk}
|
|
@cindex @command{awk}
|
|
Don't leave white spaces before the parentheses in user functions calls,
|
|
@sc{gnu} awk will reject it:
|
|
|
|
@example
|
|
$ gawk 'function die () @{ print "Aaaaarg!" @}
|
|
BEGIN @{ die () @}'
|
|
gawk: cmd. line:2: BEGIN @{ die () @}
|
|
gawk: cmd. line:2: ^ parse error
|
|
$ gawk 'function die () @{ print "Aaaaarg!" @}
|
|
BEGIN @{ die() @}'
|
|
Aaaaarg!
|
|
@end example
|
|
|
|
@item @command{cat}
|
|
@cindex @command{cat}
|
|
Don't rely on any option.
|
|
|
|
@item @command{egrep}
|
|
@cindex @command{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}
|
|
@cindex @command{expr}
|
|
No @command{expr} keyword starts with @samp{x}, so use @samp{expr
|
|
x"@var{word}" : '@var{regex}'} to keep @command{expr} from
|
|
misinterpreting @var{word}.
|
|
|
|
You can use @samp{|}. There is one portability problem occuring when
|
|
you @samp{|} together the empty string (or zero) with the empty string.
|
|
For example:
|
|
|
|
@example
|
|
expr '' \| ''
|
|
@end example
|
|
|
|
@sc{gnu}/Linux and @sc{posix.2} return the empty string for this case,
|
|
but traditional Unix returns @samp{0}. In the latest @sc{posix} draft,
|
|
the specification has been changed to match traditional Unix's behavior
|
|
(which is bizarre, but it's too late to fix this).
|
|
|
|
Avoid this portability problem by avoiding the empty string.
|
|
|
|
Don't use @code{length}, @code{substr}, @code{match} and @code{index}.
|
|
|
|
@item @command{expr} (@samp{:})
|
|
@cindex @command{expr}
|
|
Don't use @samp{\?}, @samp{\+} and @samp{\|} in patterns, they are
|
|
not supported on Solaris.
|
|
|
|
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.
|
|
|
|
|
|
@item @command{grep}
|
|
@cindex @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 (eg., IRIX 6.5 and Solaris 2.5.1). Anyway,
|
|
Stardent Vistra SVR4 @code{grep} lacks @option{-e}... Instead, use
|
|
alternation and @code{egrep}.
|
|
|
|
@item @command{ln}
|
|
@cindex @command{ln}
|
|
Don't rely on @command{ln} having a @option{-f} option. Symbolic links
|
|
are not available on old systems, use @samp{ln} as a fall back.
|
|
|
|
The @sc{djgpp} @command{ln} emulates soft links for 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
|
|
src dst} will generate @file{src.exe} which will attempt to call
|
|
@file{dst.exe}. But this feature only works for executables, therefore,
|
|
don't rely on symbolic links on @sc{djgpp}.
|
|
|
|
@item @command{sed}
|
|
@cindex @command{sed}
|
|
Of course the option @option{-e} is portable, but it is not needed. No
|
|
valid @command{sed} program can start with a dash, so it does not help
|
|
disambiguating. Its sole usefulness is helping enforcing indenting 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
|
|
|
|
@command{sed} scripts should not use branch labels longer than 8
|
|
characters and should not contain comments.
|
|
|
|
@command{sed} input should have reasonably long lines, since some
|
|
@command{sed} have an input buffer limited to 4000 bytes.
|
|
|
|
Alternation, @samp{\|}, is common but not portable.
|
|
|
|
Nested groups are extremely portable, but there is at least one
|
|
@command{sed} (System V/68 Base Operating System R3V7.1) that does not
|
|
support it.
|
|
|
|
Anchors (@samp{^} and @samp{$}) inside groups are not portable.
|
|
@c FIXME: I know Solaris is guilty, but I don't remember how.
|
|
|
|
|
|
@item @command{sed} (@samp{t})
|
|
@cindex @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 @sc{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 remind 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
|
|
indeed.
|
|
|
|
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
|
|
@end table
|
|
|
|
|
|
@node Multiple Cases, Language Choice, Portable Shell, Writing Tests
|
|
@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_TRY_CPP([#include <sys/statvfs.h>
|
|
#include <sys/fstyp.h>],
|
|
[AC_DEFINE(FSTYPE_STATVFS) fstype=SVR4])
|
|
if test $fstype = no; then
|
|
AC_TRY_CPP([#include <sys/statfs.h>
|
|
#include <sys/fstyp.h>],
|
|
[AC_DEFINE(FSTYPE_USG_STATFS) fstype=SVR3])
|
|
fi
|
|
if test $fstype = no; then
|
|
AC_TRY_CPP([#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
|
|
|
|
@node Language Choice, , Multiple Cases, Writing Tests
|
|
@section Language Choice
|
|
@cindex Language
|
|
|
|
Packages that use both C and C++ need to test features of both
|
|
compilers. Autoconf-generated @code{configure} scripts check for C
|
|
features by default. The following macros determine which language's
|
|
compiler is used in tests that follow in @file{configure.in}.
|
|
|
|
@defmac AC_LANG (@var{language})
|
|
Do compilation tests using the compiler, preprocessor and file
|
|
extensions for the @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.
|
|
|
|
@item C++
|
|
Do compilation tests using @code{CXX} and @code{CXXCPP} and use
|
|
extension @file{.C} for test programs.
|
|
|
|
@item Fortran 77
|
|
Do compilation tests using @code{F77} and use extension @file{.f} for
|
|
test programs.
|
|
@end table
|
|
@end defmac
|
|
|
|
@defmac AC_LANG_PUSH (@var{language})
|
|
@maindex 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
|
|
@maindex 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.
|
|
@end defmac
|
|
|
|
@defmac AC_REQUIRE_CPP
|
|
@maindex 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
|
|
|
|
|
|
@c ====================================================== Results of Tests.
|
|
|
|
@node Results, Writing Macros, Writing Tests, Top
|
|
@chapter Results of Tests
|
|
|
|
Once @code{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 @code{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 @code{configure} runs
|
|
* Printing Messages:: Notifying @code{configure} users
|
|
@end menu
|
|
|
|
@node Defining Symbols, Setting Output Variables, Results, Results
|
|
@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
|
|
@code{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}, @ovar{value}, @ovar{description})
|
|
@maindex DEFINE
|
|
Define C preprocessor variable @var{variable}. If @var{value} is given,
|
|
set @var{variable} to that value (verbatim), otherwise set it to 1.
|
|
@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 @code{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 macro need not be mentioned in @file{acconfig.h}. 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
|
|
@end defmac
|
|
|
|
@defmac AC_DEFINE_UNQUOTED (@var{variable}, @ovar{value}, @ovar{description})
|
|
@maindex 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 the 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 @code{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, Caching Results, Defining Symbols, Results
|
|
@section Setting Output Variables
|
|
|
|
One way to record the results of tests is to set @dfn{output variables},
|
|
which are shell variables whose values are substituted into files that
|
|
@code{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})
|
|
@maindex 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 @samp{variable}.
|
|
@end defmac
|
|
|
|
@defmac AC_SUBST_FILE (@var{variable})
|
|
@maindex 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.in}
|
|
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
|
|
|
|
@node Caching Results, Printing Messages, Setting Output Variables, Results
|
|
@section Caching Results
|
|
@cindex Cache
|
|
|
|
To avoid checking for the same features repeatedly in various
|
|
@code{configure} scripts (or repeated runs of one script),
|
|
@code{configure} saves the results of many of its checks in a @dfn{cache
|
|
file}. If, when a @code{configure} script runs, it finds a cache file,
|
|
it reads from it the results from previous runs and avoids rerunning
|
|
those checks. As a result, @code{configure} can 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})
|
|
@maindex 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 @code{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 @code{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})
|
|
@maindex 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}. It is the code that
|
|
follows the call to @code{AC_CACHE_VAL} should do that, based on the
|
|
cached value. For instance the following macro:
|
|
|
|
@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[]dnl
|
|
])])
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
is broken: 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[]dnl
|
|
])
|
|
@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 @code{configure} uses for caching
|
|
@end menu
|
|
|
|
@node Cache Variable Names, Cache Files, Caching Results, Caching Results
|
|
@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, , Cache Variable Names, Caching Results
|
|
@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, configure uses no cache file (technically, it uses
|
|
@option{--cache-file=/dev/null}), so as to forestall problems caused by
|
|
accidental use of stale cache files.
|
|
|
|
To enable caching, @code{configure} accepts
|
|
@option{--cache-file=@var{file}} where @var{file} is the name of the
|
|
cache file to use, traditionally @file{config.cache}. The cache file is
|
|
created if it does not exist already. When @code{configure} calls
|
|
@code{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
|
|
@code{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 cache file on a particular system will gradually accumulate whenever
|
|
someone runs a @code{configure} script; it will be initially
|
|
nonexistent. Running @code{configure} merges the new cache results with
|
|
the existing cache file. The site initialization script can specify a
|
|
site-wide cache file to use instead of the default, to make it work
|
|
transparently, as long as the same C compiler is used every time
|
|
(@pxref{Site Defaults}).
|
|
|
|
If your configure script, or a macro called from configure.in, 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
|
|
@maindex 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
|
|
@maindex 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 configure.in.
|
|
@end defmac
|
|
|
|
For instance:
|
|
|
|
@example
|
|
@r{ ... AC_INIT, etc. ...}
|
|
@group
|
|
# Checks for programs.
|
|
AC_PROG_CC
|
|
AC_PROG_GCC_TRADITIONAL
|
|
@r{ ... more program checks ...}
|
|
AC_CACHE_SAVE
|
|
@end group
|
|
|
|
@group
|
|
# Checks for libraries.
|
|
AC_CHECK_LIB(nsl, gethostbyname)
|
|
AC_CHECK_LIB(socket, connect)
|
|
@r{ ... more lib checks ...}
|
|
AC_CACHE_SAVE
|
|
@end group
|
|
|
|
@group
|
|
# Might abort...
|
|
AM_PATH_GTK(1.0.2,, (exit 1); exit)
|
|
AM_PATH_GTKMM(0.9.5,, (exit 1); exit)
|
|
@end group
|
|
@r{ ... AC_OUTPUT, etc. ...}
|
|
@end example
|
|
|
|
@node Printing Messages, , Caching Results, Results
|
|
@section Printing Messages
|
|
@cindex Messages, from @code{configure}
|
|
|
|
@code{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.
|
|
@code{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 change
|
|
automatically.
|
|
|
|
To diagnose static issues, i.e., when @code{autoconf} is run, see
|
|
@ref{Reporting Messages}.
|
|
|
|
@defmac AC_MSG_CHECKING (@var{feature-description})
|
|
@maindex MSG_CHECKING
|
|
Notify the user that @code{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 @code{configure} is run with the
|
|
@option{--quiet} or @option{--silent} option.
|
|
@end defmac
|
|
|
|
@defmac AC_MSG_RESULT (@var{result-description})
|
|
@maindex 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 @code{configure} is run with the
|
|
@option{--quiet} or @option{--silent} option.
|
|
@end defmac
|
|
|
|
@defmac AC_MSG_NOTICE (@var{message})
|
|
@maindex 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 @code{configure} is run with the
|
|
@option{--quiet} or @option{--silent} option.
|
|
@end defmac
|
|
|
|
@defmac AC_MSG_ERROR (@var{error-description}, @ovar{exit-status})
|
|
@maindex MSG_ERROR
|
|
Notify the user of an error that prevents @code{configure} from
|
|
completing. This macro prints an error message on the standard error
|
|
output and exits @code{configure} with @var{exit-status} (1 by default).
|
|
@var{error-description} should be something like @samp{invalid value
|
|
$HOME for \$HOME}.
|
|
@end defmac
|
|
|
|
@defmac AC_MSG_WARN (@var{problem-description})
|
|
@maindex MSG_WARN
|
|
Notify the @code{configure} user of a possible problem. This macro
|
|
prints the message on the standard error output; @code{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 ========================================================== Writing Macros.
|
|
|
|
@node Writing Macros, Manual Configuration, Results, Top
|
|
@chapter Writing 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
|
|
* Quoting:: Protecting macros from unwanted expansion
|
|
* Reporting Messages:: Notifying @code{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, Macro Names, Writing Macros, Writing Macros
|
|
@section Macro Definitions
|
|
|
|
@maindex DEFUN
|
|
Autoconf macros are defined using the @code{AC_DEFUN} macro, which is
|
|
similar to the M4 builtin @code{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,
|
|
GNU m4}, for more complete information on writing M4 macros.
|
|
|
|
Be sure to quote properly 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 instance:
|
|
|
|
@example
|
|
# AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1])
|
|
# --------------------------------------
|
|
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 should make their way into @file{configure}, hence 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 @code{m4} to discard the text
|
|
through the next newline.
|
|
|
|
Keep in mind that @code{dnl} is rarely needed to introduce comments,
|
|
rather it is useful to get rid of the newlines following macros that
|
|
produce no output, such as @code{AC_REQUIRE}.
|
|
|
|
|
|
@node Macro Names, Quoting, Macro Definitions, Writing Macros
|
|
@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 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 Quoting, Reporting Messages, Macro Names, Writing Macros
|
|
@section Quoting
|
|
@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...
|
|
|
|
The most common brokenness of 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 ends with the rule of thumb. Understanding the former
|
|
helps following 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
|
|
* Quotation Rule Of Thumb:: One parenthesis, one quote
|
|
@end menu
|
|
|
|
@node Active Characters, One Macro Call, Quoting, Quoting
|
|
@subsection Active Characters
|
|
|
|
To fully understand where proper quotation is precious, you first need
|
|
to know what are the special characters 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 @code{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 ``obviousified'',
|
|
although 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 hopelessly try to find a means 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, Quotation and Nested Macros, Active Characters, Quoting
|
|
@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.in} to avoid unneeded
|
|
quotes, it is bad practice for Autoconf macros which must both be more
|
|
robust, and advocate the perfect writing.
|
|
|
|
At the top level, there are only two possible quoting: 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 this:
|
|
|
|
@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...
|
|
|
|
|
|
@node Quotation and Nested Macros, Quotation Rule Of Thumb, One Macro Call, Quoting
|
|
@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 @code{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
|
|
@code{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 time before the argument is passed to the @code{car}
|
|
macro, and the second time after the @code{car} macro expands to the
|
|
first argument.
|
|
|
|
As the author of the Autoconf macro @code{car} you then consider it is
|
|
incorrect to require 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 leave an @emph{unquoted} macro call:
|
|
|
|
@example
|
|
qar(active)
|
|
@result{}ACT
|
|
@end example
|
|
|
|
@noindent
|
|
while 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 @code{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 Quotation Rule Of Thumb, , Quotation and Nested Macros, Quoting
|
|
@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), quote properly
|
|
@emph{the arguments}!
|
|
|
|
It is frequent 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 noted that these two writings are rigorously
|
|
equivalent, since @code{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 which 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
|
|
|
|
@c FIXME: Quadrigraphs and hopeless cases.
|
|
|
|
When you create a @code{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 @code{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 @code{configure} script will contain
|
|
unexpanded macros. The @code{autoconf} program checks for this problem
|
|
by doing @samp{grep AC_ configure}.
|
|
|
|
|
|
@node Reporting Messages, Dependencies Between Macros, Quoting, Writing Macros
|
|
@section Reporting Messages
|
|
@cindex Messages, from @code{autoconf}
|
|
|
|
When macros statically diagnose abnormal situations, benign or fatal,
|
|
they should report them using these macros. For dynamic issues, i.e.,
|
|
when @code{configure} is run, see @ref{Printing Messages}.
|
|
|
|
@defmac AC_DIAGNOSE (@var{category}, @var{message})
|
|
@maindex DIAGNOSE
|
|
Report @var{message} as a warning (or as an error if requested by the
|
|
user) if it falls into the @var{category}. You are encouraged to use
|
|
standard categories, which currently include:
|
|
|
|
@table @samp
|
|
@item all
|
|
messages that don't fall into one of the following category. 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})
|
|
@maindex 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})
|
|
@maindex FATAL
|
|
Report a severe error @var{message}, and have @code{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, Obsoleting Macros, Reporting Messages, Writing 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, Suggested Ordering, Dependencies Between Macros, Dependencies Between 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})
|
|
@maindex 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 a 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_temparature_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.in}
|
|
|
|
@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 the kindred soul the
|
|
other times that the 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 avoids that messages from
|
|
required macros interrupt the messages from the requiring macros, (ii),
|
|
it avoids bad surprises when shell conditionals are used, as in:
|
|
|
|
@example
|
|
@group
|
|
if ...; then
|
|
AC_REQUIRE([SOME_CHECK])
|
|
fi
|
|
...
|
|
SOME_CHECK
|
|
@end group
|
|
@end example
|
|
|
|
|
|
You are encouraged to put all the @code{AC_REQUIRE}s at the beginning of
|
|
the macros. You can use @code{dnl} to avoid the empty line they leave.
|
|
|
|
@node Suggested Ordering, , Prerequisite Macros, Dependencies Between Macros
|
|
@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.in} file. The warning occurs when creating
|
|
@code{configure} from @file{configure.in}, not when running
|
|
@code{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})
|
|
@maindex BEFORE
|
|
Make @code{m4} print a warning message on 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, Coding Style, Dependencies Between Macros, Writing 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, @code{autoupdate} should substitute 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})
|
|
@maindex DEFUN
|
|
@maindex 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 @code{autoupdate}, the call to @var{old-macro} will be
|
|
replaced by the modern @var{implementation}. The additional
|
|
@var{message} is then printed.
|
|
@end defmac
|
|
|
|
@node Coding Style, , Obsoleting Macros, Writing Macros
|
|
@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{Quoting}.
|
|
|
|
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 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). Or better yet, using high
|
|
level macros such as @code{AC_EXPAND_ONCE}.
|
|
|
|
No Autoconf macro should ever enter the user variables name space, i.e.,
|
|
but the variables that are the actual result of running the macro, all
|
|
the 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_TRY_RUN} or any macro that cannot work when
|
|
cross-compiling, provide a pessimistic value (typically @samp{no}).
|
|
|
|
Feel free to use various tricks to avoid that auxiliary tools, such as
|
|
syntax-highlighting editors, behave improperly. For instance, instead
|
|
of
|
|
|
|
@example
|
|
patsubst([$1], [$"])
|
|
@end example
|
|
|
|
@noindent
|
|
use
|
|
|
|
@example
|
|
patsubst([$1], [$""])
|
|
@end example
|
|
|
|
@noindent
|
|
so that Emacsen do not open a endless ``string'' at the first quote.
|
|
For the same reasons, avoid
|
|
|
|
@example
|
|
test $[#] != 0
|
|
@end example
|
|
|
|
@noindent
|
|
but 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 unneeded. 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} but 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 never to be the
|
|
object of an @code{AC_REQUIRE} directive, then use @code{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 both
|
|
provides a simpler and 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. If you want to avoid the new-line which is then
|
|
introduced, use @code{dnl}. Better yet, use @samp{[]dnl} @emph{even}
|
|
behind of parenthesis, since because of the M4 evaluation rule the
|
|
@samp{dnl} might be appended to the result of the evaluation of the
|
|
macro before it (e.g., leading to @samp{yesdnl} instead of @samp{yes}).
|
|
For instance, instead of:
|
|
|
|
@example
|
|
AC_DEFUN([AC_PATH_X],
|
|
[AC_MSG_CHECKING(for X)
|
|
AC_REQUIRE_CPP()
|
|
@r{# cut...}
|
|
AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
|
|
fi])
|
|
@end example
|
|
|
|
@noindent
|
|
write:
|
|
|
|
@example
|
|
AC_DEFUN([AC_PATH_X],
|
|
[AC_REQUIRE_CPP()dnl
|
|
AC_MSG_CHECKING(for X)
|
|
@r{# cut...}
|
|
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 this 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.
|
|
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 ================================================== Manual Configuration
|
|
|
|
@node Manual Configuration, Site Configuration, Writing Macros, Top
|
|
@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
|
|
@code{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, Canonicalizing, Manual Configuration, Manual Configuration
|
|
@section Specifying the System Type
|
|
|
|
Like other @sc{gnu} @code{configure} scripts, Autoconf-generated
|
|
@code{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}}
|
|
|
|
@code{configure} can usually guess the canonical name for the type of
|
|
system it's running on. To do so it runs a script called
|
|
@code{config.guess}, which derives 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 @code{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@footnote{For
|
|
backward compatibility, @code{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 NetBSD/alpha but generate
|
|
code for GNU Hurd/sparc, which is also the build platform.
|
|
|
|
@example
|
|
./configure --host=alpha-netbsd sparc-gnu
|
|
@end example
|
|
}:
|
|
|
|
@table @option
|
|
@item --build=@var{build-type}
|
|
the type of system on which the package is being configured and
|
|
compiled.
|
|
|
|
@item --host=@var{host-type}
|
|
@ovindex cross_compiling
|
|
the type of system on which the package will run.
|
|
|
|
@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
|
|
|
|
They all default to the result of running @code{config.guess}, unless
|
|
you specify either @samp{--build} or @samp{--host}. In this case, the
|
|
default becomes the system type you specified. If you specify both, and
|
|
they're different, @code{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 @code{config.guess}, prefer
|
|
@samp{--build} over @samp{--host}. In the future, @samp{--host} will
|
|
not override the name of the build system type. Also, when you specify
|
|
@samp{--host}, but not @samp{--build}, when @code{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. Note, however, that it won't guess the build system type, since
|
|
this may require running test programs. 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, but @code{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
|
|
|
|
@code{configure} recognizes short aliases for many system types; for
|
|
example, @samp{decstation} can be used instead of
|
|
@samp{mips-dec-ultrix4.2}. @code{configure} runs a script called
|
|
@code{config.sub} to canonicalize system type aliases.
|
|
|
|
|
|
|
|
@node Canonicalizing, Using System Type, Specifying Names, Manual Configuration
|
|
@section Getting the Canonical System Type
|
|
|
|
The following macros make the system type available to @code{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 @samp{--build},
|
|
@samp{--host}, and @samp{--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 @code{config.guess} and
|
|
@code{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 @code{configure} looks for those scripts.
|
|
|
|
|
|
@defmac AC_CANONICAL_BUILD
|
|
@maindex 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 @samp{--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 @code{config.guess}.
|
|
@end defmac
|
|
|
|
@defmac AC_CANONICAL_HOST
|
|
@maindex 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 @samp{--host} was specified, then @code{host} is the
|
|
canonicalization of @code{host_alias} by @command{config.sub},
|
|
otherwise it defaults to @code{build}.
|
|
|
|
For temporary backward-compatibility, when @samp{--host} is specified
|
|
by @samp{--build} isn't, the build system will be assumed to be the
|
|
same as @samp{--host}, and @samp{build_alias} will be set to that
|
|
value. Eventually, this historically incorrect behavior will go away.
|
|
|
|
@end defmac
|
|
|
|
@defmac AC_CANONICAL_TARGET
|
|
@maindex 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 @samp{--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
|
|
|
|
|
|
@node Using System Type, , Canonicalizing, Manual Configuration
|
|
@section Using the System Type
|
|
|
|
How do you use a canonical system type? Usually, you use it in one or
|
|
more @code{case} statements in @file{configure.in} to select
|
|
system-specific C files. Then, using @code{AC_CONFIG_LINKS}, link those
|
|
files which have names based on the system name, to generic names, such
|
|
as @file{host.h} or @file{target.c} (@pxref{Configuration Links}). The
|
|
@code{case} statement patterns can use shell wild cards to group several
|
|
cases together, like in this fragment:
|
|
|
|
@example
|
|
case "$target" in
|
|
i386-*-mach* | i386-*-gnu*)
|
|
obj_format=aout emulation=mach bfd_gas=yes ;;
|
|
i960-*-bout) obj_format=bout ;;
|
|
esac
|
|
@end example
|
|
|
|
@noindent
|
|
and in @file{configure.in}, use:
|
|
|
|
@example
|
|
AC_CONFIG_LINKS(host.h:config/$machine.h
|
|
object.h:config/$obj_format.h)
|
|
@end example
|
|
|
|
You can also use the host system type to find cross-compilation tools.
|
|
@xref{Generic Programs}, for information about the @code{AC_CHECK_TOOL}
|
|
macro which does that.
|
|
|
|
|
|
@c ===================================================== Site Configuration.
|
|
|
|
@node Site Configuration, Running configure scripts, Manual Configuration, Top
|
|
@chapter Site Configuration
|
|
|
|
@code{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 @code{configure}
|
|
options.
|
|
|
|
@menu
|
|
* External Software:: Working with other optional software
|
|
* Package Options:: Selecting optional features
|
|
* Pretty Help Strings:: Formating help string
|
|
* Site Details:: Configuring site details
|
|
* Transforming Names:: Changing program names when installing
|
|
* Site Defaults:: Giving @code{configure} local defaults
|
|
@end menu
|
|
|
|
@node External Software, Package Options, Site Configuration, Site Configuration
|
|
@section Working With External Software
|
|
|
|
Some packages require, or can optionally use, other software packages
|
|
that are already installed. The user can give @code{configure}
|
|
command line options to specify which such external software to use.
|
|
The options have one of these forms:
|
|
|
|
@example
|
|
--with-@var{package}=@ovar{arg}
|
|
--without-@var{package}
|
|
@end example
|
|
|
|
For example, @option{--with-gnu-ld} means work with the @sc{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}.
|
|
|
|
@code{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 @code{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.in}
|
|
should call @code{AC_ARG_WITH} to detect whether the @code{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})
|
|
@maindex ARG_WITH
|
|
If the user gave @code{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 which
|
|
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 it in @samp{[}
|
|
and @samp{]} in order to produce the leading spaces.
|
|
|
|
You should format your @var{help-string} with the macro
|
|
@code{AC_HELP_STRING} (@pxref{Pretty Help Strings}).
|
|
@end defmac
|
|
|
|
@defmac AC_WITH (@var{package}, @var{action-if-given}, @ovar{action-if-not-given})
|
|
@maindex WITH
|
|
This is an obsolete version of @code{AC_ARG_WITH} that does not
|
|
support providing a help string.
|
|
@end defmac
|
|
|
|
@node Package Options, Pretty Help Strings, External Software, Site Configuration
|
|
@section Choosing Package Options
|
|
|
|
If a software package has optional compile-time features, the user can
|
|
give @code{configure} command line options to specify whether to
|
|
compile them. The options have one of these forms:
|
|
|
|
@example
|
|
--enable-@var{feature}=@ovar{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}.
|
|
|
|
@code{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 @code{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.in} should call
|
|
@code{AC_ARG_ENABLE} to detect whether the @code{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})
|
|
@maindex ARG_ENABLE
|
|
If the user gave @code{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{AC_HELP_STRING} (@pxref{Pretty Help Strings}).
|
|
@end defmac
|
|
|
|
@defmac AC_ENABLE (@var{feature}, @var{action-if-given}, @ovar{action-if-not-given})
|
|
@maindex 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, Site Details, Package Options, Site Configuration
|
|
@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{AC_HELP_STRING} macro.
|
|
|
|
@defmac AC_HELP_STRING (@var{left-hand-side}, @var{right-hand-side})
|
|
@maindex 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,
|
|
AC_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{AC_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{AC_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],
|
|
AC_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, Transforming Names, Pretty Help Strings, Site Configuration
|
|
@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, GNU Coding
|
|
Standards}, for more information on where to put data files.
|
|
|
|
@node Transforming Names, Site Defaults, Site Details, Site Configuration
|
|
@section Transforming Program Names When Installing
|
|
|
|
Autoconf supports changing the names of programs when installing them.
|
|
In order to use these transformations, @file{configure.in} must call the
|
|
macro @code{AC_ARG_PROGRAM}.
|
|
|
|
@defmac AC_ARG_PROGRAM
|
|
@maindex 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 @code{configure},
|
|
program names are transformed accordingly. Otherwise, if
|
|
@code{AC_CANONICAL_TARGET} has been called and a @option{--target} value
|
|
is given that differs from the host type (specified with @option{--host}),
|
|
the target type followed by a dash is used as a prefix. Otherwise, no
|
|
program name transformation is done.
|
|
@end defmac
|
|
|
|
@menu
|
|
* Transformation Options:: @code{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, Transformation Examples, Transforming Names, Transforming Names
|
|
@subsection Transformation Options
|
|
|
|
You can specify name transformations by giving @code{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, Transformation Rules, Transformation Options, Transforming Names
|
|
@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
|
|
@sc{gnu} programs installed on your system to shadow other programs with
|
|
the same name. For example, if you configure @sc{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 @sc{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, , Transformation Examples, Transforming Names
|
|
@subsection Transformation Rules
|
|
|
|
Here is how to use the variable @code{program_transform_name} in a
|
|
@file{Makefile.in}:
|
|
|
|
@example
|
|
transform = @@program_transform_name@@
|
|
install: all
|
|
$(INSTALL_PROGRAM) myprog $(bindir)/`echo myprog|sed '$(transform)'`
|
|
|
|
uninstall:
|
|
rm -f $(bindir)/`echo myprog|sed '$(transform)'`
|
|
@end example
|
|
|
|
@noindent
|
|
If you have more than one program to install, you can do it in a loop:
|
|
|
|
@example
|
|
PROGRAMS = cp ls rm
|
|
install:
|
|
for p in $(PROGRAMS); do \
|
|
$(INSTALL_PROGRAM) $$p $(bindir)/`echo $$p|sed '$(transform)'`; \
|
|
done
|
|
|
|
uninstall:
|
|
for p in $(PROGRAMS); do \
|
|
rm -f $(bindir)/`echo $$p|sed '$(transform)'`; \
|
|
done
|
|
@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, , Transforming Names, Site Configuration
|
|
@section Setting Site Defaults
|
|
|
|
Autoconf-generated @code{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, @code{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 @code{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
|
|
@code{configure} scripts run on that system. 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
|
|
@code{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, so 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 @code{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
|
|
@code{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, config.status Invocation, Site Configuration, Top
|
|
@chapter Running @code{configure} Scripts
|
|
@cindex @code{configure}
|
|
|
|
Below are instructions on how to configure a package that uses a
|
|
@code{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 @code{configure}
|
|
* Environment Variables:: Defining environment variables.
|
|
* configure Invocation:: Changing how @code{configure} runs
|
|
@end menu
|
|
|
|
@include install.texi
|
|
|
|
|
|
@c ============================================== Recreating a Configuration
|
|
|
|
@node config.status Invocation, Obsolete Constructs, Running configure scripts, Top
|
|
@chapter Recreating a Configuration
|
|
@cindex @code{config.status}
|
|
|
|
The @code{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}... [@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 --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 @code{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.in} 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 @code{configure}, so that the
|
|
results of some tests might be different from the previous run. The
|
|
@option{--recheck} option re-runs @code{configure} with the same arguments
|
|
you used before, plus the @option{--no-create} option, which prevents
|
|
@code{configure} from running @file{config.status} and creating
|
|
@file{Makefile} and other files, and the @option{--no-recursion} option,
|
|
which prevents @code{configure} from running other @code{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 @code{configure} for the @option{--recheck}
|
|
option. It must be Bourne-compatible. The default is @file{/bin/sh}.
|
|
@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 @code{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.in} 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, Questions, config.status Invocation, Top
|
|
@chapter Obsolete Constructs
|
|
|
|
Autoconf changes, and throughout the years some constructs are obsoleted.
|
|
Most of the changes involve the macros, but 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.in}
|
|
* Obsolete Macros:: Backward compatibility macros
|
|
* Autoconf 1:: Tips for upgrading your files
|
|
@end menu
|
|
|
|
@node Obsolete config.status Use, acconfig.h, Obsolete Constructs, Obsolete Constructs
|
|
@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.in}.
|
|
@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.in}.
|
|
@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.in} 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, autoupdate Invocation, Obsolete config.status Use, Obsolete Constructs
|
|
@section @file{acconfig.h}
|
|
|
|
@cindex @file{acconfig.h}
|
|
@cindex @file{config.h.top}
|
|
@cindex @file{config.h.bot}
|
|
|
|
@code{autoheader} scans @file{configure.in} and figures out which C
|
|
preprocessor symbols it might define. It copies comments and
|
|
@code{#define} and @code{#undef} statements from a file called
|
|
@file{acconfig.h} in the current directory, if present. This file used
|
|
to be mandatory if you @code{AC_DEFINE} any additional symbols. Now,
|
|
you are encouraged to use the @code{AH} series of macros
|
|
(@pxref{Autoheader Macros}).
|
|
|
|
The file that @code{autoheader} creates contains mainly @code{#define}
|
|
and @code{#undef} statements and their accompanying comments. If
|
|
@file{./acconfig.h} contains the string @samp{@@TOP@@},
|
|
@code{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@@},
|
|
@code{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 alternate way to produce the same effect 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,
|
|
@code{autoheader} copies them to the beginning and end, respectively, of
|
|
its output. Their use is discouraged because they have file names that
|
|
contain two periods, and so cannot be stored on MS-DOS; also, they are
|
|
two more files to clutter up the directory. But if you use the
|
|
@option{--localdir=@var{dir}} option to use an @file{acconfig.h} in
|
|
another directory, they give you a way to put custom boilerplate in each
|
|
individual @file{config.h.in}.
|
|
|
|
|
|
@node autoupdate Invocation, Obsolete Macros, acconfig.h, Obsolete Constructs
|
|
@section Using @code{autoupdate} to Modernize @file{configure.in}
|
|
@cindex @code{autoupdate}
|
|
|
|
The @code{autoupdate} program updates a @file{configure.in} 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.in} 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, @code{autoupdate} updates @file{configure.in},
|
|
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 @code{autoupdate} an argument, it reads that file
|
|
instead of @file{configure.in} and writes the updated file to the
|
|
standard output.
|
|
|
|
@noindent
|
|
@code{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 --autoconf-dir=@var{dir}
|
|
@itemx -A
|
|
@evindex AC_MACRODIR
|
|
Overwrite the location where Autoconf files were installed. You can
|
|
also set the @code{AC_MACRODIR} environment variable to a directory;
|
|
this option overrides the environment variable.
|
|
|
|
This option is rarely needed and dangerous: only when you play with
|
|
different versions of Autoconf.
|
|
|
|
@item --localdir=@var{dir}
|
|
@itemx -l @var{dir}
|
|
Look for the package file @file{aclocal.m4} in directory @var{dir}
|
|
instead of in the current directory.
|
|
@end table
|
|
|
|
@node Obsolete Macros, Autoconf 1, autoupdate Invocation, Obsolete Constructs
|
|
@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, 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
|
|
@maindex ALLOCA
|
|
@code{AC_FUNC_ALLOCA}
|
|
@end defmac
|
|
|
|
@defmac AC_ARG_ARRAY
|
|
@maindex ARG_ARRAY
|
|
removed because of limited usefulness
|
|
@end defmac
|
|
|
|
@defmac AC_C_CROSS
|
|
@maindex C_CROSS
|
|
This macro is obsolete; it does nothing.
|
|
@end defmac
|
|
|
|
@defmac AC_CANONICAL_SYSTEM
|
|
@maindex 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 explicitly use either
|
|
@code{AC_CANONICAL_BUILD}, or @code{AC_CANONICAL_HOST}, or
|
|
@code{AC_CANONICAL_TARGET}, depending on her needs. Using
|
|
@code{AC_CANONICAL_TARGET} is enough to run the three macros.
|
|
@end defmac
|
|
|
|
@defmac AC_CHAR_UNSIGNED
|
|
@maindex CHAR_UNSIGNED
|
|
@code{AC_C_CHAR_UNSIGNED}
|
|
@end defmac
|
|
|
|
@defmac AC_CHECK_TYPE (@var{type}, @var{default})
|
|
@maindex 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. Second, 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([@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 is a C or C++ @emph{builtin} type, then the
|
|
obsolete version is used. Because many people have used @samp{off_t}
|
|
and @samp{size_t} as replacement types, they are recognized too.
|
|
|
|
@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})
|
|
@maindex CHECKING
|
|
Same as @samp{AC_MSG_NOTICE([checking @var{feature-description}...]}.
|
|
@end defmac
|
|
|
|
@defmac AC_COMPILE_CHECK (@var{echo-text}, @var{includes}, @var{function-body}, @var{action-if-found}, @ovar{action-if-not-found})
|
|
@maindex COMPILE_CHECK
|
|
This is an obsolete version of @code{AC_TRY_LINK} (@pxref{Examining
|
|
Libraries}), 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
|
|
@maindex CONST
|
|
@code{AC_C_CONST}
|
|
@end defmac
|
|
|
|
@defmac AC_CROSS_CHECK
|
|
@maindex CROSS_CHECK
|
|
Same as @code{AC_C_CROSS}, which is obsolete too, and does nothing
|
|
@code{:-)}.
|
|
@end defmac
|
|
|
|
@defmac AC_CYGWIN
|
|
@maindex CYGWIN
|
|
Checked for the Cygwin environment in which case the shell variable
|
|
@code{CYGWIN} is set to @samp{yes}. @code{AC_EXEEXT} now handles this
|
|
task.
|
|
@end defmac
|
|
|
|
@defmac AC_DECL_YYTEXT
|
|
@maindex DECL_YYTEXT
|
|
Does nothing, now integrated in @code{AC_PROG_LEX}.
|
|
@end defmac
|
|
|
|
@defmac AC_DIR_HEADER
|
|
@maindex 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
|
|
@maindex DYNIX_SEQ
|
|
If on Dynix/PTX (Sequent @sc{unix}), 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
|
|
@maindex EXEEXT
|
|
@ovindex EXEEXT
|
|
@ovindex CYGWIN
|
|
@ovindex EMXOS2
|
|
@ovindex MINGW32
|
|
Defined the output variable @code{EXEEXT} based on the output of the
|
|
compiler. Typically set to empty string if Unix and @samp{.exe} if
|
|
Win32 or OS/2.
|
|
|
|
This macro sets the shell variable @code{CYGWIN} to @samp{yes} if run in
|
|
the Cygwin environment, @code{EMXOS2} to @samp{yes} if in the EMX
|
|
environment on OS/2, and @code{MINGW32} to @samp{yes} with the MingW32
|
|
compiler.
|
|
|
|
Now handled by the macros checking for the compiler.
|
|
@end defmac
|
|
|
|
@defmac AC_EMXOS2
|
|
@maindex EMXOS2
|
|
Checks for the EMX environment on OS/2 in which case the shell variable
|
|
@code{EMXOS2} is set to @samp{yes}. @code{AC_EXEEXT} now handles this
|
|
task.
|
|
@end defmac
|
|
|
|
@defmac AC_ERROR
|
|
@maindex ERROR
|
|
@code{AC_MSG_ERROR}
|
|
@end defmac
|
|
|
|
@defmac AC_FIND_X
|
|
@maindex FIND_X
|
|
@code{AC_PATH_X}
|
|
@end defmac
|
|
|
|
@defmac AC_FIND_XTRA
|
|
@maindex FIND_XTRA
|
|
@code{AC_PATH_XTRA}
|
|
@end defmac
|
|
|
|
@defmac AC_FUNC_CHECK
|
|
@maindex FUNC_CHECK
|
|
@code{AC_CHECK_FUNC}
|
|
@end defmac
|
|
|
|
@defmac AC_GCC_TRADITIONAL
|
|
@maindex GCC_TRADITIONAL
|
|
@code{AC_PROG_GCC_TRADITIONAL}
|
|
@end defmac
|
|
|
|
@defmac AC_GETGROUPS_T
|
|
@maindex GETGROUPS_T
|
|
@code{AC_TYPE_GETGROUPS}
|
|
@end defmac
|
|
|
|
@defmac AC_GETLOADAVG
|
|
@maindex GETLOADAVG
|
|
@code{AC_FUNC_GETLOADAVG}
|
|
@end defmac
|
|
|
|
@defmac AC_HAVE_FUNCS
|
|
@maindex HAVE_FUNCS
|
|
@code{AC_CHECK_FUNCS}
|
|
@end defmac
|
|
|
|
@defmac AC_HAVE_HEADERS
|
|
@maindex 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})
|
|
@maindex 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
|
|
@maindex HAVE_POUNDBANG
|
|
@code{AC_SYS_INTERPRETER} (different calling convention)
|
|
@end defmac
|
|
|
|
@defmac AC_HEADER_CHECK
|
|
@maindex HEADER_CHECK
|
|
@code{AC_CHECK_HEADER}
|
|
@end defmac
|
|
|
|
@defmac AC_HEADER_EGREP
|
|
@maindex HEADER_EGREP
|
|
@code{AC_EGREP_HEADER}
|
|
@end defmac
|
|
|
|
@defmac AC_INIT (@var{unique-file-in-source-dir})
|
|
@maindex 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
|
|
@maindex INLINE
|
|
@code{AC_C_INLINE}
|
|
@end defmac
|
|
|
|
@defmac AC_INT_16_BITS
|
|
@maindex 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
|
|
@maindex IRIX_SUN
|
|
If on 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
|
|
@maindex LANG_C
|
|
Same as @samp{AC_LANG(C)}.
|
|
@end defmac
|
|
|
|
@defmac AC_LANG_CPLUSPLUS
|
|
@maindex LANG_CPLUSPLUS
|
|
Same as @samp{AC_LANG(C++)}.
|
|
@end defmac
|
|
|
|
@defmac AC_LANG_FORTRAN77
|
|
@maindex LANG_FORTRAN77
|
|
Same as @samp{AC_LANG(Fortran 77)}.
|
|
@end defmac
|
|
|
|
@defmac AC_LANG_RESTORE
|
|
@maindex 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
|
|
@maindex LANG_SAVE
|
|
Remember the current language (as set by @code{AC_LANG}) on a stack.
|
|
Doe not change which language is current. @code{AC_LANG_PUSH} is
|
|
preferred.
|
|
@end defmac
|
|
|
|
@defmac AC_LINK_FILES (@var{source}@dots{}, @var{dest}@dots{})
|
|
@maindex 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
|
|
@maindex LN_S
|
|
@code{AC_PROG_LN_S}
|
|
@end defmac
|
|
|
|
@defmac AC_LONG_64_BITS
|
|
@maindex LONG_64_BITS
|
|
@cvindex LONG_64_BITS
|
|
If the C type @code{long int} is 16 bits wide, define
|
|
@code{LONG_64_BITS}. Use @samp{AC_CHECK_SIZEOF(long int)} instead.
|
|
@end defmac
|
|
|
|
@defmac AC_LONG_DOUBLE
|
|
@maindex LONG_DOUBLE
|
|
@code{AC_C_LONG_DOUBLE}
|
|
@end defmac
|
|
|
|
@defmac AC_LONG_FILE_NAMES
|
|
@maindex LONG_FILE_NAMES
|
|
@code{AC_SYS_LONG_FILE_NAMES}
|
|
@end defmac
|
|
|
|
@defmac AC_MAJOR_HEADER
|
|
@maindex MAJOR_HEADER
|
|
@code{AC_HEADER_MAJOR}
|
|
@end defmac
|
|
|
|
@defmac AC_MEMORY_H
|
|
@maindex 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 @xref{Standard
|
|
Symbols}.
|
|
@end defmac
|
|
|
|
@defmac AC_MINGW32
|
|
@maindex MINGW32
|
|
Checked for the MingW32 compiler environment, in which case the shell
|
|
variable @code{MINGW32} is set to @samp{yes}. @code{AC_EXEEXT} now
|
|
handles this task.
|
|
@end defmac
|
|
|
|
@defmac AC_MINUS_C_MINUS_O
|
|
@maindex MINUS_C_MINUS_O
|
|
@code{AC_PROG_CC_C_O}
|
|
@end defmac
|
|
|
|
@defmac AC_MMAP
|
|
@maindex MMAP
|
|
@code{AC_FUNC_MMAP}
|
|
@end defmac
|
|
|
|
@defmac AC_MODE_T
|
|
@maindex MODE_T
|
|
@code{AC_TYPE_MODE_T}
|
|
@end defmac
|
|
|
|
@defmac AC_OBJEXT
|
|
@maindex 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.
|
|
@end defmac
|
|
|
|
@defmac AC_OBSOLETE (@var{this-macro-name}, @ovar{suggestion})
|
|
@maindex OBSOLETE
|
|
Make @code{m4} print a message on 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
|
|
@maindex OFF_T
|
|
@code{AC_TYPE_OFF_T}
|
|
@end defmac
|
|
|
|
@defmac AC_OUTPUT (@ovar{file}@dots{}, @ovar{extra-cmds}, @ovar{init-cmds})
|
|
@maindex 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})
|
|
@maindex OUTPUT_COMMANDS
|
|
Specify additional shell commands to run at the end of
|
|
@file{config.status}, and shell commands to initialize any variables
|
|
from @code{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, while
|
|
@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
|
|
@maindex PID_T
|
|
@code{AC_TYPE_PID_T}
|
|
@end defmac
|
|
|
|
@defmac AC_PREFIX
|
|
@maindex PREFIX
|
|
@code{AC_PREFIX_PROGRAM}
|
|
@end defmac
|
|
|
|
@defmac AC_PROGRAMS_CHECK
|
|
@maindex PROGRAMS_CHECK
|
|
@code{AC_CHECK_PROGS}
|
|
@end defmac
|
|
|
|
@defmac AC_PROGRAMS_PATH
|
|
@maindex PROGRAMS_PATH
|
|
@code{AC_PATH_PROGS}
|
|
@end defmac
|
|
|
|
@defmac AC_PROGRAM_CHECK
|
|
@maindex PROGRAM_CHECK
|
|
@code{AC_CHECK_PROG}
|
|
@end defmac
|
|
|
|
@defmac AC_PROGRAM_EGREP
|
|
@maindex PROGRAM_EGREP
|
|
@code{AC_EGREP_CPP}
|
|
@end defmac
|
|
|
|
@defmac AC_PROGRAM_PATH
|
|
@maindex PROGRAM_PATH
|
|
@code{AC_PATH_PROG}
|
|
@end defmac
|
|
|
|
@defmac AC_REMOTE_TAPE
|
|
@maindex REMOTE_TAPE
|
|
removed because of limited usefulness
|
|
@end defmac
|
|
|
|
@defmac AC_RESTARTABLE_SYSCALLS
|
|
@maindex RESTARTABLE_SYSCALLS
|
|
@code{AC_SYS_RESTARTABLE_SYSCALLS}
|
|
@end defmac
|
|
|
|
@defmac AC_RETSIGTYPE
|
|
@maindex RETSIGTYPE
|
|
@code{AC_TYPE_SIGNAL}
|
|
@end defmac
|
|
|
|
@defmac AC_RSH
|
|
@maindex RSH
|
|
Removed because of limited usefulness.
|
|
@end defmac
|
|
|
|
@defmac AC_SCO_INTL
|
|
@maindex 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
|
|
@maindex SETVBUF_REVERSED
|
|
@code{AC_FUNC_SETVBUF_REVERSED}
|
|
@end defmac
|
|
|
|
@defmac AC_SET_MAKE
|
|
@maindex SET_MAKE
|
|
@code{AC_PROG_MAKE_SET}
|
|
@end defmac
|
|
|
|
@defmac AC_SIZEOF_TYPE
|
|
@maindex SIZEOF_TYPE
|
|
@code{AC_CHECK_SIZEOF}
|
|
@end defmac
|
|
|
|
@defmac AC_SIZE_T
|
|
@maindex SIZE_T
|
|
@code{AC_TYPE_SIZE_T}
|
|
@end defmac
|
|
|
|
@defmac AC_STAT_MACROS_BROKEN
|
|
@maindex STAT_MACROS_BROKEN
|
|
@code{AC_HEADER_STAT}
|
|
@end defmac
|
|
|
|
@defmac AC_STDC_HEADERS
|
|
@maindex STDC_HEADERS
|
|
@code{AC_HEADER_STDC}
|
|
@end defmac
|
|
|
|
@defmac AC_STRCOLL
|
|
@maindex STRCOLL
|
|
@code{AC_FUNC_STRCOLL}
|
|
@end defmac
|
|
|
|
@defmac AC_ST_BLKSIZE
|
|
@maindex ST_BLKSIZE
|
|
@code{AC_STRUCT_ST_BLKSIZE}
|
|
@end defmac
|
|
|
|
@defmac AC_ST_BLOCKS
|
|
@maindex ST_BLOCKS
|
|
@code{AC_STRUCT_ST_BLOCKS}
|
|
@end defmac
|
|
|
|
@defmac AC_ST_RDEV
|
|
@maindex ST_RDEV
|
|
@code{AC_STRUCT_ST_RDEV}
|
|
@end defmac
|
|
|
|
@defmac AC_SYS_SIGLIST_DECLARED
|
|
@maindex SYS_SIGLIST_DECLARED
|
|
@code{AC_DECL_SYS_SIGLIST}
|
|
@end defmac
|
|
|
|
@defmac AC_TEST_CPP
|
|
@maindex TEST_CPP
|
|
@code{AC_TRY_CPP}
|
|
@end defmac
|
|
|
|
@defmac AC_TEST_PROGRAM
|
|
@maindex TEST_PROGRAM
|
|
@code{AC_TRY_RUN}
|
|
@end defmac
|
|
|
|
@defmac AC_TIMEZONE
|
|
@maindex TIMEZONE
|
|
@code{AC_STRUCT_TIMEZONE}
|
|
@end defmac
|
|
|
|
@defmac AC_TIME_WITH_SYS_TIME
|
|
@maindex TIME_WITH_SYS_TIME
|
|
@code{AC_HEADER_TIME}
|
|
@end defmac
|
|
|
|
@defmac AC_UID_T
|
|
@maindex UID_T
|
|
@code{AC_TYPE_UID_T}
|
|
@end defmac
|
|
|
|
@defmac AC_UNISTD_H
|
|
@maindex UNISTD_H
|
|
Same as @samp{AC_CHECK_HEADERS(unistd.h)}.
|
|
@end defmac
|
|
|
|
@defmac AC_USG
|
|
@maindex USG
|
|
@cvindex USG
|
|
Define @code{USG} if the @sc{bsd} string functions are defined in
|
|
@file{strings.h}. You should no longer depend upon @code{USG}, but on
|
|
@code{HAVE_STRING_H}, see @xref{Standard Symbols}.
|
|
@end defmac
|
|
|
|
@defmac AC_UTIME_NULL
|
|
@maindex UTIME_NULL
|
|
@code{AC_FUNC_UTIME_NULL}
|
|
@end defmac
|
|
|
|
@defmac AC_VALIDATE_CACHED_SYSTEM_TUPLE (@ovar{cmd})
|
|
@maindex 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})
|
|
@maindex VERBOSE
|
|
@code{AC_MSG_RESULT}.
|
|
@end defmac
|
|
|
|
@defmac AC_VFORK
|
|
@maindex VFORK
|
|
@code{AC_FUNC_VFORK}
|
|
@end defmac
|
|
|
|
@defmac AC_VPRINTF
|
|
@maindex VPRINTF
|
|
@code{AC_FUNC_VPRINTF}
|
|
@end defmac
|
|
|
|
@defmac AC_WAIT3
|
|
@maindex WAIT3
|
|
@code{AC_FUNC_WAIT3}
|
|
@end defmac
|
|
|
|
@defmac AC_WARN
|
|
@maindex WARN
|
|
@code{AC_MSG_WARN}
|
|
@end defmac
|
|
|
|
@defmac AC_WORDS_BIGENDIAN
|
|
@maindex WORDS_BIGENDIAN
|
|
@code{AC_C_BIGENDIAN}
|
|
@end defmac
|
|
|
|
@defmac AC_XENIX_DIR
|
|
@maindex 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
|
|
@maindex YYTEXT_POINTER
|
|
@code{AC_DECL_YYTEXT}
|
|
@end defmac
|
|
|
|
@node Autoconf 1, , Obsolete Macros, Obsolete Constructs
|
|
@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.in} 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
|
|
@code{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, Changed Makefiles, Autoconf 1, Autoconf 1
|
|
@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} or @file{config.h.bot}, you still
|
|
can, but you will have less clutter if you merge them into
|
|
@file{acconfig.h}. @xref{autoheader Invocation}.
|
|
|
|
@node Changed Makefiles, Changed Macros, Changed File Names, Autoconf 1
|
|
@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 @code{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 @code{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, Changed Results, Changed Makefiles, Autoconf 1
|
|
@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 @code{autoupdate} program to
|
|
convert your @file{configure.in} 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 @code{autoconf}, you may safely ignore them, but
|
|
your @code{configure} script will generally work better if you follow
|
|
the advice it prints 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 @code{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, Changed Macro Writing, Changed Macros, Autoconf 1
|
|
@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
|
|
@code{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.in} 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, , Changed Results, Autoconf 1
|
|
@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 into macros that you can share.
|
|
|
|
|
|
@c ================================================ Questions About Autoconf.
|
|
|
|
@node Questions, History, Obsolete Constructs, Top
|
|
@chapter Questions About Autoconf
|
|
|
|
Several questions about Autoconf come up occasionally. Here some of them
|
|
are addressed.
|
|
|
|
@menu
|
|
* Distributing:: Distributing @code{configure} scripts
|
|
* Why GNU m4:: Why not use the standard M4?
|
|
* Bootstrapping:: Autoconf and GNU M4 require each other?
|
|
* Why Not Imake:: Why GNU uses @code{configure} instead of Imake
|
|
@end menu
|
|
|
|
@node Distributing, Why GNU m4, Questions, Questions
|
|
@section Distributing @code{configure} Scripts
|
|
|
|
@display
|
|
What are the restrictions on distributing @code{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 @sc{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 @code{configure},
|
|
@file{config.h.in} is under whatever copyright you use for your
|
|
@file{configure.in}, since it is derived from that file and from the
|
|
public domain file @file{acconfig.h}. @file{config.sub} and
|
|
@file{config.guess} have an exception to the GPL when they are used with
|
|
an Autoconf-generated @code{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, Bootstrapping, Distributing, Questions
|
|
@section Why Require GNU M4?
|
|
|
|
@display
|
|
Why does Autoconf require @sc{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
|
|
builtin
|
|
indir
|
|
patsubst
|
|
__file__
|
|
__line__
|
|
@end example
|
|
|
|
Autoconf requires version 1.4 or above of @sc{gnu} M4 because it uses
|
|
frozen state files.
|
|
|
|
Since only software maintainers need to use Autoconf, and since @sc{gnu}
|
|
M4 is simple to configure and install, it seems reasonable to require
|
|
@sc{gnu} M4 to be installed also. Many maintainers of @sc{gnu} and
|
|
other free software already have most of the @sc{gnu} utilities
|
|
installed, since they prefer them.
|
|
|
|
@node Bootstrapping, Why Not Imake, Why GNU m4, Questions
|
|
@section How Can I Bootstrap?
|
|
|
|
@display
|
|
If Autoconf requires @sc{gnu} M4 and @sc{gnu} M4 has an Autoconf
|
|
@code{configure} script, how do I bootstrap? It seems like a chicken
|
|
and egg problem!
|
|
@end display
|
|
|
|
This is a misunderstanding. Although @sc{gnu} M4 does come with a
|
|
@code{configure} script produced by Autoconf, Autoconf is not required
|
|
in order to run the script and install @sc{gnu} M4. Autoconf is only
|
|
required if you want to change the M4 @code{configure} script, which few
|
|
people have to do (mainly its maintainer).
|
|
|
|
@node Why Not Imake, , Bootstrapping, Questions
|
|
@section Why Not Imake?
|
|
|
|
@display
|
|
Why not use Imake instead of @code{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.
|
|
|
|
@sc{gnu} tools are not released this way. Each @sc{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 @sc{gnu} suite as a collection of native tools, then the
|
|
problems are similar. But the @sc{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 @sc{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
|
|
@code{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 @code{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 @code{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 @code{configure} setups.
|
|
@end quotation
|
|
|
|
|
|
|
|
|
|
@c ===================================================== History of Autoconf.
|
|
|
|
@node History, Environment Variable Index, Questions, Top
|
|
@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@dots{}
|
|
|
|
@menu
|
|
* Genesis:: Prehistory and naming of @code{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, Exodus, History, History
|
|
@section Genesis
|
|
|
|
In June 1991 I was maintaining many of the @sc{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 @code{configure} script worked well enough that
|
|
the next month I adapted it (by hand) to create similar @code{configure}
|
|
scripts for several other @sc{gnu} utilities packages. Brian Berliner
|
|
also adapted one of my scripts for his @sc{cvs} revision control system.
|
|
|
|
Later that summer, I learned that Richard Stallman and Richard Pixley
|
|
were developing similar scripts to use in the @sc{gnu} compiler tools;
|
|
so I adapted my @code{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, Leviticus, Genesis, History
|
|
@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 @sc{gnu} utilities packages to use
|
|
@code{configure} scripts, updating them all by hand became impractical.
|
|
Rich Murphey, the maintainer of the @sc{gnu} graphics utilities, sent me
|
|
mail saying that the @code{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 @code{configure} scripts to the
|
|
abundance and ease of Autoconf began.
|
|
|
|
Cygnus @code{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
|
|
@code{configure}, where there is a single @code{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 @code{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 @code{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 @code{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 @code{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 @sc{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, Numbers, Exodus, History
|
|
@section Leviticus
|
|
|
|
Since my @code{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 @file{autoconf} shell script to run @code{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 @sc{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, Deuteronomy, Leviticus, History
|
|
@section Numbers
|
|
|
|
In July 1992, after months of alpha testing, I released Autoconf 1.0,
|
|
and converted many @sc{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 @sc{gnu} Project (such as TCL, FSP, and Kerberos V5).
|
|
Autoconf continued to improve rapidly, as many people using the
|
|
@code{configure} scripts reported problems they encountered.
|
|
|
|
Autoconf turned out to be a good torture test for M4 implementations.
|
|
@sc{unix} @code{m4} started to dump core because of the length of the
|
|
macros that Autoconf defined, and several bugs showed up in @sc{gnu}
|
|
@code{m4} as well. Eventually, we realized that we needed to use some
|
|
features that only @sc{gnu} M4 has. 4.3@sc{bsd} @code{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
|
|
@sc{gnu} Emacs, laying the groundwork for several later improvements.
|
|
Roland McGrath got it to configure the @sc{gnu} C Library, wrote the
|
|
@code{autoheader} script to automate the creation of C header file
|
|
templates, and added a @option{--verbose} option to @code{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, , Numbers, History
|
|
@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
|
|
@code{configure} that Autoconf had lacked, largely by adapting the
|
|
relevant parts of Cygnus @code{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 @code{configure}
|
|
scripts in subdirectories. Adding these features enabled Ken to convert
|
|
@sc{gnu} @code{as}, and Rob Savoye to convert DejaGNU, to using
|
|
Autoconf.
|
|
|
|
I added more features in response to other peoples' requests. Many
|
|
people had asked for @code{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
|
|
@code{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 @sc{gnu} @code{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 Environment Variable Index, Output Variable Index, History, Top
|
|
@unnumbered Environment Variable Index
|
|
|
|
This is an alphabetical list of the environment variables that Autoconf
|
|
checks.
|
|
|
|
@printindex ev
|
|
|
|
@node Output Variable Index, Preprocessor Symbol Index, Environment Variable Index, Top
|
|
@unnumbered 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, Macro Index, Output Variable Index, Top
|
|
@unnumbered 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 Macro Index, Concept Index, Preprocessor Symbol Index, Top
|
|
@unnumbered Macro Index
|
|
|
|
This is an alphabetical list of the Autoconf macros. To make the list
|
|
easier to use, the macros are listed without their preceding @samp{AC_}.
|
|
|
|
@printindex ma
|
|
|
|
@node Concept Index, , Macro Index, Top
|
|
@unnumbered Concept Index
|
|
|
|
@c FIXME: Find some nice wording to introduce this section.
|
|
|
|
@printindex cp
|
|
|
|
@contents
|
|
@bye
|
|
|
|
@c Local Variables:
|
|
@c ispell-local-dictionary: "american"
|
|
@c End:
|