* lib/m4sugar/m4sh.m4 (_AS_PATH_SEPARATOR_PREPARE): Set FPATH too.
[autoconf/tsuna.git] / doc / autoconf.texi
blob1a663f6e59e9cb484de704fc2ba4d5401759a071
1 \input texinfo @c -*-texinfo-*-
2 @comment ========================================================
3 @comment %**start of header
4 @setfilename autoconf.info
5 @include version.texi
6 @settitle Autoconf
7 @setchapternewpage odd
8 @ifnothtml
9 @setcontentsaftertitlepage
10 @end ifnothtml
11 @finalout
13 @c @ovar(ARG, DEFAULT)
14 @c -------------------
15 @c The ARG is an optional argument.  To be used for macro arguments in
16 @c their documentation (@defmac).
17 @macro ovar{varname}
18 @r{[}@var{\varname\}@r{]}
19 @end macro
21 @c @dvar(ARG, DEFAULT)
22 @c -------------------
23 @c The ARG is an optional argument, defaulting to DEFAULT.  To be used
24 @c for macro arguments in their documentation (@defmac).
25 @macro dvar{varname, default}
26 @r{[}@var{\varname\} = @samp{\default\}@r{]}
27 @end macro
29 @c Handling the indexes with Texinfo yields several different problems.
31 @c Because we want to drop out the AC_ part of the macro names in the
32 @c printed manual, but not in the other outputs, we need a layer above
33 @c the usual @acindex{} etc.  That's why we first define indexes such as
34 @c acx meant to become the macro @acindex.  First of all, using ``ac_''
35 @c does not work with makeinfo, and using ``ac1'' doesn't work with TeX.
36 @c So use something more regular ``acx''.  Then you finish with a printed
37 @c index saying ``index is not existent''.  Of course: you ought to use
38 @c two letters :(  So you use capitals.
40 @c Second, when defining a macro in the TeX world, following spaces are
41 @c eaten.  But then, since we embed @acxindex commands that use the end
42 @c of line as an end marker, the whole things wrecks itself.  So make
43 @c sure you do *force* an additional end of line, add a ``@c''.
45 @c Finally, you might want to get rid of TeX expansion, using --expand
46 @c with texi2dvi.  But then you wake up an old problem: we use macros
47 @c in @defmac etc. where TeX does perform the expansion, but not makeinfo.
49 @c Define an environment variable index.
50 @defcodeindex ev
51 @c Define an output variable index.
52 @defcodeindex ov
53 @c Define a CPP variable index.
54 @defcodeindex cv
55 @c Define an Autoconf macro index that @defmac doesn't write to.
56 @defcodeindex AC
57 @c Define an Autotest macro index that @defmac doesn't write to.
58 @defcodeindex AT
59 @c Define an M4sugar macro index that @defmac doesn't write to.
60 @defcodeindex MS
61 @c Define an index for *foreign* programs: `mv' etc.  Used for the
62 @c portability sections and so on.
63 @defindex pr
65 @c shortindexflag
66 @c --------------
67 @c Shall we factor AC_ out of the Autoconf macro index etc.?
68 @iftex
69 @set shortindexflag
70 @end iftex
72 @c @acindex{MACRO}
73 @c ---------------
74 @c Registering an AC_\MACRO\.
75 @ifset shortindexflag
76 @macro acindex{macro}
77 @ACindex \macro\
79 @end macro
80 @end ifset
81 @ifclear shortindexflag
82 @macro acindex{macro}
83 @ACindex AC_\macro\
84 @end macro
85 @end ifclear
87 @c @ahindex{MACRO}
88 @c ---------------
89 @c Registering an AH_\MACRO\.
90 @macro ahindex{macro}
91 @ACindex AH_\macro\
93 @end macro
95 @c @asindex{MACRO}
96 @c ---------------
97 @c Registering an AS_\MACRO\.
98 @ifset shortindexflag
99 @macro asindex{macro}
100 @MSindex \macro\
102 @end macro
103 @end ifset
104 @ifclear shortindexflag
105 @macro asindex{macro}
106 @MSindex AS_\macro\
107 @end macro
108 @end ifclear
110 @c @atindex{MACRO}
111 @c ---------------
112 @c Registering an AT_\MACRO\.
113 @ifset shortindexflag
114 @macro atindex{macro}
115 @ATindex \macro\
117 @end macro
118 @end ifset
119 @ifclear shortindexflag
120 @macro atindex{macro}
121 @ATindex AT_\macro\
122 @end macro
123 @end ifclear
125 @c @auindex{MACRO}
126 @c ---------------
127 @c Registering an AU_\MACRO\.
128 @macro auindex{macro}
129 @ACindex AU_\macro\
131 @end macro
133 @c @hdrindex{MACRO}
134 @c ----------------
135 @c Indexing a header.
136 @macro hdrindex{macro}
137 @prindex @file{\macro\}
139 @end macro
141 @c @msindex{MACRO}
142 @c ---------------
143 @c Registering an m4_\MACRO\.
144 @ifset shortindexflag
145 @macro msindex{macro}
146 @MSindex \macro\
148 @end macro
149 @end ifset
150 @ifclear shortindexflag
151 @macro msindex{macro}
152 @MSindex m4_\macro\
153 @end macro
154 @end ifclear
157 @c Define an index for functions: `alloca' etc.  Used for the
158 @c portability sections and so on.  We can't use `fn' (aka `fnindex),
159 @c since `@defmac' goes into it => we'd get all the macros too.
161 @c   FIXME: Aaarg!  It seems there are too many indices for TeX :(
163 @c   ! No room for a new @write .
164 @c   l.112 @defcodeindex fu
166 @c   so don't define yet another one :(  Just put some tags before each
167 @c   @prindex which is actually a @funindex.
169 @c   @defcodeindex fu
172 @c   @c Put the programs and functions into their own index.
173 @c   @syncodeindex fu pr
175 @comment %**end of header
176 @comment ========================================================
178 @copying
180 This manual is for @acronym{GNU} Autoconf
181 (version @value{VERSION}, @value{UPDATED}),
182 a package for creating scripts to configure source code packages using
183 templates and an M4 macro package.
185 Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000,
186 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
188 @quotation
189 Permission is granted to copy, distribute and/or modify this document
190 under the terms of the @acronym{GNU} Free Documentation License,
191 Version 1.2 or any later version published by the Free Software
192 Foundation; with no Invariant Sections, with the Front-Cover texts
193 being ``A @acronym{GNU} Manual,'' and with the Back-Cover Texts as in
194 (a) below.  A copy of the license is included in the section entitled
195 ``@acronym{GNU} Free Documentation License.''
197 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and
198 modify this @acronym{GNU} Manual, like @acronym{GNU} software.  Copies
199 published by the Free Software Foundation raise funds for
200 @acronym{GNU} development.''
201 @end quotation
202 @end copying
206 @dircategory Software development
207 @direntry
208 * Autoconf: (autoconf).         Create source code configuration scripts.
209 @end direntry
211 @dircategory Individual utilities
212 @direntry
213 * autoscan: (autoconf)autoscan Invocation.
214                                 Semi-automatic @file{configure.ac} writing
215 * ifnames: (autoconf)ifnames Invocation.        Listing conditionals in source.
216 * autoconf-invocation: (autoconf)autoconf Invocation.
217                                 How to create configuration scripts
218 * autoreconf: (autoconf)autoreconf Invocation.
219                                 Remaking multiple @command{configure} scripts
220 * autoheader: (autoconf)autoheader Invocation.
221                                 How to create configuration templates
222 * autom4te: (autoconf)autom4te Invocation.
223                                 The Autoconf executables backbone
224 * configure: (autoconf)configure Invocation.    Configuring a package.
225 * autoupdate: (autoconf)autoupdate Invocation.
226                                 Automatic update of @file{configure.ac}
227 * config.status: (autoconf)config.status Invocation. Recreating configurations.
228 * testsuite: (autoconf)testsuite Invocation.    Running an Autotest test suite.
229 @end direntry
231 @titlepage
232 @title Autoconf
233 @subtitle Creating Automatic Configuration Scripts
234 @subtitle for version @value{VERSION}, @value{UPDATED}
235 @author David MacKenzie
236 @author Ben Elliston
237 @author Akim Demaille
238 @page
239 @vskip 0pt plus 1filll
240 @insertcopying
241 @end titlepage
243 @contents
246 @ifnottex
247 @node Top
248 @top Autoconf
249 @insertcopying
250 @end ifnottex
252 @c The master menu, created with texinfo-master-menu, goes here.
254 @menu
255 * Introduction::                Autoconf's purpose, strengths, and weaknesses
256 * The GNU Build System::        A set of tools for portable software packages
257 * Making configure Scripts::    How to organize and produce Autoconf scripts
258 * Setup::                       Initialization and output
259 * Existing Tests::              Macros that check for particular features
260 * Writing Tests::               How to write new feature checks
261 * Results::                     What to do with results from feature checks
262 * Programming in M4::           Layers on top of which Autoconf is written
263 * Writing Autoconf Macros::     Adding new macros to Autoconf
264 * Portable Shell::              Shell script portability pitfalls
265 * Portable Make::               Makefile portability pitfalls
266 * Portable C and C++::          C and C++ portability pitfalls
267 * Manual Configuration::        Selecting features that can't be guessed
268 * Site Configuration::          Local defaults for @command{configure}
269 * Running configure Scripts::   How to use the Autoconf output
270 * config.status Invocation::    Recreating a configuration
271 * Obsolete Constructs::         Kept for backward compatibility
272 * Using Autotest::              Creating portable test suites
273 * FAQ::                         Frequent Autoconf Questions, with answers
274 * History::                     History of Autoconf
275 * Copying This Manual::         How to make copies of this manual
276 * Indices::                     Indices of symbols, concepts, etc.
278 @detailmenu
279  --- The Detailed Node Listing ---
281 The @acronym{GNU} Build System
283 * Automake::                    Escaping makefile hell
284 * Gnulib::                      The @acronym{GNU} portability library
285 * Libtool::                     Building libraries portably
286 * Pointers::                    More info on the @acronym{GNU} build system
288 Making @command{configure} Scripts
290 * Writing Autoconf Input::      What to put in an Autoconf input file
291 * autoscan Invocation::         Semi-automatic @file{configure.ac} writing
292 * ifnames Invocation::          Listing the conditionals in source code
293 * autoconf Invocation::         How to create configuration scripts
294 * autoreconf Invocation::       Remaking multiple @command{configure} scripts
296 Writing @file{configure.ac}
298 * Shell Script Compiler::       Autoconf as solution of a problem
299 * Autoconf Language::           Programming in Autoconf
300 * Autoconf Input Layout::       Standard organization of @file{configure.ac}
302 Initialization and Output Files
304 * Initializing configure::      Option processing etc.
305 * Notices::                     Copyright, version numbers in @command{configure}
306 * Input::                       Where Autoconf should find files
307 * Output::                      Outputting results from the configuration
308 * Configuration Actions::       Preparing the output based on results
309 * Configuration Files::         Creating output files
310 * Makefile Substitutions::      Using output variables in makefiles
311 * Configuration Headers::       Creating a configuration header file
312 * Configuration Commands::      Running arbitrary instantiation commands
313 * Configuration Links::         Links depending on the configuration
314 * Subdirectories::              Configuring independent packages together
315 * Default Prefix::              Changing the default installation prefix
317 Substitutions in Makefiles
319 * Preset Output Variables::     Output variables that are always set
320 * Installation Directory Variables::  Other preset output variables
321 * Changed Directory Variables:: Warnings about @file{datarootdir}
322 * Build Directories::           Supporting multiple concurrent compiles
323 * Automatic Remaking::          Makefile rules for configuring
325 Configuration Header Files
327 * Header Templates::            Input for the configuration headers
328 * autoheader Invocation::       How to create configuration templates
329 * Autoheader Macros::           How to specify CPP templates
331 Existing Tests
333 * Common Behavior::             Macros' standard schemes
334 * Alternative Programs::        Selecting between alternative programs
335 * Files::                       Checking for the existence of files
336 * Libraries::                   Library archives that might be missing
337 * Library Functions::           C library functions that might be missing
338 * Header Files::                Header files that might be missing
339 * Declarations::                Declarations that may be missing
340 * Structures::                  Structures or members that might be missing
341 * Types::                       Types that might be missing
342 * Compilers and Preprocessors::  Checking for compiling programs
343 * System Services::             Operating system services
344 * Posix Variants::              Special kludges for specific Posix variants
345 * Erlang Libraries::            Checking for the existence of Erlang libraries
347 Common Behavior
349 * Standard Symbols::            Symbols defined by the macros
350 * Default Includes::            Includes used by the generic macros
352 Alternative Programs
354 * Particular Programs::         Special handling to find certain programs
355 * Generic Programs::            How to find other programs
357 Library Functions
359 * Function Portability::        Pitfalls with usual functions
360 * Particular Functions::        Special handling to find certain functions
361 * Generic Functions::           How to find other functions
363 Header Files
365 * Header Portability::          Collected knowledge on common headers
366 * Particular Headers::          Special handling to find certain headers
367 * Generic Headers::             How to find other headers
369 Declarations
371 * Particular Declarations::     Macros to check for certain declarations
372 * Generic Declarations::        How to find other declarations
374 Structures
376 * Particular Structures::       Macros to check for certain structure members
377 * Generic Structures::          How to find other structure members
379 Types
381 * Particular Types::            Special handling to find certain types
382 * Generic Types::               How to find other types
384 Compilers and Preprocessors
386 * Specific Compiler Characteristics::  Some portability issues
387 * Generic Compiler Characteristics::  Language independent tests and features
388 * C Compiler::                  Checking its characteristics
389 * C++ Compiler::                Likewise
390 * Objective C Compiler::        Likewise
391 * Erlang Compiler and Interpreter::  Likewise
392 * Fortran Compiler::            Likewise
394 Writing Tests
396 * Language Choice::             Selecting which language to use for testing
397 * Writing Test Programs::       Forging source files for compilers
398 * Running the Preprocessor::    Detecting preprocessor symbols
399 * Running the Compiler::        Detecting language or header features
400 * Running the Linker::          Detecting library features
401 * Runtime::                     Testing for runtime features
402 * Systemology::                 A zoology of operating systems
403 * Multiple Cases::              Tests for several possible values
405 Writing Test Programs
407 * Guidelines::                  General rules for writing test programs
408 * Test Functions::              Avoiding pitfalls in test programs
409 * Generating Sources::          Source program boilerplate
411 Results of Tests
413 * Defining Symbols::            Defining C preprocessor symbols
414 * Setting Output Variables::    Replacing variables in output files
415 * Special Chars in Variables::  Characters to beware of in variables
416 * Caching Results::             Speeding up subsequent @command{configure} runs
417 * Printing Messages::           Notifying @command{configure} users
419 Caching Results
421 * Cache Variable Names::        Shell variables used in caches
422 * Cache Files::                 Files @command{configure} uses for caching
423 * Cache Checkpointing::         Loading and saving the cache file
425 Programming in M4
427 * M4 Quotation::                Protecting macros from unwanted expansion
428 * Using autom4te::              The Autoconf executables backbone
429 * Programming in M4sugar::      Convenient pure M4 macros
430 * Programming in M4sh::         Common shell Constructs
431 * File Descriptor Macros::      File descriptor macros for input and output
433 M4 Quotation
435 * Active Characters::           Characters that change the behavior of M4
436 * One Macro Call::              Quotation and one macro call
437 * Quotation and Nested Macros::  Macros calling macros
438 * Changequote is Evil::         Worse than INTERCAL: M4 + changequote
439 * Quadrigraphs::                Another way to escape special characters
440 * Quotation Rule Of Thumb::     One parenthesis, one quote
442 Using @command{autom4te}
444 * autom4te Invocation::         A @acronym{GNU} M4 wrapper
445 * Customizing autom4te::        Customizing the Autoconf package
447 Programming in M4sugar
449 * Redefined M4 Macros::         M4 builtins changed in M4sugar
450 * Looping constructs::          Iteration in M4
451 * Evaluation Macros::           More quotation and evaluation control
452 * Text processing Macros::      String manipulation in M4
453 * Forbidden Patterns::          Catching unexpanded macros
455 Writing Autoconf Macros
457 * Macro Definitions::           Basic format of an Autoconf macro
458 * Macro Names::                 What to call your new macros
459 * Reporting Messages::          Notifying @command{autoconf} users
460 * Dependencies Between Macros::  What to do when macros depend on other macros
461 * Obsoleting Macros::           Warning about old ways of doing things
462 * Coding Style::                Writing Autoconf macros @`a la Autoconf
464 Dependencies Between Macros
466 * Prerequisite Macros::         Ensuring required information
467 * Suggested Ordering::          Warning about possible ordering problems
468 * One-Shot Macros::             Ensuring a macro is called only once
470 Portable Shell Programming
472 * Shellology::                  A zoology of shells
473 * Here-Documents::              Quirks and tricks
474 * File Descriptors::            FDs and redirections
475 * File System Conventions::     File names
476 * Shell Pattern Matching::      Pattern matching
477 * Shell Substitutions::         Variable and command expansions
478 * Assignments::                 Varying side effects of assignments
479 * Parentheses::                 Parentheses in shell scripts
480 * Slashes::                     Slashes in shell scripts
481 * Special Shell Variables::     Variables you should not change
482 * Limitations of Builtins::     Portable use of not so portable /bin/sh
483 * Limitations of Usual Tools::  Portable use of portable tools
485 Portable Make Programming
487 * $< in Ordinary Make Rules::   $< in ordinary rules
488 * Failure in Make Rules::       Failing portably in rules
489 * Special Chars in Names::      Special Characters in Macro Names
490 * Backslash-Newline-Newline::   Empty last lines in macro definitions
491 * Backslash-Newline Comments::  Spanning comments across line boundaries
492 * Long Lines in Makefiles::     Line length limitations
493 * Macros and Submakes::         @code{make macro=value} and submakes
494 * The Make Macro MAKEFLAGS::    @code{$(MAKEFLAGS)} portability issues
495 * The Make Macro SHELL::        @code{$(SHELL)} portability issues
496 * Comments in Make Rules::      Other problems with Make comments
497 * obj/ and Make::               Don't name a subdirectory @file{obj}
498 * make -k Status::              Exit status of @samp{make -k}
499 * VPATH and Make::              @code{VPATH} woes
500 * Single Suffix Rules::         Single suffix rules and separated dependencies
501 * Timestamps and Make::         Subsecond timestamp resolution
503 @code{VPATH} and Make
505 * VPATH and Double-colon::      Problems with @samp{::} on ancient hosts
506 * $< in Explicit Rules::        @code{$<} does not work in ordinary rules
507 * Automatic Rule Rewriting::    @code{VPATH} goes wild on Solaris
508 * Tru64 Directory Magic::       @command{mkdir} goes wild on Tru64
509 * Make Target Lookup::          More details about @code{VPATH} lookup
511 Portable C and C++ Programming
513 * Varieties of Unportability::  How to make your programs unportable
514 * Integer Overflow::            When integers get too large
515 * Null Pointers::               Properties of null pointers
516 * Buffer Overruns::             Subscript errors and the like
517 * Volatile Objects::            @code{volatile} and signals
518 * Floating Point Portability::  Portable floating-point arithmetic
519 * Exiting Portably::            Exiting and the exit status
521 Manual Configuration
523 * Specifying Names::            Specifying the system type
524 * Canonicalizing::              Getting the canonical system type
525 * Using System Type::           What to do with the system type
527 Site Configuration
529 * Help Formatting::             Customizing @samp{configure --help}
530 * External Software::           Working with other optional software
531 * Package Options::             Selecting optional features
532 * Pretty Help Strings::         Formatting help string
533 * Option Checking::             Controlling checking of @command{configure} options
534 * Site Details::                Configuring site details
535 * Transforming Names::          Changing program names when installing
536 * Site Defaults::               Giving @command{configure} local defaults
538 Transforming Program Names When Installing
540 * Transformation Options::      @command{configure} options to transform names
541 * Transformation Examples::     Sample uses of transforming names
542 * Transformation Rules::        Makefile uses of transforming names
544 Running @command{configure} Scripts
546 * Basic Installation::          Instructions for typical cases
547 * Compilers and Options::       Selecting compilers and optimization
548 * Multiple Architectures::      Compiling for multiple architectures at once
549 * Installation Names::          Installing in different directories
550 * Optional Features::           Selecting optional features
551 * System Type::                 Specifying the system type
552 * Sharing Defaults::            Setting site-wide defaults for @command{configure}
553 * Defining Variables::          Specifying the compiler etc.
554 * configure Invocation::        Changing how @command{configure} runs
556 Obsolete Constructs
558 * Obsolete config.status Use::  Obsolete convention for @command{config.status}
559 * acconfig Header::             Additional entries in @file{config.h.in}
560 * autoupdate Invocation::       Automatic update of @file{configure.ac}
561 * Obsolete Macros::             Backward compatibility macros
562 * Autoconf 1::                  Tips for upgrading your files
563 * Autoconf 2.13::               Some fresher tips
565 Upgrading From Version 1
567 * Changed File Names::          Files you might rename
568 * Changed Makefiles::           New things to put in @file{Makefile.in}
569 * Changed Macros::              Macro calls you might replace
570 * Changed Results::             Changes in how to check test results
571 * Changed Macro Writing::       Better ways to write your own macros
573 Upgrading From Version 2.13
575 * Changed Quotation::           Broken code which used to work
576 * New Macros::                  Interaction with foreign macros
577 * Hosts and Cross-Compilation::  Bugward compatibility kludges
578 * AC_LIBOBJ vs LIBOBJS::        LIBOBJS is a forbidden token
579 * AC_FOO_IFELSE vs AC_TRY_FOO::  A more generic scheme for testing sources
581 Generating Test Suites with Autotest
583 * Using an Autotest Test Suite::  Autotest and the user
584 * Writing Testsuites::          Autotest macros
585 * testsuite Invocation::        Running @command{testsuite} scripts
586 * Making testsuite Scripts::    Using autom4te to create @command{testsuite}
588 Using an Autotest Test Suite
590 * testsuite Scripts::           The concepts of Autotest
591 * Autotest Logs::               Their contents
593 Frequent Autoconf Questions, with answers
595 * Distributing::                Distributing @command{configure} scripts
596 * Why GNU M4::                  Why not use the standard M4?
597 * Bootstrapping::               Autoconf and @acronym{GNU} M4 require each other?
598 * Why Not Imake::               Why @acronym{GNU} uses @command{configure} instead of Imake
599 * Defining Directories::        Passing @code{datadir} to program
600 * Autom4te Cache::              What is it?  Can I remove it?
601 * Present But Cannot Be Compiled::  Compiler and Preprocessor Disagree
603 History of Autoconf
605 * Genesis::                     Prehistory and naming of @command{configure}
606 * Exodus::                      The plagues of M4 and Perl
607 * Leviticus::                   The priestly code of portability arrives
608 * Numbers::                     Growth and contributors
609 * Deuteronomy::                 Approaching the promises of easy configuration
611 Copying This Manual
613 * GNU Free Documentation License::  License for copying this manual
615 Indices
617 * Environment Variable Index::  Index of environment variables used
618 * Output Variable Index::       Index of variables set in output files
619 * Preprocessor Symbol Index::   Index of C preprocessor symbols defined
620 * Autoconf Macro Index::        Index of Autoconf macros
621 * M4 Macro Index::              Index of M4, M4sugar, and M4sh macros
622 * Autotest Macro Index::        Index of Autotest macros
623 * Program & Function Index::    Index of those with portability problems
624 * Concept Index::               General index
626 @end detailmenu
627 @end menu
629 @c ============================================================= Introduction.
631 @node Introduction
632 @chapter Introduction
633 @cindex Introduction
635 @flushright
636 A physicist, an engineer, and a computer scientist were discussing the
637 nature of God.  ``Surely a Physicist,'' said the physicist, ``because
638 early in the Creation, God made Light; and you know, Maxwell's
639 equations, the dual nature of electromagnetic waves, the relativistic
640 consequences@dots{}'' ``An Engineer!,'' said the engineer, ``because
641 before making Light, God split the Chaos into Land and Water; it takes a
642 hell of an engineer to handle that big amount of mud, and orderly
643 separation of solids from liquids@dots{}'' The computer scientist
644 shouted: ``And the Chaos, where do you think it was coming from, hmm?''
646 ---Anonymous
647 @end flushright
648 @c (via Franc,ois Pinard)
650 Autoconf is a tool for producing shell scripts that automatically
651 configure software source code packages to adapt to many kinds of
652 Posix-like systems.  The configuration scripts produced by Autoconf
653 are independent of Autoconf when they are run, so their users do not
654 need to have Autoconf.
656 The configuration scripts produced by Autoconf require no manual user
657 intervention when run; they do not normally even need an argument
658 specifying the system type.  Instead, they individually test for the
659 presence of each feature that the software package they are for might need.
660 (Before each check, they print a one-line message stating what they are
661 checking for, so the user doesn't get too bored while waiting for the
662 script to finish.)  As a result, they deal well with systems that are
663 hybrids or customized from the more common Posix variants.  There is
664 no need to maintain files that list the features supported by each
665 release of each variant of Posix.
667 For each software package that Autoconf is used with, it creates a
668 configuration script from a template file that lists the system features
669 that the package needs or can use.  After the shell code to recognize
670 and respond to a system feature has been written, Autoconf allows it to
671 be shared by many software packages that can use (or need) that feature.
672 If it later turns out that the shell code needs adjustment for some
673 reason, it needs to be changed in only one place; all of the
674 configuration scripts can be regenerated automatically to take advantage
675 of the updated code.
677 The Metaconfig package is similar in purpose to Autoconf, but the
678 scripts it produces require manual user intervention, which is quite
679 inconvenient when configuring large source trees.  Unlike Metaconfig
680 scripts, Autoconf scripts can support cross-compiling, if some care is
681 taken in writing them.
683 Autoconf does not solve all problems related to making portable
684 software packages---for a more complete solution, it should be used in
685 concert with other @acronym{GNU} build tools like Automake and
686 Libtool.  These other tools take on jobs like the creation of a
687 portable, recursive makefile with all of the standard targets,
688 linking of shared libraries, and so on.  @xref{The GNU Build System},
689 for more information.
691 Autoconf imposes some restrictions on the names of macros used with
692 @code{#if} in C programs (@pxref{Preprocessor Symbol Index}).
694 Autoconf requires @acronym{GNU} M4 version 1.4.5 or later in order to
695 generate the scripts.  It uses features that some versions of M4,
696 including @acronym{GNU} M4 1.3, do not have.  Autoconf works better
697 with @acronym{GNU} M4 version 1.4.8 or later, though this is not
698 required.
700 @xref{Autoconf 1}, for information about upgrading from version 1.
701 @xref{History}, for the story of Autoconf's development.  @xref{FAQ},
702 for answers to some common questions about Autoconf.
704 See the @uref{http://www.gnu.org/software/autoconf/,
705 Autoconf web page} for up-to-date information, details on the mailing
706 lists, pointers to a list of known bugs, etc.
708 Mail suggestions to @email{autoconf@@gnu.org, the Autoconf mailing
709 list}.  Past suggestions are
710 @uref{http://lists.gnu.org/archive/html/autoconf/, archived}.
712 Mail bug reports to @email{bug-autoconf@@gnu.org, the
713 Autoconf Bugs mailing list}.  Past bug reports are
714 @uref{http://lists.gnu.org/archive/html/bug-autoconf/, archived}.
716 If possible, first check that your bug is
717 not already solved in current development versions, and that it has not
718 been reported yet.  Be sure to include all the needed information and a
719 short @file{configure.ac} that demonstrates the problem.
721 Autoconf's development tree is accessible via anonymous @acronym{CVS}; see the
722 @uref{http://savannah.gnu.org/projects/autoconf/, Autoconf
723 Summary} for details.  Patches relative to the
724 current @acronym{CVS} version can be sent for review to the
725 @email{autoconf-patches@@gnu.org, Autoconf Patches mailing list}.
726 Past patches are
727 @uref{http://lists.gnu.org/@/archive/@/html/@/autoconf-patches/, archived}.
729 Because of its mission, the Autoconf package itself
730 includes only a set of often-used
731 macros that have already demonstrated their usefulness.  Nevertheless,
732 if you wish to share your macros, or find existing ones, see the
733 @uref{http://autoconf-archive.cryp.to/, Autoconf Macro
734 Archive}, which is kindly run by @email{simons@@cryp.to,
735 Peter Simons}.
738 @c ================================================= The GNU Build System
740 @node The GNU Build System
741 @chapter The @acronym{GNU} Build System
742 @cindex @acronym{GNU} build system
744 Autoconf solves an important problem---reliable discovery of
745 system-specific build and runtime information---but this is only one
746 piece of the puzzle for the development of portable software.  To this
747 end, the @acronym{GNU} project has developed a suite of integrated
748 utilities to finish the job Autoconf started: the @acronym{GNU} build
749 system, whose most important components are Autoconf, Automake, and
750 Libtool.  In this chapter, we introduce you to those tools, point you
751 to sources of more information, and try to convince you to use the
752 entire @acronym{GNU} build system for your software.
754 @menu
755 * Automake::                    Escaping makefile hell
756 * Gnulib::                      The @acronym{GNU} portability library
757 * Libtool::                     Building libraries portably
758 * Pointers::                    More info on the @acronym{GNU} build system
759 @end menu
761 @node Automake
762 @section Automake
764 The ubiquity of @command{make} means that a makefile is almost the
765 only viable way to distribute automatic build rules for software, but
766 one quickly runs into its numerous limitations.  Its lack of
767 support for automatic dependency tracking, recursive builds in
768 subdirectories, reliable timestamps (e.g., for network file systems), and
769 so on, mean that developers must painfully (and often incorrectly)
770 reinvent the wheel for each project.  Portability is non-trivial, thanks
771 to the quirks of @command{make} on many systems.  On top of all this is the
772 manual labor required to implement the many standard targets that users
773 have come to expect (@code{make install}, @code{make distclean},
774 @code{make uninstall}, etc.).  Since you are, of course, using Autoconf,
775 you also have to insert repetitive code in your @code{Makefile.in} to
776 recognize @code{@@CC@@}, @code{@@CFLAGS@@}, and other substitutions
777 provided by @command{configure}.  Into this mess steps @dfn{Automake}.
778 @cindex Automake
780 Automake allows you to specify your build needs in a @code{Makefile.am}
781 file with a vastly simpler and more powerful syntax than that of a plain
782 makefile, and then generates a portable @code{Makefile.in} for
783 use with Autoconf.  For example, the @code{Makefile.am} to build and
784 install a simple ``Hello world'' program might look like:
786 @example
787 bin_PROGRAMS = hello
788 hello_SOURCES = hello.c
789 @end example
791 @noindent
792 The resulting @code{Makefile.in} (~400 lines) automatically supports all
793 the standard targets, the substitutions provided by Autoconf, automatic
794 dependency tracking, @code{VPATH} building, and so on.  @command{make}
795 builds the @code{hello} program, and @code{make install} installs it
796 in @file{/usr/local/bin} (or whatever prefix was given to
797 @command{configure}, if not @file{/usr/local}).
799 The benefits of Automake increase for larger packages (especially ones
800 with subdirectories), but even for small programs the added convenience
801 and portability can be substantial.  And that's not all@enddots{}
803 @node Gnulib
804 @section Gnulib
806 @acronym{GNU} software has a well-deserved reputation for running on
807 many different types of systems.  While our primary goal is to write
808 software for the @acronym{GNU} system, many users and developers have
809 been introduced to us through the systems that they were already using.
811 @cindex Gnulib
812 Gnulib is a central location for common @acronym{GNU} code, intended to
813 be shared among free software packages.  Its components are typically
814 shared at the source level, rather than being a library that gets built,
815 installed, and linked against.  The idea is to copy files from Gnulib
816 into your own source tree.  There is no distribution tarball; developers
817 should just grab source modules from the repository.  The source files
818 are available online, under various licenses, mostly @acronym{GNU}
819 @acronym{GPL} or @acronym{GNU} @acronym{LGPL}.
821 Gnulib modules typically contain C source code along with Autoconf
822 macros used to configure the source code.  For example, the Gnulib
823 @code{stdbool} module implements a @file{stdbool.h} header that nearly
824 conforms to C99, even on old-fashioned hosts that lack @file{stdbool.h}.
825 This module contains a source file for the replacement header, along
826 with an Autoconf macro that arranges to use the replacement header on
827 old-fashioned systems.
829 @node Libtool
830 @section Libtool
832 Often, one wants to build not only programs, but libraries, so that
833 other programs can benefit from the fruits of your labor.  Ideally, one
834 would like to produce @emph{shared} (dynamically linked) libraries,
835 which can be used by multiple programs without duplication on disk or in
836 memory and can be updated independently of the linked programs.
837 Producing shared libraries portably, however, is the stuff of
838 nightmares---each system has its own incompatible tools, compiler flags,
839 and magic incantations.  Fortunately, @acronym{GNU} provides a solution:
840 @dfn{Libtool}.
841 @cindex Libtool
843 Libtool handles all the requirements of building shared libraries for
844 you, and at this time seems to be the @emph{only} way to do so with any
845 portability.  It also handles many other headaches, such as: the
846 interaction of Make rules with the variable suffixes of
847 shared libraries, linking reliably with shared libraries before they are
848 installed by the superuser, and supplying a consistent versioning system
849 (so that different versions of a library can be installed or upgraded
850 without breaking binary compatibility).  Although Libtool, like
851 Autoconf, can be used without Automake, it is most simply utilized in
852 conjunction with Automake---there, Libtool is used automatically
853 whenever shared libraries are needed, and you need not know its syntax.
855 @node Pointers
856 @section Pointers
858 Developers who are used to the simplicity of @command{make} for small
859 projects on a single system might be daunted at the prospect of
860 learning to use Automake and Autoconf.  As your software is
861 distributed to more and more users, however, you otherwise
862 quickly find yourself putting lots of effort into reinventing the
863 services that the @acronym{GNU} build tools provide, and making the
864 same mistakes that they once made and overcame.  (Besides, since
865 you're already learning Autoconf, Automake is a piece of cake.)
867 There are a number of places that you can go to for more information on
868 the @acronym{GNU} build tools.
870 @itemize @minus
872 @item Web
874 The home pages for
875 @uref{http://www.gnu.org/@/software/@/autoconf/, Autoconf},
876 @uref{http://www.gnu.org/@/software/@/automake/, Automake},
877 @uref{http://www.gnu.org/@/software/@/gnulib/, Gnulib}, and
878 @uref{http://www.gnu.org/@/software/@/libtool/, Libtool}.
880 @item Automake Manual
882 @xref{Top, , Automake, automake, @acronym{GNU} Automake}, for more
883 information on Automake.
885 @item Books
887 The book @cite{@acronym{GNU} Autoconf, Automake and
888 Libtool}@footnote{@cite{@acronym{GNU} Autoconf, Automake and Libtool},
889 by G. V. Vaughan, B. Elliston, T. Tromey, and I. L. Taylor.  SAMS (originally
890 New Riders), 2000, ISBN 1578701902.} describes the complete @acronym{GNU}
891 build environment.  You can also find
892 @uref{http://sources.redhat.com/@/autobook/, the entire book on-line}.
894 @end itemize
896 @c ================================================= Making configure Scripts.
898 @node Making configure Scripts
899 @chapter Making @command{configure} Scripts
900 @cindex @file{aclocal.m4}
901 @cindex @command{configure}
903 The configuration scripts that Autoconf produces are by convention
904 called @command{configure}.  When run, @command{configure} creates several
905 files, replacing configuration parameters in them with appropriate
906 values.  The files that @command{configure} creates are:
908 @itemize @minus
909 @item
910 one or more @file{Makefile} files, usually one in each subdirectory of the
911 package (@pxref{Makefile Substitutions});
913 @item
914 optionally, a C header file, the name of which is configurable,
915 containing @code{#define} directives (@pxref{Configuration Headers});
917 @item
918 a shell script called @file{config.status} that, when run, recreates
919 the files listed above (@pxref{config.status Invocation});
921 @item
922 an optional shell script normally called @file{config.cache}
923 (created when using @samp{configure --config-cache}) that
924 saves the results of running many of the tests (@pxref{Cache Files});
926 @item
927 a file called @file{config.log} containing any messages produced by
928 compilers, to help debugging if @command{configure} makes a mistake.
929 @end itemize
931 @cindex @file{configure.in}
932 @cindex @file{configure.ac}
933 To create a @command{configure} script with Autoconf, you need to write an
934 Autoconf input file @file{configure.ac} (or @file{configure.in}) and run
935 @command{autoconf} on it.  If you write your own feature tests to
936 supplement those that come with Autoconf, you might also write files
937 called @file{aclocal.m4} and @file{acsite.m4}.  If you use a C header
938 file to contain @code{#define} directives, you might also run
939 @command{autoheader}, and you can distribute the generated file
940 @file{config.h.in} with the package.
942 Here is a diagram showing how the files that can be used in
943 configuration are produced.  Programs that are executed are suffixed by
944 @samp{*}.  Optional files are enclosed in square brackets (@samp{[]}).
945 @command{autoconf} and @command{autoheader} also read the installed Autoconf
946 macro files (by reading @file{autoconf.m4}).
948 @noindent
949 Files used in preparing a software package for distribution:
950 @example
951 your source files --> [autoscan*] --> [configure.scan] --> configure.ac
953 @group
954 configure.ac --.
955                |   .------> autoconf* -----> configure
956 [aclocal.m4] --+---+
957                |   `-----> [autoheader*] --> [config.h.in]
958 [acsite.m4] ---'
959 @end group
961 Makefile.in -------------------------------> Makefile.in
962 @end example
964 @noindent
965 Files used in configuring a software package:
966 @example
967 @group
968                        .-------------> [config.cache]
969 configure* ------------+-------------> config.log
970                        |
971 [config.h.in] -.       v            .-> [config.h] -.
972                +--> config.status* -+               +--> make*
973 Makefile.in ---'                    `-> Makefile ---'
974 @end group
975 @end example
977 @menu
978 * Writing Autoconf Input::      What to put in an Autoconf input file
979 * autoscan Invocation::         Semi-automatic @file{configure.ac} writing
980 * ifnames Invocation::          Listing the conditionals in source code
981 * autoconf Invocation::         How to create configuration scripts
982 * autoreconf Invocation::       Remaking multiple @command{configure} scripts
983 @end menu
985 @node Writing Autoconf Input
986 @section Writing @file{configure.ac}
988 To produce a @command{configure} script for a software package, create a
989 file called @file{configure.ac} that contains invocations of the
990 Autoconf macros that test the system features your package needs or can
991 use.  Autoconf macros already exist to check for many features; see
992 @ref{Existing Tests}, for their descriptions.  For most other features,
993 you can use Autoconf template macros to produce custom checks; see
994 @ref{Writing Tests}, for information about them.  For especially tricky
995 or specialized features, @file{configure.ac} might need to contain some
996 hand-crafted shell commands; see @ref{Portable Shell}.  The
997 @command{autoscan} program can give you a good start in writing
998 @file{configure.ac} (@pxref{autoscan Invocation}, for more information).
1000 Previous versions of Autoconf promoted the name @file{configure.in},
1001 which is somewhat ambiguous (the tool needed to process this file is not
1002 described by its extension), and introduces a slight confusion with
1003 @file{config.h.in} and so on (for which @samp{.in} means ``to be
1004 processed by @command{configure}'').  Using @file{configure.ac} is now
1005 preferred.
1007 @menu
1008 * Shell Script Compiler::       Autoconf as solution of a problem
1009 * Autoconf Language::           Programming in Autoconf
1010 * Autoconf Input Layout::       Standard organization of @file{configure.ac}
1011 @end menu
1013 @node Shell Script Compiler
1014 @subsection A Shell Script Compiler
1016 Just as for any other computer language, in order to properly program
1017 @file{configure.ac} in Autoconf you must understand @emph{what} problem
1018 the language tries to address and @emph{how} it does so.
1020 The problem Autoconf addresses is that the world is a mess.  After all,
1021 you are using Autoconf in order to have your package compile easily on
1022 all sorts of different systems, some of them being extremely hostile.
1023 Autoconf itself bears the price for these differences: @command{configure}
1024 must run on all those systems, and thus @command{configure} must limit itself
1025 to their lowest common denominator of features.
1027 Naturally, you might then think of shell scripts; who needs
1028 @command{autoconf}?  A set of properly written shell functions is enough to
1029 make it easy to write @command{configure} scripts by hand.  Sigh!
1030 Unfortunately, shell functions do not belong to the least common
1031 denominator; therefore, where you would like to define a function and
1032 use it ten times, you would instead need to copy its body ten times.
1034 So, what is really needed is some kind of compiler, @command{autoconf},
1035 that takes an Autoconf program, @file{configure.ac}, and transforms it
1036 into a portable shell script, @command{configure}.
1038 How does @command{autoconf} perform this task?
1040 There are two obvious possibilities: creating a brand new language or
1041 extending an existing one.  The former option is attractive: all
1042 sorts of optimizations could easily be implemented in the compiler and
1043 many rigorous checks could be performed on the Autoconf program
1044 (e.g., rejecting any non-portable construct).  Alternatively, you can
1045 extend an existing language, such as the @code{sh} (Bourne shell)
1046 language.
1048 Autoconf does the latter: it is a layer on top of @code{sh}.  It was
1049 therefore most convenient to implement @command{autoconf} as a macro
1050 expander: a program that repeatedly performs @dfn{macro expansions} on
1051 text input, replacing macro calls with macro bodies and producing a pure
1052 @code{sh} script in the end.  Instead of implementing a dedicated
1053 Autoconf macro expander, it is natural to use an existing
1054 general-purpose macro language, such as M4, and implement the extensions
1055 as a set of M4 macros.
1058 @node Autoconf Language
1059 @subsection The Autoconf Language
1060 @cindex quotation
1062 The Autoconf language differs from many other computer
1063 languages because it treats actual code the same as plain text.  Whereas
1064 in C, for instance, data and instructions have different syntactic
1065 status, in Autoconf their status is rigorously the same.  Therefore, we
1066 need a means to distinguish literal strings from text to be expanded:
1067 quotation.
1069 When calling macros that take arguments, there must not be any white
1070 space between the macro name and the open parenthesis.  Arguments should
1071 be enclosed within the M4 quote characters @samp{[} and @samp{]}, and be
1072 separated by commas.  Any leading blanks or newlines in arguments are ignored,
1073 unless they are quoted.  You should always quote an argument that
1074 might contain a macro name, comma, parenthesis, or a leading blank or
1075 newline.  This rule applies recursively for every macro
1076 call, including macros called from other macros.
1078 For instance:
1080 @example
1081 AC_CHECK_HEADER([stdio.h],
1082                 [AC_DEFINE([HAVE_STDIO_H], [1],
1083                    [Define to 1 if you have <stdio.h>.])],
1084                 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1085 @end example
1087 @noindent
1088 is quoted properly.  You may safely simplify its quotation to:
1090 @example
1091 AC_CHECK_HEADER([stdio.h],
1092                 [AC_DEFINE([HAVE_STDIO_H], 1,
1093                    [Define to 1 if you have <stdio.h>.])],
1094                 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1095 @end example
1097 @noindent
1098 because @samp{1} cannot contain a macro call.  Here, the argument of
1099 @code{AC_MSG_ERROR} must be quoted; otherwise, its comma would be
1100 interpreted as an argument separator.  Also, the second and third arguments
1101 of @samp{AC_CHECK_HEADER} must be quoted, since they contain
1102 macro calls.  The three arguments @samp{HAVE_STDIO_H}, @samp{stdio.h},
1103 and @samp{Define to 1 if you have <stdio.h>.} do not need quoting, but
1104 if you unwisely defined a macro with a name like @samp{Define} or
1105 @samp{stdio} then they would need quoting.  Cautious Autoconf users
1106 would keep the quotes, but many Autoconf users find such precautions
1107 annoying, and would rewrite the example as follows:
1109 @example
1110 AC_CHECK_HEADER(stdio.h,
1111                 [AC_DEFINE(HAVE_STDIO_H, 1,
1112                    [Define to 1 if you have <stdio.h>.])],
1113                 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1114 @end example
1116 @noindent
1117 This is safe, so long as you adopt good naming conventions and do not
1118 define macros with names like @samp{HAVE_STDIO_H}, @samp{stdio}, or
1119 @samp{h}.  Though it is also safe here to omit the quotes around
1120 @samp{Define to 1 if you have <stdio.h>.} this is not recommended, as
1121 message strings are more likely to inadvertently contain commas.
1123 The following example is wrong and dangerous, as it is underquoted:
1125 @example
1126 AC_CHECK_HEADER(stdio.h,
1127                 AC_DEFINE(HAVE_STDIO_H, 1,
1128                    Define to 1 if you have <stdio.h>.),
1129                 AC_MSG_ERROR([Sorry, can't do anything for you]))
1130 @end example
1132 In other cases, you may have to use text that also resembles a macro
1133 call.  You must quote that text even when it is not passed as a macro
1134 argument:
1136 @example
1137 echo "Hard rock was here!  --[AC_DC]"
1138 @end example
1140 @noindent
1141 which results in:
1143 @example
1144 echo "Hard rock was here!  --AC_DC"
1145 @end example
1147 @noindent
1148 When you use the same text in a macro argument, you must therefore have
1149 an extra quotation level (since one is stripped away by the macro
1150 substitution).  In general, then, it is a good idea to @emph{use double
1151 quoting for all literal string arguments}:
1153 @example
1154 AC_MSG_WARN([[AC_DC stinks  --Iron Maiden]])
1155 @end example
1157 You are now able to understand one of the constructs of Autoconf that
1158 has been continually misunderstood@dots{}  The rule of thumb is that
1159 @emph{whenever you expect macro expansion, expect quote expansion};
1160 i.e., expect one level of quotes to be lost.  For instance:
1162 @example
1163 AC_COMPILE_IFELSE([char b[10];], [], [AC_MSG_ERROR([you lose])])
1164 @end example
1166 @noindent
1167 is incorrect: here, the first argument of @code{AC_COMPILE_IFELSE} is
1168 @samp{char b[10];} and is expanded once, which results in
1169 @samp{char b10;}.  (There was an idiom common in Autoconf's past to
1170 address this issue via the M4 @code{changequote} primitive, but do not
1171 use it!)  Let's take a closer look: the author meant the first argument
1172 to be understood as a literal, and therefore it must be quoted twice:
1174 @example
1175 AC_COMPILE_IFELSE([[char b[10];]], [], [AC_MSG_ERROR([you lose])])
1176 @end example
1178 @noindent
1179 Voil@`a, you actually produce @samp{char b[10];} this time!
1181 On the other hand, descriptions (e.g., the last parameter of
1182 @code{AC_DEFINE} or @code{AS_HELP_STRING}) are not literals---they
1183 are subject to line breaking, for example---and should not be double quoted.
1184 Even if these descriptions are short and are not actually broken, double
1185 quoting them yields weird results.
1187 Some macros take optional arguments, which this documentation represents
1188 as @ovar{arg} (not to be confused with the quote characters).  You may
1189 just leave them empty, or use @samp{[]} to make the emptiness of the
1190 argument explicit, or you may simply omit the trailing commas.  The
1191 three lines below are equivalent:
1193 @example
1194 AC_CHECK_HEADERS([stdio.h], [], [], [])
1195 AC_CHECK_HEADERS([stdio.h],,,)
1196 AC_CHECK_HEADERS([stdio.h])
1197 @end example
1199 It is best to put each macro call on its own line in
1200 @file{configure.ac}.  Most of the macros don't add extra newlines; they
1201 rely on the newline after the macro call to terminate the commands.
1202 This approach makes the generated @command{configure} script a little
1203 easier to read by not inserting lots of blank lines.  It is generally
1204 safe to set shell variables on the same line as a macro call, because
1205 the shell allows assignments without intervening newlines.
1207 You can include comments in @file{configure.ac} files by starting them
1208 with the @samp{#}.  For example, it is helpful to begin
1209 @file{configure.ac} files with a line like this:
1211 @example
1212 # Process this file with autoconf to produce a configure script.
1213 @end example
1215 @node Autoconf Input Layout
1216 @subsection Standard @file{configure.ac} Layout
1218 The order in which @file{configure.ac} calls the Autoconf macros is not
1219 important, with a few exceptions.  Every @file{configure.ac} must
1220 contain a call to @code{AC_INIT} before the checks, and a call to
1221 @code{AC_OUTPUT} at the end (@pxref{Output}).  Additionally, some macros
1222 rely on other macros having been called first, because they check
1223 previously set values of some variables to decide what to do.  These
1224 macros are noted in the individual descriptions (@pxref{Existing
1225 Tests}), and they also warn you when @command{configure} is created if they
1226 are called out of order.
1228 To encourage consistency, here is a suggested order for calling the
1229 Autoconf macros.  Generally speaking, the things near the end of this
1230 list are those that could depend on things earlier in it.  For example,
1231 library functions could be affected by types and libraries.
1233 @display
1234 @group
1235 Autoconf requirements
1236 @code{AC_INIT(@var{package}, @var{version}, @var{bug-report-address})}
1237 information on the package
1238 checks for programs
1239 checks for libraries
1240 checks for header files
1241 checks for types
1242 checks for structures
1243 checks for compiler characteristics
1244 checks for library functions
1245 checks for system services
1246 @code{AC_CONFIG_FILES(@r{[}@var{file@dots{}}@r{]})}
1247 @code{AC_OUTPUT}
1248 @end group
1249 @end display
1252 @node autoscan Invocation
1253 @section Using @command{autoscan} to Create @file{configure.ac}
1254 @cindex @command{autoscan}
1256 The @command{autoscan} program can help you create and/or maintain a
1257 @file{configure.ac} file for a software package.  @command{autoscan}
1258 examines source files in the directory tree rooted at a directory given
1259 as a command line argument, or the current directory if none is given.
1260 It searches the source files for common portability problems and creates
1261 a file @file{configure.scan} which is a preliminary @file{configure.ac}
1262 for that package, and checks a possibly existing @file{configure.ac} for
1263 completeness.
1265 When using @command{autoscan} to create a @file{configure.ac}, you
1266 should manually examine @file{configure.scan} before renaming it to
1267 @file{configure.ac}; it probably needs some adjustments.
1268 Occasionally, @command{autoscan} outputs a macro in the wrong order
1269 relative to another macro, so that @command{autoconf} produces a warning;
1270 you need to move such macros manually.  Also, if you want the package to
1271 use a configuration header file, you must add a call to
1272 @code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers}).  You might
1273 also have to change or add some @code{#if} directives to your program in
1274 order to make it work with Autoconf (@pxref{ifnames Invocation}, for
1275 information about a program that can help with that job).
1277 When using @command{autoscan} to maintain a @file{configure.ac}, simply
1278 consider adding its suggestions.  The file @file{autoscan.log}
1279 contains detailed information on why a macro is requested.
1281 @command{autoscan} uses several data files (installed along with Autoconf)
1282 to determine which macros to output when it finds particular symbols in
1283 a package's source files.  These data files all have the same format:
1284 each line consists of a symbol, one or more blanks, and the Autoconf macro to
1285 output if that symbol is encountered.  Lines starting with @samp{#} are
1286 comments.
1288 @command{autoscan} accepts the following options:
1290 @table @option
1291 @item --help
1292 @itemx -h
1293 Print a summary of the command line options and exit.
1295 @item --version
1296 @itemx -V
1297 Print the version number of Autoconf and exit.
1299 @item --verbose
1300 @itemx -v
1301 Print the names of the files it examines and the potentially interesting
1302 symbols it finds in them.  This output can be voluminous.
1304 @item --include=@var{dir}
1305 @itemx -I @var{dir}
1306 Append @var{dir} to the include path.  Multiple invocations accumulate.
1308 @item --prepend-include=@var{dir}
1309 @item -B @var{dir}
1310 Prepend @var{dir} to the include path.  Multiple invocations accumulate.
1311 @end table
1313 @node ifnames Invocation
1314 @section Using @command{ifnames} to List Conditionals
1315 @cindex @command{ifnames}
1317 @command{ifnames} can help you write @file{configure.ac} for a software
1318 package.  It prints the identifiers that the package already uses in C
1319 preprocessor conditionals.  If a package has already been set up to have
1320 some portability, @command{ifnames} can thus help you figure out what its
1321 @command{configure} needs to check for.  It may help fill in some gaps in a
1322 @file{configure.ac} generated by @command{autoscan} (@pxref{autoscan
1323 Invocation}).
1325 @command{ifnames} scans all of the C source files named on the command line
1326 (or the standard input, if none are given) and writes to the standard
1327 output a sorted list of all the identifiers that appear in those files
1328 in @code{#if}, @code{#elif}, @code{#ifdef}, or @code{#ifndef}
1329 directives.  It prints each identifier on a line, followed by a
1330 space-separated list of the files in which that identifier occurs.
1332 @noindent
1333 @command{ifnames} accepts the following options:
1335 @table @option
1336 @item --help
1337 @itemx -h
1338 Print a summary of the command line options and exit.
1340 @item --version
1341 @itemx -V
1342 Print the version number of Autoconf and exit.
1343 @end table
1345 @node autoconf Invocation
1346 @section Using @command{autoconf} to Create @command{configure}
1347 @cindex @command{autoconf}
1349 To create @command{configure} from @file{configure.ac}, run the
1350 @command{autoconf} program with no arguments.  @command{autoconf} processes
1351 @file{configure.ac} with the M4 macro processor, using the
1352 Autoconf macros.  If you give @command{autoconf} an argument, it reads that
1353 file instead of @file{configure.ac} and writes the configuration script
1354 to the standard output instead of to @command{configure}.  If you give
1355 @command{autoconf} the argument @option{-}, it reads from the standard
1356 input instead of @file{configure.ac} and writes the configuration script
1357 to the standard output.
1359 The Autoconf macros are defined in several files.  Some of the files are
1360 distributed with Autoconf; @command{autoconf} reads them first.  Then it
1361 looks for the optional file @file{acsite.m4} in the directory that
1362 contains the distributed Autoconf macro files, and for the optional file
1363 @file{aclocal.m4} in the current directory.  Those files can contain
1364 your site's or the package's own Autoconf macro definitions
1365 (@pxref{Writing Autoconf Macros}, for more information).  If a macro is
1366 defined in more than one of the files that @command{autoconf} reads, the
1367 last definition it reads overrides the earlier ones.
1369 @command{autoconf} accepts the following options:
1371 @table @option
1372 @item --help
1373 @itemx -h
1374 Print a summary of the command line options and exit.
1376 @item --version
1377 @itemx -V
1378 Print the version number of Autoconf and exit.
1380 @item --verbose
1381 @itemx -v
1382 Report processing steps.
1384 @item --debug
1385 @itemx -d
1386 Don't remove the temporary files.
1388 @item --force
1389 @itemx -f
1390 Remake @file{configure} even if newer than its input files.
1392 @item --include=@var{dir}
1393 @itemx -I @var{dir}
1394 Append @var{dir} to the include path.  Multiple invocations accumulate.
1396 @item --prepend-include=@var{dir}
1397 @item -B @var{dir}
1398 Prepend @var{dir} to the include path.  Multiple invocations accumulate.
1400 @item --output=@var{file}
1401 @itemx -o @var{file}
1402 Save output (script or trace) to @var{file}.  The file @option{-} stands
1403 for the standard output.
1405 @item --warnings=@var{category}
1406 @itemx -W @var{category}
1407 @evindex WARNINGS
1408 Report the warnings related to @var{category} (which can actually be a
1409 comma separated list).  @xref{Reporting Messages}, macro
1410 @code{AC_DIAGNOSE}, for a comprehensive list of categories.  Special
1411 values include:
1413 @table @samp
1414 @item all
1415 report all the warnings
1417 @item none
1418 report none
1420 @item error
1421 treats warnings as errors
1423 @item no-@var{category}
1424 disable warnings falling into @var{category}
1425 @end table
1427 Warnings about @samp{syntax} are enabled by default, and the environment
1428 variable @env{WARNINGS}, a comma separated list of categories, is
1429 honored as well.  Passing @option{-W @var{category}} actually behaves as if
1430 you had passed @option{--warnings=syntax,$WARNINGS,@var{category}}.  If
1431 you want to disable the defaults and @env{WARNINGS}, but (for example)
1432 enable the warnings about obsolete constructs, you would use @option{-W
1433 none,obsolete}.
1435 @cindex Back trace
1436 @cindex Macro invocation stack
1437 Because @command{autoconf} uses @command{autom4te} behind the scenes, it
1438 displays a back trace for errors, but not for warnings; if you want
1439 them, just pass @option{-W error}.  @xref{autom4te Invocation}, for some
1440 examples.
1442 @item --trace=@var{macro}[:@var{format}]
1443 @itemx -t @var{macro}[:@var{format}]
1444 Do not create the @command{configure} script, but list the calls to
1445 @var{macro} according to the @var{format}.  Multiple @option{--trace}
1446 arguments can be used to list several macros.  Multiple @option{--trace}
1447 arguments for a single macro are not cumulative; instead, you should
1448 just make @var{format} as long as needed.
1450 The @var{format} is a regular string, with newlines if desired, and
1451 several special escape codes.  It defaults to @samp{$f:$l:$n:$%}; see
1452 @ref{autom4te Invocation}, for details on the @var{format}.
1454 @item --initialization
1455 @itemx -i
1456 By default, @option{--trace} does not trace the initialization of the
1457 Autoconf macros (typically the @code{AC_DEFUN} definitions).  This
1458 results in a noticeable speedup, but can be disabled by this option.
1459 @end table
1462 It is often necessary to check the content of a @file{configure.ac}
1463 file, but parsing it yourself is extremely fragile and error-prone.  It
1464 is suggested that you rely upon @option{--trace} to scan
1465 @file{configure.ac}.  For instance, to find the list of variables that
1466 are substituted, use:
1468 @example
1469 @group
1470 $ @kbd{autoconf -t AC_SUBST}
1471 configure.ac:2:AC_SUBST:ECHO_C
1472 configure.ac:2:AC_SUBST:ECHO_N
1473 configure.ac:2:AC_SUBST:ECHO_T
1474 @i{More traces deleted}
1475 @end group
1476 @end example
1478 @noindent
1479 The example below highlights the difference between @samp{$@@},
1480 @samp{$*}, and @samp{$%}.
1482 @example
1483 @group
1484 $ @kbd{cat configure.ac}
1485 AC_DEFINE(This, is, [an
1486 [example]])
1487 $ @kbd{autoconf -t 'AC_DEFINE:@@: $@@}
1488 *: $*
1489 %: $%'
1490 @@: [This],[is],[an
1491 [example]]
1492 *: This,is,an
1493 [example]
1494 %: This:is:an [example]
1495 @end group
1496 @end example
1498 @noindent
1499 The @var{format} gives you a lot of freedom:
1501 @example
1502 @group
1503 $ @kbd{autoconf -t 'AC_SUBST:$$ac_subst@{"$1"@} = "$f:$l";'}
1504 $ac_subst@{"ECHO_C"@} = "configure.ac:2";
1505 $ac_subst@{"ECHO_N"@} = "configure.ac:2";
1506 $ac_subst@{"ECHO_T"@} = "configure.ac:2";
1507 @i{More traces deleted}
1508 @end group
1509 @end example
1511 @noindent
1512 A long @var{separator} can be used to improve the readability of complex
1513 structures, and to ease their parsing (for instance when no single
1514 character is suitable as a separator):
1516 @example
1517 @group
1518 $ @kbd{autoconf -t 'AM_MISSING_PROG:$@{|:::::|@}*'}
1519 ACLOCAL|:::::|aclocal|:::::|$missing_dir
1520 AUTOCONF|:::::|autoconf|:::::|$missing_dir
1521 AUTOMAKE|:::::|automake|:::::|$missing_dir
1522 @i{More traces deleted}
1523 @end group
1524 @end example
1526 @node autoreconf Invocation
1527 @section Using @command{autoreconf} to Update @command{configure} Scripts
1528 @cindex @command{autoreconf}
1530 Installing the various components of the @acronym{GNU} Build System can be
1531 tedious: running @command{autopoint} for Gettext, @command{automake} for
1532 @file{Makefile.in} etc.@: in each directory.  It may be needed either
1533 because some tools such as @command{automake} have been updated on your
1534 system, or because some of the sources such as @file{configure.ac} have
1535 been updated, or finally, simply in order to install the @acronym{GNU} Build
1536 System in a fresh tree.
1538 @command{autoreconf} runs @command{autoconf}, @command{autoheader},
1539 @command{aclocal}, @command{automake}, @command{libtoolize}, and
1540 @command{autopoint} (when appropriate) repeatedly to update the
1541 @acronym{GNU} Build System in the specified directories and their
1542 subdirectories (@pxref{Subdirectories}).  By default, it only remakes
1543 those files that are older than their sources.
1545 If you install a new version of some tool, you can make
1546 @command{autoreconf} remake @emph{all} of the files by giving it the
1547 @option{--force} option.
1549 @xref{Automatic Remaking}, for Make rules to automatically
1550 remake @command{configure} scripts when their source files change.  That
1551 method handles the timestamps of configuration header templates
1552 properly, but does not pass @option{--autoconf-dir=@var{dir}} or
1553 @option{--localdir=@var{dir}}.
1555 @cindex Gettext
1556 @cindex @command{autopoint}
1557 Gettext supplies the @command{autopoint} command to add translation
1558 infrastructure to a source package.  If you use @command{autopoint},
1559 your @file{configure.ac} should invoke both @code{AM_GNU_GETTEXT} and
1560 @code{AM_GNU_GETTEXT_VERSION(@var{gettext-version})}.  @xref{autopoint
1561 Invocation, , Invoking the @code{autopoint} Program, gettext,
1562 @acronym{GNU} @code{gettext} utilities}, for further details.
1564 @noindent
1565 @command{autoreconf} accepts the following options:
1567 @table @option
1568 @item --help
1569 @itemx -h
1570 Print a summary of the command line options and exit.
1572 @item --version
1573 @itemx -V
1574 Print the version number of Autoconf and exit.
1576 @item --verbose
1577 Print the name of each directory @command{autoreconf} examines and the
1578 commands it runs.  If given two or more times, pass @option{--verbose}
1579 to subordinate tools that support it.
1581 @item --debug
1582 @itemx -d
1583 Don't remove the temporary files.
1585 @item --force
1586 @itemx -f
1587 Remake even @file{configure} scripts and configuration headers that are
1588 newer than their input files (@file{configure.ac} and, if present,
1589 @file{aclocal.m4}).
1591 @item --install
1592 @itemx -i
1593 Install the missing auxiliary files in the package.  By default, files
1594 are copied; this can be changed with @option{--symlink}.
1596 If deemed appropriate, this option triggers calls to
1597 @samp{automake --add-missing},
1598 @samp{libtoolize}, @samp{autopoint}, etc.
1600 @item --no-recursive
1601 Do not rebuild files in subdirectories to configure (see @ref{Subdirectories},
1602 macro @code{AC_CONFIG_SUBDIRS}).
1604 @item --symlink
1605 @itemx -s
1606 When used with @option{--install}, install symbolic links to the missing
1607 auxiliary files instead of copying them.
1609 @item --make
1610 @itemx -m
1611 When the directories were configured, update the configuration by
1612 running @samp{./config.status --recheck && ./config.status}, and then
1613 run @samp{make}.
1615 @item --include=@var{dir}
1616 @itemx -I @var{dir}
1617 Append @var{dir} to the include path.  Multiple invocations accumulate.
1618 Passed on to @command{autoconf} and @command{autoheader} internally.
1620 @item --prepend-include=@var{dir}
1621 @item -B @var{dir}
1622 Prepend @var{dir} to the include path.  Multiple invocations accumulate.
1623 Passed on to @command{autoconf} and @command{autoheader} internally.
1625 @item --warnings=@var{category}
1626 @itemx -W @var{category}
1627 @evindex WARNINGS
1628 Report the warnings related to @var{category} (which can actually be a
1629 comma separated list).
1631 @table @samp
1632 @item cross
1633 related to cross compilation issues.
1635 @item obsolete
1636 report the uses of obsolete constructs.
1638 @item portability
1639 portability issues
1641 @item syntax
1642 dubious syntactic constructs.
1644 @item all
1645 report all the warnings
1647 @item none
1648 report none
1650 @item error
1651 treats warnings as errors
1653 @item no-@var{category}
1654 disable warnings falling into @var{category}
1655 @end table
1657 Warnings about @samp{syntax} are enabled by default, and the environment
1658 variable @env{WARNINGS}, a comma separated list of categories, is
1659 honored as well.  Passing @option{-W @var{category}} actually behaves as if
1660 you had passed @option{--warnings=syntax,$WARNINGS,@var{category}}.  If
1661 you want to disable the defaults and @env{WARNINGS}, but (for example)
1662 enable the warnings about obsolete constructs, you would use @option{-W
1663 none,obsolete}.
1664 @end table
1666 If you want @command{autoreconf} to pass flags that are not listed here
1667 on to @command{aclocal}, set @code{ACLOCAL_AMFLAGS} in your @file{Makefile.am}.
1669 @c ========================================= Initialization and Output Files.
1671 @node Setup
1672 @chapter Initialization and Output Files
1674 Autoconf-generated @command{configure} scripts need some information about
1675 how to initialize, such as how to find the package's source files and
1676 about the output files to produce.  The following sections describe the
1677 initialization and the creation of output files.
1679 @menu
1680 * Initializing configure::      Option processing etc.
1681 * Notices::                     Copyright, version numbers in @command{configure}
1682 * Input::                       Where Autoconf should find files
1683 * Output::                      Outputting results from the configuration
1684 * Configuration Actions::       Preparing the output based on results
1685 * Configuration Files::         Creating output files
1686 * Makefile Substitutions::      Using output variables in makefiles
1687 * Configuration Headers::       Creating a configuration header file
1688 * Configuration Commands::      Running arbitrary instantiation commands
1689 * Configuration Links::         Links depending on the configuration
1690 * Subdirectories::              Configuring independent packages together
1691 * Default Prefix::              Changing the default installation prefix
1692 @end menu
1694 @node Initializing configure
1695 @section Initializing @command{configure}
1697 Every @command{configure} script must call @code{AC_INIT} before doing
1698 anything else.  The only other required macro is @code{AC_OUTPUT}
1699 (@pxref{Output}).
1701 @defmac AC_INIT (@var{package}, @var{version}, @ovar{bug-report}, @ovar{tarname})
1702 @acindex{INIT}
1703 Process any command-line arguments and perform various initializations
1704 and verifications.
1706 Set the name of the @var{package} and its @var{version}.  These are
1707 typically used in @option{--version} support, including that of
1708 @command{configure}.  The optional argument @var{bug-report} should be
1709 the email to which users should send bug reports.  The package
1710 @var{tarname} differs from @var{package}: the latter designates the full
1711 package name (e.g., @samp{GNU Autoconf}), while the former is meant for
1712 distribution tar ball names (e.g., @samp{autoconf}).  It defaults to
1713 @var{package} with @samp{GNU } stripped, lower-cased, and all characters
1714 other than alphanumerics and underscores are changed to @samp{-}.
1716 It is preferable that the arguments of @code{AC_INIT} be static, i.e.,
1717 there should not be any shell computation, but they can be computed by
1720 The following M4 macros (e.g., @code{AC_PACKAGE_NAME}), output variables
1721 (e.g., @code{PACKAGE_NAME}), and preprocessor symbols (e.g.,
1722 @code{PACKAGE_NAME}) are defined by @code{AC_INIT}:
1724 @table @asis
1725 @item @code{AC_PACKAGE_NAME}, @code{PACKAGE_NAME}
1726 @acindex{PACKAGE_NAME}
1727 @ovindex PACKAGE_NAME
1728 @cvindex PACKAGE_NAME
1729 Exactly @var{package}.
1731 @item @code{AC_PACKAGE_TARNAME}, @code{PACKAGE_TARNAME}
1732 @acindex{PACKAGE_TARNAME}
1733 @ovindex PACKAGE_TARNAME
1734 @cvindex PACKAGE_TARNAME
1735 Exactly @var{tarname}.
1737 @item @code{AC_PACKAGE_VERSION}, @code{PACKAGE_VERSION}
1738 @acindex{PACKAGE_VERSION}
1739 @ovindex PACKAGE_VERSION
1740 @cvindex PACKAGE_VERSION
1741 Exactly @var{version}.
1743 @item @code{AC_PACKAGE_STRING}, @code{PACKAGE_STRING}
1744 @acindex{PACKAGE_STRING}
1745 @ovindex PACKAGE_STRING
1746 @cvindex PACKAGE_STRING
1747 Exactly @samp{@var{package} @var{version}}.
1749 @item @code{AC_PACKAGE_BUGREPORT}, @code{PACKAGE_BUGREPORT}
1750 @acindex{PACKAGE_BUGREPORT}
1751 @ovindex PACKAGE_BUGREPORT
1752 @cvindex PACKAGE_BUGREPORT
1753 Exactly @var{bug-report}.
1754 @end table
1755 @end defmac
1757 If your @command{configure} script does its own option processing, it
1758 should inspect @samp{$@@} or @samp{$*} immediately after calling
1759 @code{AC_INIT}, because other Autoconf macros liberally use the
1760 @command{set} command to process strings, and this has the side effect
1761 of updating @samp{$@@} and @samp{$*}.  However, we suggest that you use
1762 standard macros like @code{AC_ARG_ENABLE} instead of attempting to
1763 implement your own option processing.  @xref{Site Configuration}.
1766 @node Notices
1767 @section Notices in @command{configure}
1768 @cindex Notices in @command{configure}
1770 The following macros manage version numbers for @command{configure}
1771 scripts.  Using them is optional.
1773 @c FIXME: AC_PREREQ should not be here
1774 @defmac AC_PREREQ (@var{version})
1775 @acindex{PREREQ}
1776 @cindex Version
1777 Ensure that a recent enough version of Autoconf is being used.  If the
1778 version of Autoconf being used to create @command{configure} is
1779 earlier than @var{version}, print an error message to the standard
1780 error output and exit with failure (exit status is 63).  For example:
1782 @example
1783 AC_PREREQ([@value{VERSION}])
1784 @end example
1786 This macro is the only macro that may be used before @code{AC_INIT}, but
1787 for consistency, you are invited not to do so.
1788 @end defmac
1790 @defmac AC_COPYRIGHT (@var{copyright-notice})
1791 @acindex{COPYRIGHT}
1792 @cindex Copyright Notice
1793 State that, in addition to the Free Software Foundation's copyright on
1794 the Autoconf macros, parts of your @command{configure} are covered by the
1795 @var{copyright-notice}.
1797 The @var{copyright-notice} shows up in both the head of
1798 @command{configure} and in @samp{configure --version}.
1799 @end defmac
1802 @defmac AC_REVISION (@var{revision-info})
1803 @acindex{REVISION}
1804 @cindex Revision
1805 Copy revision stamp @var{revision-info} into the @command{configure}
1806 script, with any dollar signs or double-quotes removed.  This macro lets
1807 you put a revision stamp from @file{configure.ac} into @command{configure}
1808 without @acronym{RCS} or @acronym{CVS} changing it when you check in
1809 @command{configure}.  That way, you can determine easily which revision of
1810 @file{configure.ac} a particular @command{configure} corresponds to.
1812 For example, this line in @file{configure.ac}:
1814 @c The asis prevents RCS from changing the example in the manual.
1815 @example
1816 AC_REVISION([$@asis{Revision: 1.30 }$])
1817 @end example
1819 @noindent
1820 produces this in @command{configure}:
1822 @example
1823 #!/bin/sh
1824 # From configure.ac Revision: 1.30
1825 @end example
1826 @end defmac
1829 @node Input
1830 @section Finding @command{configure} Input
1833 @defmac AC_CONFIG_SRCDIR (@var{unique-file-in-source-dir})
1834 @acindex{CONFIG_SRCDIR}
1835 @var{unique-file-in-source-dir} is some file that is in the package's
1836 source directory; @command{configure} checks for this file's existence to
1837 make sure that the directory that it is told contains the source code in
1838 fact does.  Occasionally people accidentally specify the wrong directory
1839 with @option{--srcdir}; this is a safety check.  @xref{configure
1840 Invocation}, for more information.
1841 @end defmac
1844 @c FIXME: Remove definitively once --install explained.
1846 @c Small packages may store all their macros in @code{aclocal.m4}.  As the
1847 @c set of macros grows, or for maintenance reasons, a maintainer may prefer
1848 @c to split the macros in several files.  In this case, Autoconf must be
1849 @c told which files to load, and in which order.
1851 @c @defmac AC_INCLUDE (@var{file}@dots{})
1852 @c @acindex{INCLUDE}
1853 @c @c FIXME: There is no longer shell globbing.
1854 @c Read the macro definitions that appear in the listed files.  A list of
1855 @c space-separated file names or shell globbing patterns is expected.  The
1856 @c files are read in the order they're listed.
1858 @c Because the order of definition of macros is important (only the last
1859 @c definition of a macro is used), beware that it is @code{AC_INIT} that
1860 @c loads @file{acsite.m4} and @file{aclocal.m4}.  Note that
1861 @c @code{AC_INCLUDE}ing a file before @code{AC_INIT} or within
1862 @c @file{aclocal.m4} is different from doing so after @code{AC_INIT}: in
1863 @c the latter case, non-macro lines from included files may end up in the
1864 @c @file{configure} script, whereas in the former case, they'd be discarded
1865 @c just like any text that appear before @code{AC_INIT}.
1866 @c @end defmac
1868 Packages that do manual configuration or use the @command{install} program
1869 might need to tell @command{configure} where to find some other shell
1870 scripts by calling @code{AC_CONFIG_AUX_DIR}, though the default places
1871 it looks are correct for most cases.
1873 @defmac AC_CONFIG_AUX_DIR (@var{dir})
1874 @acindex{CONFIG_AUX_DIR}
1875 Use the auxiliary build tools (e.g., @file{install-sh},
1876 @file{config.sub}, @file{config.guess}, Cygnus @command{configure},
1877 Automake and Libtool scripts, etc.)@: that are in directory @var{dir}.
1878 These are auxiliary files used in configuration.  @var{dir} can be
1879 either absolute or relative to @file{@var{srcdir}}.  The default is
1880 @file{@var{srcdir}} or @file{@var{srcdir}/..} or
1881 @file{@var{srcdir}/../..}, whichever is the first that contains
1882 @file{install-sh}.  The other files are not checked for, so that using
1883 @code{AC_PROG_INSTALL} does not automatically require distributing the
1884 other auxiliary files.  It checks for @file{install.sh} also, but that
1885 name is obsolete because some @code{make} have a rule that creates
1886 @file{install} from it if there is no makefile.
1888 The auxiliary directory is commonly named @file{build-aux}.
1889 If you need portability to @acronym{DOS} variants, do not name the
1890 auxiliary directory @file{aux}.  @xref{File System Conventions}.
1891 @end defmac
1893 @defmac AC_REQUIRE_AUX_FILE (@var{file})
1894 @acindex{REQUIRE_AUX_FILE}
1895 Declares that @var{file} is expected in the directory defined above.  In
1896 Autoconf proper, this macro does nothing: its sole purpose is to be
1897 traced by third-party tools to produce a list of expected auxiliary
1898 files.  For instance it is called by macros like @code{AC_PROG_INSTALL}
1899 (@pxref{Particular Programs}) or @code{AC_CANONICAL_BUILD}
1900 (@pxref{Canonicalizing}) to register the auxiliary files they need.
1901 @end defmac
1903 Similarly, packages that use @command{aclocal} should declare where
1904 local macros can be found using @code{AC_CONFIG_MACRO_DIR}.
1906 @defmac AC_CONFIG_MACRO_DIR (@var{dir})
1907 @acindex{CONFIG_MACRO_DIR}
1908 Specify @var{dir} as the location of additional local Autoconf macros.
1909 This macro is intended for use by future versions of commands like
1910 @command{autoreconf} that trace macro calls.  It should be called
1911 directly from @file{configure.ac} so that tools that install macros for
1912 @command{aclocal} can find the macros' declarations.
1913 @end defmac
1916 @node Output
1917 @section Outputting Files
1918 @cindex Outputting files
1920 Every Autoconf script, e.g., @file{configure.ac}, should finish by
1921 calling @code{AC_OUTPUT}.  That is the macro that generates and runs
1922 @file{config.status}, which in turn creates the makefiles and any
1923 other files resulting from configuration.  This is the only required
1924 macro besides @code{AC_INIT} (@pxref{Input}).
1926 @defmac AC_OUTPUT
1927 @acindex{OUTPUT}
1928 @cindex Instantiation
1929 Generate @file{config.status} and launch it.  Call this macro once, at
1930 the end of @file{configure.ac}.
1932 @file{config.status} performs all the configuration actions: all the
1933 output files (see @ref{Configuration Files}, macro
1934 @code{AC_CONFIG_FILES}), header files (see @ref{Configuration Headers},
1935 macro @code{AC_CONFIG_HEADERS}), commands (see @ref{Configuration
1936 Commands}, macro @code{AC_CONFIG_COMMANDS}), links (see
1937 @ref{Configuration Links}, macro @code{AC_CONFIG_LINKS}), subdirectories
1938 to configure (see @ref{Subdirectories}, macro @code{AC_CONFIG_SUBDIRS})
1939 are honored.
1941 The location of your @code{AC_OUTPUT} invocation is the exact point
1942 where configuration actions are taken: any code afterwards is
1943 executed by @code{configure} once @command{config.status} was run.  If
1944 you want to bind actions to @command{config.status} itself
1945 (independently of whether @command{configure} is being run), see
1946 @ref{Configuration Commands, , Running Arbitrary Configuration
1947 Commands}.
1948 @end defmac
1950 Historically, the usage of @code{AC_OUTPUT} was somewhat different.
1951 @xref{Obsolete Macros}, for a description of the arguments that
1952 @code{AC_OUTPUT} used to support.
1955 If you run @command{make} in subdirectories, you should run it using the
1956 @code{make} variable @code{MAKE}.  Most versions of @command{make} set
1957 @code{MAKE} to the name of the @command{make} program plus any options it
1958 was given.  (But many do not include in it the values of any variables
1959 set on the command line, so those are not passed on automatically.)
1960 Some old versions of @command{make} do not set this variable.  The
1961 following macro allows you to use it even with those versions.
1963 @defmac AC_PROG_MAKE_SET
1964 @acindex{PROG_MAKE_SET}
1965 @ovindex SET_MAKE
1966 If the Make command, @code{$MAKE} if set or else @samp{make}, predefines
1967 @code{$(MAKE)}, define output variable @code{SET_MAKE} to be empty.
1968 Otherwise, define @code{SET_MAKE} to a macro definition that sets
1969 @code{$(MAKE)}, such as @samp{MAKE=make}.  Calls @code{AC_SUBST} for
1970 @code{SET_MAKE}.
1971 @end defmac
1973 If you use this macro, place a line like this in each @file{Makefile.in}
1974 that runs @code{MAKE} on other directories:
1976 @example
1977 @@SET_MAKE@@
1978 @end example
1982 @node Configuration Actions
1983 @section Performing Configuration Actions
1984 @cindex Configuration actions
1986 @file{configure} is designed so that it appears to do everything itself,
1987 but there is actually a hidden slave: @file{config.status}.
1988 @file{configure} is in charge of examining your system, but it is
1989 @file{config.status} that actually takes the proper actions based on the
1990 results of @file{configure}.  The most typical task of
1991 @file{config.status} is to @emph{instantiate} files.
1993 This section describes the common behavior of the four standard
1994 instantiating macros: @code{AC_CONFIG_FILES}, @code{AC_CONFIG_HEADERS},
1995 @code{AC_CONFIG_COMMANDS} and @code{AC_CONFIG_LINKS}.  They all
1996 have this prototype:
1998 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
1999 @c awful.
2000 @example
2001 AC_CONFIG_FOOS(@var{tag}@dots{}, [@var{commands}], [@var{init-cmds}])
2002 @end example
2004 @noindent
2005 where the arguments are:
2007 @table @var
2008 @item tag@dots{}
2009 A blank-or-newline-separated list of tags, which are typically the names of
2010 the files to instantiate.
2012 You are encouraged to use literals as @var{tags}.  In particular, you
2013 should avoid
2015 @example
2016 @dots{} && my_foos="$my_foos fooo"
2017 @dots{} && my_foos="$my_foos foooo"
2018 AC_CONFIG_FOOS([$my_foos])
2019 @end example
2021 @noindent
2022 and use this instead:
2024 @example
2025 @dots{} && AC_CONFIG_FOOS([fooo])
2026 @dots{} && AC_CONFIG_FOOS([foooo])
2027 @end example
2029 The macros @code{AC_CONFIG_FILES} and @code{AC_CONFIG_HEADERS} use
2030 special @var{tag} values: they may have the form @samp{@var{output}} or
2031 @samp{@var{output}:@var{inputs}}.  The file @var{output} is instantiated
2032 from its templates, @var{inputs} (defaulting to @samp{@var{output}.in}).
2034 @samp{AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk)]},
2035 for example, asks for
2036 the creation of the file @file{Makefile} that contains the expansion of the
2037 output variables in the concatenation of @file{boiler/top.mk} and
2038 @file{boiler/bot.mk}.
2040 The special value @samp{-} might be used to denote the standard output
2041 when used in @var{output}, or the standard input when used in the
2042 @var{inputs}.  You most probably don't need to use this in
2043 @file{configure.ac}, but it is convenient when using the command line
2044 interface of @file{./config.status}, see @ref{config.status Invocation},
2045 for more details.
2047 The @var{inputs} may be absolute or relative file names.  In the latter
2048 case they are first looked for in the build tree, and then in the source
2049 tree.
2051 @item commands
2052 Shell commands output literally into @file{config.status}, and
2053 associated with a tag that the user can use to tell @file{config.status}
2054 which the commands to run.  The commands are run each time a @var{tag}
2055 request is given to @file{config.status}, typically each time the file
2056 @file{@var{tag}} is created.
2058 The variables set during the execution of @command{configure} are
2059 @emph{not} available here: you first need to set them via the
2060 @var{init-cmds}.  Nonetheless the following variables are precomputed:
2062 @table @code
2063 @item srcdir
2064 The name of the top source directory, assuming that the working
2065 directory is the top build directory.  This
2066 is what the @command{configure} option @option{--srcdir} sets.
2068 @item ac_top_srcdir
2069 The name of the top source directory, assuming that the working
2070 directory is the current build directory.
2073 @item ac_top_build_prefix
2074 The name of the top build directory, assuming that the working
2075 directory is the current build directory.
2076 It can be empty, or else ends with a slash, so that you may concatenate
2079 @item ac_srcdir
2080 The name of the corresponding source directory, assuming that the
2081 working directory is the current build directory.
2082 @end table
2084 @noindent
2085 The @dfn{current} directory refers to the directory (or
2086 pseudo-directory) containing the input part of @var{tags}.  For
2087 instance, running
2089 @example
2090 AC_CONFIG_COMMANDS([deep/dir/out:in/in.in], [@dots{}], [@dots{}])
2091 @end example
2093 @noindent
2094  with @option{--srcdir=../package} produces the following values:
2096 @example
2097 # Argument of --srcdir
2098 srcdir='../package'
2099 # Reversing deep/dir
2100 ac_top_build_prefix='../../'
2101 # Concatenation of $ac_top_build_prefix and srcdir
2102 ac_top_srcdir='../../../package'
2103 # Concatenation of $ac_top_srcdir and deep/dir
2104 ac_srcdir='../../../package/deep/dir'
2105 @end example
2107 @noindent
2108 independently of @samp{in/in.in}.
2110 @item init-cmds
2111 Shell commands output @emph{unquoted} near the beginning of
2112 @file{config.status}, and executed each time @file{config.status} runs
2113 (regardless of the tag).  Because they are unquoted, for example,
2114 @samp{$var} is output as the value of @code{var}.  @var{init-cmds}
2115 is typically used by @file{configure} to give @file{config.status} some
2116 variables it needs to run the @var{commands}.
2118 You should be extremely cautious in your variable names: all the
2119 @var{init-cmds} share the same name space and may overwrite each other
2120 in unpredictable ways.  Sorry@enddots{}
2121 @end table
2123 All these macros can be called multiple times, with different
2124 @var{tag} values, of course!
2127 @node Configuration Files
2128 @section Creating Configuration Files
2129 @cindex Creating configuration files
2130 @cindex Configuration file creation
2132 Be sure to read the previous section, @ref{Configuration Actions}.
2134 @defmac AC_CONFIG_FILES (@var{file}@dots{}, @ovar{cmds}, @ovar{init-cmds})
2135 @acindex{CONFIG_FILES}
2136 Make @code{AC_OUTPUT} create each @file{@var{file}} by copying an input
2137 file (by default @file{@var{file}.in}), substituting the output variable
2138 values.
2139 @c Before we used to have this feature, which was later rejected
2140 @c because it complicates the writing of makefiles:
2141 @c If the file would be unchanged, it is left untouched, to preserve
2142 @c timestamp.
2143 This macro is one of the instantiating macros; see @ref{Configuration
2144 Actions}.  @xref{Makefile Substitutions}, for more information on using
2145 output variables.  @xref{Setting Output Variables}, for more information
2146 on creating them.  This macro creates the directory that the file is in
2147 if it doesn't exist.  Usually, makefiles are created this way,
2148 but other files, such as @file{.gdbinit}, can be specified as well.
2150 Typical calls to @code{AC_CONFIG_FILES} look like this:
2152 @example
2153 AC_CONFIG_FILES([Makefile src/Makefile man/Makefile X/Imakefile])
2154 AC_CONFIG_FILES([autoconf], [chmod +x autoconf])
2155 @end example
2157 You can override an input file name by appending to @var{file} a
2158 colon-separated list of input files.  Examples:
2160 @example
2161 AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk]
2162                 [lib/Makefile:boiler/lib.mk])
2163 @end example
2165 @noindent
2166 Doing this allows you to keep your file names acceptable to
2167 @acronym{DOS} variants, or
2168 to prepend and/or append boilerplate to the file.
2169 @end defmac
2173 @node Makefile Substitutions
2174 @section Substitutions in Makefiles
2175 @cindex Substitutions in makefiles
2176 @cindex Makefile substitutions
2178 Each subdirectory in a distribution that contains something to be
2179 compiled or installed should come with a file @file{Makefile.in}, from
2180 which @command{configure} creates a file @file{Makefile} in that directory.
2181 To create @file{Makefile}, @command{configure} performs a simple variable
2182 substitution, replacing occurrences of @samp{@@@var{variable}@@} in
2183 @file{Makefile.in} with the value that @command{configure} has determined
2184 for that variable.  Variables that are substituted into output files in
2185 this way are called @dfn{output variables}.  They are ordinary shell
2186 variables that are set in @command{configure}.  To make @command{configure}
2187 substitute a particular variable into the output files, the macro
2188 @code{AC_SUBST} must be called with that variable name as an argument.
2189 Any occurrences of @samp{@@@var{variable}@@} for other variables are
2190 left unchanged.  @xref{Setting Output Variables}, for more information
2191 on creating output variables with @code{AC_SUBST}.
2193 A software package that uses a @command{configure} script should be
2194 distributed with a file @file{Makefile.in}, but no makefile; that
2195 way, the user has to properly configure the package for the local system
2196 before compiling it.
2198 @xref{Makefile Conventions, , Makefile Conventions, standards, The
2199 @acronym{GNU} Coding Standards}, for more information on what to put in
2200 makefiles.
2202 @menu
2203 * Preset Output Variables::     Output variables that are always set
2204 * Installation Directory Variables::  Other preset output variables
2205 * Changed Directory Variables:: Warnings about @file{datarootdir}
2206 * Build Directories::           Supporting multiple concurrent compiles
2207 * Automatic Remaking::          Makefile rules for configuring
2208 @end menu
2210 @node Preset Output Variables
2211 @subsection Preset Output Variables
2212 @cindex Output variables
2214 Some output variables are preset by the Autoconf macros.  Some of the
2215 Autoconf macros set additional output variables, which are mentioned in
2216 the descriptions for those macros.  @xref{Output Variable Index}, for a
2217 complete list of output variables.  @xref{Installation Directory
2218 Variables}, for the list of the preset ones related to installation
2219 directories.  Below are listed the other preset ones.  They all are
2220 precious variables (@pxref{Setting Output Variables},
2221 @code{AC_ARG_VAR}).
2223 @c Just say no to ASCII sorting!  We're humans, not computers.
2224 @c These variables are listed as they would be in a dictionary:
2225 @c actor
2226 @c Actress
2227 @c actress
2229 @defvar CFLAGS
2230 @ovindex CFLAGS
2231 Debugging and optimization options for the C compiler.  If it is not set
2232 in the environment when @command{configure} runs, the default value is set
2233 when you call @code{AC_PROG_CC} (or empty if you don't).  @command{configure}
2234 uses this variable when compiling or linking programs to test for C features.
2236 If a compiler option affects only the behavior of the preprocessor
2237 (e.g., @option{-D @var{name}}), it should be put into @code{CPPFLAGS}
2238 instead.  If it affects only the linker (e.g., @option{-L
2239 @var{directory}}), it should be put into @code{LDFLAGS} instead.  If it
2240 affects only the compiler proper, @code{CFLAGS} is the natural home for
2241 it.  If an option affects multiple phases of the compiler, though,
2242 matters get tricky.  One approach to put such options directly into
2243 @code{CC}, e.g., @code{CC='gcc -m64'}.  Another is to put them into both
2244 @code{CPPFLAGS} and @code{LDFLAGS}, but not into @code{CFLAGS}.
2246 @end defvar
2248 @defvar configure_input
2249 @ovindex configure_input
2250 A comment saying that the file was generated automatically by
2251 @command{configure} and giving the name of the input file.
2252 @code{AC_OUTPUT} adds a comment line containing this variable to the top
2253 of every makefile it creates.  For other files, you should
2254 reference this variable in a comment at the top of each input file.  For
2255 example, an input shell script should begin like this:
2257 @example
2258 #!/bin/sh
2259 # @@configure_input@@
2260 @end example
2262 @noindent
2263 The presence of that line also reminds people editing the file that it
2264 needs to be processed by @command{configure} in order to be used.
2265 @end defvar
2267 @defvar CPPFLAGS
2268 @ovindex CPPFLAGS
2269 Preprocessor options for the C, C++, and Objective C preprocessors and
2270 compilers.  If
2271 it is not set in the environment when @command{configure} runs, the default
2272 value is empty.  @command{configure} uses this variable when preprocessing
2273 or compiling programs to test for C, C++, and Objective C features.
2275 This variable's contents should contain options like @option{-I},
2276 @option{-D}, and @option{-U} that affect only the behavior of the
2277 preprocessor.  Please see the explanation of @code{CFLAGS} for what you
2278 can do if an option affects other phases of the compiler as well.
2280 Currently, @command{configure} always links as part of a single
2281 invocation of the compiler that also preprocesses and compiles, so it
2282 uses this variable also when linking programs.  However, it is unwise to
2283 depend on this behavior because the @acronym{GNU} coding standards do
2284 not require it and many packages do not use @code{CPPFLAGS} when linking
2285 programs.
2287 @xref{Special Chars in Variables}, for limitations that @code{CPPFLAGS}
2288 might run into.
2289 @end defvar
2291 @defvar CXXFLAGS
2292 @ovindex CXXFLAGS
2293 Debugging and optimization options for the C++ compiler.  It acts like
2294 @code{CFLAGS}, but for C++ instead of C.
2295 @end defvar
2297 @defvar DEFS
2298 @ovindex DEFS
2299 @option{-D} options to pass to the C compiler.  If @code{AC_CONFIG_HEADERS}
2300 is called, @command{configure} replaces @samp{@@DEFS@@} with
2301 @option{-DHAVE_CONFIG_H} instead (@pxref{Configuration Headers}).  This
2302 variable is not defined while @command{configure} is performing its tests,
2303 only when creating the output files.  @xref{Setting Output Variables}, for
2304 how to check the results of previous tests.
2305 @end defvar
2307 @defvar ECHO_C
2308 @defvarx ECHO_N
2309 @defvarx ECHO_T
2310 @ovindex ECHO_C
2311 @ovindex ECHO_N
2312 @ovindex ECHO_T
2313 How does one suppress the trailing newline from @command{echo} for
2314 question-answer message pairs?  These variables provide a way:
2316 @example
2317 echo $ECHO_N "And the winner is... $ECHO_C"
2318 sleep 100000000000
2319 echo "$@{ECHO_T@}dead."
2320 @end example
2322 @noindent
2323 Some old and uncommon @command{echo} implementations offer no means to
2324 achieve this, in which case @code{ECHO_T} is set to tab.  You might not
2325 want to use it.
2326 @end defvar
2328 @defvar ERLCFLAGS
2329 @ovindex ERLCFLAGS
2330 Debugging and optimization options for the Erlang compiler.  If it is not set
2331 in the environment when @command{configure} runs, the default value is empty.
2332 @command{configure} uses this variable when compiling
2333 programs to test for Erlang features.
2334 @end defvar
2336 @defvar FCFLAGS
2337 @ovindex FCFLAGS
2338 Debugging and optimization options for the Fortran compiler.  If it
2339 is not set in the environment when @command{configure} runs, the default
2340 value is set when you call @code{AC_PROG_FC} (or empty if you don't).
2341 @command{configure} uses this variable when compiling or linking
2342 programs to test for Fortran features.
2343 @end defvar
2345 @defvar FFLAGS
2346 @ovindex FFLAGS
2347 Debugging and optimization options for the Fortran 77 compiler.  If it
2348 is not set in the environment when @command{configure} runs, the default
2349 value is set when you call @code{AC_PROG_F77} (or empty if you don't).
2350 @command{configure} uses this variable when compiling or linking
2351 programs to test for Fortran 77 features.
2352 @end defvar
2354 @defvar LDFLAGS
2355 @ovindex LDFLAGS
2356 Options for the linker.  If it is not set
2357 in the environment when @command{configure} runs, the default value is empty.
2358 @command{configure} uses this variable when linking programs to test for
2359 C, C++, Objective C, and Fortran features.
2361 This variable's contents should contain options like @option{-s} and
2362 @option{-L} that affect only the behavior of the linker.  Please see the
2363 explanation of @code{CFLAGS} for what you can do if an option also
2364 affects other phases of the compiler.
2366 Don't use this variable to pass library names
2367 (@option{-l}) to the linker; use @code{LIBS} instead.
2368 @end defvar
2370 @defvar LIBS
2371 @ovindex LIBS
2372 @option{-l} options to pass to the linker.  The default value is empty,
2373 but some Autoconf macros may prepend extra libraries to this variable if
2374 those libraries are found and provide necessary functions, see
2375 @ref{Libraries}.  @command{configure} uses this variable when linking
2376 programs to test for C, C++, and Fortran features.
2377 @end defvar
2379 @defvar OBJCFLAGS
2380 @ovindex OBJCFLAGS
2381 Debugging and optimization options for the Objective C compiler.  It
2382 acts like @code{CFLAGS}, but for Objective C instead of C.
2383 @end defvar
2385 @defvar builddir
2386 @ovindex builddir
2387 Rigorously equal to @samp{.}.  Added for symmetry only.
2388 @end defvar
2390 @defvar abs_builddir
2391 @ovindex abs_builddir
2392 Absolute name of @code{builddir}.
2393 @end defvar
2395 @defvar top_builddir
2396 @ovindex top_builddir
2397 The relative name of the top level of the current build tree.  In the
2398 top-level directory, this is the same as @code{builddir}.
2399 @end defvar
2401 @defvar abs_top_builddir
2402 @ovindex abs_top_builddir
2403 Absolute name of @code{top_builddir}.
2404 @end defvar
2406 @defvar srcdir
2407 @ovindex srcdir
2408 The name of the directory that contains the source code for
2409 that makefile.
2410 @end defvar
2412 @defvar abs_srcdir
2413 @ovindex abs_srcdir
2414 Absolute name of @code{srcdir}.
2415 @end defvar
2417 @defvar top_srcdir
2418 @ovindex top_srcdir
2419 The name of the top-level source code directory for the
2420 package.  In the top-level directory, this is the same as @code{srcdir}.
2421 @end defvar
2423 @defvar abs_top_srcdir
2424 @ovindex abs_top_srcdir
2425 Absolute name of @code{top_srcdir}.
2426 @end defvar
2428 @node Installation Directory Variables
2429 @subsection Installation Directory Variables
2430 @cindex Installation directories
2431 @cindex Directories, installation
2433 The following variables specify the directories for
2434 package installation, see @ref{Directory Variables, , Variables for
2435 Installation Directories, standards, The @acronym{GNU} Coding
2436 Standards}, for more information.  See the end of this section for
2437 details on when and how to use these variables.
2439 @defvar bindir
2440 @ovindex bindir
2441 The directory for installing executables that users run.
2442 @end defvar
2444 @defvar datadir
2445 @ovindex datadir
2446 The directory for installing idiosyncratic read-only
2447 architecture-independent data.
2448 @end defvar
2450 @defvar datarootdir
2451 @ovindex datarootdir
2452 The root of the directory tree for read-only architecture-independent
2453 data files.
2454 @end defvar
2456 @defvar docdir
2457 @ovindex docdir
2458 The directory for installing documentation files (other than Info and
2459 man).
2460 @end defvar
2462 @defvar dvidir
2463 @ovindex dvidir
2464 The directory for installing documentation files in DVI format.
2465 @end defvar
2467 @defvar exec_prefix
2468 @ovindex exec_prefix
2469 The installation prefix for architecture-dependent files.  By default
2470 it's the same as @var{prefix}.  You should avoid installing anything
2471 directly to @var{exec_prefix}.  However, the default value for
2472 directories containing architecture-dependent files should be relative
2473 to @var{exec_prefix}.
2474 @end defvar
2476 @defvar htmldir
2477 @ovindex htmldir
2478 The directory for installing HTML documentation.
2479 @end defvar
2481 @defvar includedir
2482 @ovindex includedir
2483 The directory for installing C header files.
2484 @end defvar
2486 @defvar infodir
2487 @ovindex infodir
2488 The directory for installing documentation in Info format.
2489 @end defvar
2491 @defvar libdir
2492 @ovindex libdir
2493 The directory for installing object code libraries.
2494 @end defvar
2496 @defvar libexecdir
2497 @ovindex libexecdir
2498 The directory for installing executables that other programs run.
2499 @end defvar
2501 @defvar localedir
2502 @ovindex localedir
2503 The directory for installing locale-dependent but
2504 architecture-independent data, such as message catalogs.  This directory
2505 usually has a subdirectory per locale.
2506 @end defvar
2508 @defvar localstatedir
2509 @ovindex localstatedir
2510 The directory for installing modifiable single-machine data.
2511 @end defvar
2513 @defvar mandir
2514 @ovindex mandir
2515 The top-level directory for installing documentation in man format.
2516 @end defvar
2518 @defvar oldincludedir
2519 @ovindex oldincludedir
2520 The directory for installing C header files for non-@acronym{GCC} compilers.
2521 @end defvar
2523 @defvar pdfdir
2524 @ovindex pdfdir
2525 The directory for installing PDF documentation.
2526 @end defvar
2528 @defvar prefix
2529 @ovindex prefix
2530 The common installation prefix for all files.  If @var{exec_prefix}
2531 is defined to a different value, @var{prefix} is used only for
2532 architecture-independent files.
2533 @end defvar
2535 @defvar psdir
2536 @ovindex psdir
2537 The directory for installing PostScript documentation.
2538 @end defvar
2540 @defvar sbindir
2541 @ovindex sbindir
2542 The directory for installing executables that system
2543 administrators run.
2544 @end defvar
2546 @defvar sharedstatedir
2547 @ovindex sharedstatedir
2548 The directory for installing modifiable architecture-independent data.
2549 @end defvar
2551 @defvar sysconfdir
2552 @ovindex sysconfdir
2553 The directory for installing read-only single-machine data.
2554 @end defvar
2557 Most of these variables have values that rely on @code{prefix} or
2558 @code{exec_prefix}.  It is deliberate that the directory output
2559 variables keep them unexpanded: typically @samp{@@datarootdir@@} is
2560 replaced by @samp{$@{prefix@}/share}, not @samp{/usr/local/share}, and
2561 @samp{@@datadir@@} is replaced by @samp{$@{datarootdir@}}.
2563 This behavior is mandated by the @acronym{GNU} coding standards, so that when
2564 the user runs:
2566 @table @samp
2567 @item make
2568 she can still specify a different prefix from the one specified to
2569 @command{configure}, in which case, if needed, the package should hard
2570 code dependencies corresponding to the make-specified prefix.
2572 @item make install
2573 she can specify a different installation location, in which case the
2574 package @emph{must} still depend on the location which was compiled in
2575 (i.e., never recompile when @samp{make install} is run).  This is an
2576 extremely important feature, as many people may decide to install all
2577 the files of a package grouped together, and then install links from
2578 the final locations to there.
2579 @end table
2581 In order to support these features, it is essential that
2582 @code{datarootdir} remains being defined as @samp{$@{prefix@}/share} to
2583 depend upon the current value of @code{prefix}.
2585 A corollary is that you should not use these variables except in
2586 makefiles.  For instance, instead of trying to evaluate @code{datadir}
2587 in @file{configure} and hard-coding it in makefiles using
2588 e.g., @samp{AC_DEFINE_UNQUOTED([DATADIR], ["$datadir"], [Data directory.])},
2589 you should add
2590 @option{-DDATADIR='$(datadir)'} to your makefile's definition of
2591 @code{CPPFLAGS} (@code{AM_CPPFLAGS} if you are also using Automake).
2593 Similarly, you should not rely on @code{AC_CONFIG_FILES} to replace
2594 @code{datadir} and friends in your shell scripts and other files; instead,
2595 let @command{make} manage their replacement.  For instance Autoconf
2596 ships templates of its shell scripts ending with @samp{.in}, and uses a
2597 makefile snippet similar to the following to build scripts like
2598 @command{autoheader} and @command{autom4te}:
2600 @example
2601 @group
2602 edit = sed \
2603         -e 's|@@datadir[@@]|$(pkgdatadir)|g' \
2604         -e 's|@@prefix[@@]|$(prefix)|g'
2605 @end group
2607 @group
2608 autoheader autom4te: Makefile
2609         rm -f $@@ $@@.tmp
2610         $(edit) '$(srcdir)/$@@.in' >$@@.tmp
2611         chmod +x $@@.tmp
2612         chmod a-w $@@.tmp
2613         mv $@@.tmp $@@
2614 @end group
2616 @group
2617 autoheader: $(srcdir)/autoheader.in
2618 autom4te: $(srcdir)/autom4te.in
2619 @end group
2620 @end example
2622 Some details are noteworthy:
2624 @table @asis
2625 @item @samp{@@datadir[@@]}
2626 The brackets prevent @command{configure} from replacing
2627 @samp{@@datadir@@} in the Sed expression itself.
2628 Brackets are preferable to a backslash here, since
2629 Posix says @samp{\@@} is not portable.
2631 @item @samp{$(pkgdatadir)}
2632 Don't use @samp{@@pkgdatadir@@}!  Use the matching makefile variable
2633 instead.
2635 @item @samp{/}
2636 Don't use @samp{/} in the Sed expressions that replace file names since
2637 most likely the
2638 variables you use, such as @samp{$(pkgdatadir)}, contain @samp{/}.
2639 Use a shell metacharacter instead, such as @samp{|}.
2641 @item special characters
2642 File names, file name components, and the value of @code{VPATH} should
2643 not contain shell metacharacters or white
2644 space.  @xref{Special Chars in Variables}.
2646 @item dependency on @file{Makefile}
2647 Since @code{edit} uses values that depend on the configuration specific
2648 values (@code{prefix}, etc.)@: and not only on @code{VERSION} and so forth,
2649 the output depends on @file{Makefile}, not @file{configure.ac}.
2651 @item @samp{$@@}
2652 The main rule is generic, and uses @samp{$@@} extensively to
2653 avoid the need for multiple copies of the rule.
2655 @item Separated dependencies and single suffix rules
2656 You can't use them!  The above snippet cannot be (portably) rewritten
2659 @example
2660 autoconf autoheader: Makefile
2661 @group
2662 .in:
2663         rm -f $@@ $@@.tmp
2664         $(edit) $< >$@@.tmp
2665         chmod +x $@@.tmp
2666         mv $@@.tmp $@@
2667 @end group
2668 @end example
2670 @xref{Single Suffix Rules}, for details.
2672 @item @samp{$(srcdir)}
2673 Be sure to specify the name of the source directory,
2674 otherwise the package won't support separated builds.
2675 @end table
2677 For the more specific installation of Erlang libraries, the following variables
2678 are defined:
2680 @defvar ERLANG_INSTALL_LIB_DIR
2681 @ovindex ERLANG_INSTALL_LIB_DIR
2682 @acindex{ERLANG_SUBST_INSTALL_LIB_DIR}
2683 The common parent directory of Erlang library installation directories.
2684 This variable is set by calling the @code{AC_ERLANG_SUBST_INSTALL_LIB_DIR}
2685 macro in @file{configure.ac}.
2686 @end defvar
2688 @defvar ERLANG_INSTALL_LIB_DIR_@var{library}
2689 @ovindex ERLANG_INSTALL_LIB_DIR_@var{library}
2690 @acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR}
2691 The installation directory for Erlang library @var{library}.
2692 This variable is set by calling the
2693 @samp{AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR(@var{library}, @var{version}}
2694 macro in @file{configure.ac}.
2695 @end defvar
2697 @xref{Erlang Libraries}, for details.
2700 @node Changed Directory Variables
2701 @subsection Changed Directory Variables
2702 @cindex @file{datarootdir}
2704 In Autoconf 2.60, the set of directory variables has changed, and the
2705 defaults of some variables have been adjusted
2706 (@pxref{Installation Directory Variables}) to changes in the
2707 @acronym{GNU} Coding Standards.  Notably, @file{datadir}, @file{infodir}, and
2708 @file{mandir} are now expressed in terms of @file{datarootdir}.  If you are
2709 upgrading from an earlier Autoconf version, you may need to adjust your files
2710 to ensure that the directory variables are substituted correctly
2711 (@pxref{Defining Directories}), and that a definition of @file{datarootdir} is
2712 in place.  For example, in a @file{Makefile.in}, adding
2714 @example
2715 datarootdir = @@datarootdir@@
2716 @end example
2718 @noindent
2719 is usually sufficient.  If you use Automake to create @file{Makefile.in},
2720 it will add this for you.
2722 To help with the transition, Autoconf warns about files that seem to use
2723 @code{datarootdir} without defining it.  In some cases, it then expands
2724 the value of @code{$datarootdir} in substitutions of the directory
2725 variables.  The following example shows such a warning:
2727 @example
2728 $ @kbd{cat configure.ac}
2729 AC_INIT
2730 AC_CONFIG_FILES([Makefile])
2731 AC_OUTPUT
2732 $ @kbd{cat Makefile.in}
2733 prefix = @@prefix@@
2734 datadir = @@datadir@@
2735 $ @kbd{autoconf}
2736 $ @kbd{configure}
2737 configure: creating ./config.status
2738 config.status: creating Makefile
2739 config.status: WARNING:
2740                Makefile.in seems to ignore the --datarootdir setting
2741 $ @kbd{cat Makefile}
2742 prefix = /usr/local
2743 datadir = $@{prefix@}/share
2744 @end example
2746 Usually one can easily change the file to accommodate both older and newer
2747 Autoconf releases:
2749 @example
2750 $ @kbd{cat Makefile.in}
2751 prefix = @@prefix@@
2752 datarootdir = @@datarootdir@@
2753 datadir = @@datadir@@
2754 $ @kbd{configure}
2755 configure: creating ./config.status
2756 config.status: creating Makefile
2757 $ @kbd{cat Makefile}
2758 prefix = /usr/local
2759 datarootdir = $@{prefix@}/share
2760 datadir = $@{datarootdir@}
2761 @end example
2763 @acindex{DATAROOTDIR_CHECKED}
2764 In some cases, however, the checks may not be able to detect that a suitable
2765 initialization of @code{datarootdir} is in place, or they may fail to detect
2766 that such an initialization is necessary in the output file.  If, after
2767 auditing your package, there are still spurious @file{configure} warnings about
2768 @code{datarootdir}, you may add the line
2770 @example
2771 AC_DEFUN([AC_DATAROOTDIR_CHECKED])
2772 @end example
2774 @noindent
2775 to your @file{configure.ac} to disable the warnings.  This is an exception
2776 to the usual rule that you should not define a macro whose name begins with
2777 @code{AC_} (@pxref{Macro Names}).
2781 @node Build Directories
2782 @subsection Build Directories
2783 @cindex Build directories
2784 @cindex Directories, build
2786 You can support compiling a software package for several architectures
2787 simultaneously from the same copy of the source code.  The object files
2788 for each architecture are kept in their own directory.
2790 To support doing this, @command{make} uses the @code{VPATH} variable to
2791 find the files that are in the source directory.  @acronym{GNU} Make
2792 can do this.  Most other recent @command{make} programs can do this as
2793 well, though they may have difficulties and it is often simpler to
2794 recommend @acronym{GNU} @command{make} (@pxref{VPATH and Make}).  Older
2795 @command{make} programs do not support @code{VPATH}; when using them, the
2796 source code must be in the same directory as the object files.
2798 To support @code{VPATH}, each @file{Makefile.in} should contain two
2799 lines that look like:
2801 @example
2802 srcdir = @@srcdir@@
2803 VPATH = @@srcdir@@
2804 @end example
2806 Do not set @code{VPATH} to the value of another variable, for example
2807 @samp{VPATH = $(srcdir)}, because some versions of @command{make} do not do
2808 variable substitutions on the value of @code{VPATH}.
2810 @command{configure} substitutes the correct value for @code{srcdir} when
2811 it produces @file{Makefile}.
2813 Do not use the @code{make} variable @code{$<}, which expands to the
2814 file name of the file in the source directory (found with @code{VPATH}),
2815 except in implicit rules.  (An implicit rule is one such as @samp{.c.o},
2816 which tells how to create a @file{.o} file from a @file{.c} file.)  Some
2817 versions of @command{make} do not set @code{$<} in explicit rules; they
2818 expand it to an empty value.
2820 Instead, Make command lines should always refer to source
2821 files by prefixing them with @samp{$(srcdir)/}.  For example:
2823 @example
2824 time.info: time.texinfo
2825         $(MAKEINFO) '$(srcdir)/time.texinfo'
2826 @end example
2828 @node Automatic Remaking
2829 @subsection Automatic Remaking
2830 @cindex Automatic remaking
2831 @cindex Remaking automatically
2833 You can put rules like the following in the top-level @file{Makefile.in}
2834 for a package to automatically update the configuration information when
2835 you change the configuration files.  This example includes all of the
2836 optional files, such as @file{aclocal.m4} and those related to
2837 configuration header files.  Omit from the @file{Makefile.in} rules for
2838 any of these files that your package does not use.
2840 The @samp{$(srcdir)/} prefix is included because of limitations in the
2841 @code{VPATH} mechanism.
2843 The @file{stamp-} files are necessary because the timestamps of
2844 @file{config.h.in} and @file{config.h} are not changed if remaking
2845 them does not change their contents.  This feature avoids unnecessary
2846 recompilation.  You should include the file @file{stamp-h.in} your
2847 package's distribution, so that @command{make} considers
2848 @file{config.h.in} up to date.  Don't use @command{touch}
2849 (@pxref{Limitations of Usual Tools}); instead, use @command{echo} (using
2850 @command{date} would cause needless differences, hence @acronym{CVS}
2851 conflicts, etc.).
2853 @example
2854 @group
2855 $(srcdir)/configure: configure.ac aclocal.m4
2856         cd '$(srcdir)' && autoconf
2858 # autoheader might not change config.h.in, so touch a stamp file.
2859 $(srcdir)/config.h.in: stamp-h.in
2860 $(srcdir)/stamp-h.in: configure.ac aclocal.m4
2861         cd '$(srcdir)' && autoheader
2862         echo timestamp > '$(srcdir)/stamp-h.in'
2864 config.h: stamp-h
2865 stamp-h: config.h.in config.status
2866         ./config.status
2868 Makefile: Makefile.in config.status
2869         ./config.status
2871 config.status: configure
2872         ./config.status --recheck
2873 @end group
2874 @end example
2876 @noindent
2877 (Be careful if you copy these lines directly into your makefile, as you
2878 need to convert the indented lines to start with the tab character.)
2880 In addition, you should use
2882 @example
2883 AC_CONFIG_FILES([stamp-h], [echo timestamp > stamp-h])
2884 @end example
2886 @noindent
2887 so @file{config.status} ensures that @file{config.h} is considered up to
2888 date.  @xref{Output}, for more information about @code{AC_OUTPUT}.
2890 @xref{config.status Invocation}, for more examples of handling
2891 configuration-related dependencies.
2893 @node Configuration Headers
2894 @section Configuration Header Files
2895 @cindex Configuration Header
2896 @cindex @file{config.h}
2898 When a package contains more than a few tests that define C preprocessor
2899 symbols, the command lines to pass @option{-D} options to the compiler
2900 can get quite long.  This causes two problems.  One is that the
2901 @command{make} output is hard to visually scan for errors.  More
2902 seriously, the command lines can exceed the length limits of some
2903 operating systems.  As an alternative to passing @option{-D} options to
2904 the compiler, @command{configure} scripts can create a C header file
2905 containing @samp{#define} directives.  The @code{AC_CONFIG_HEADERS}
2906 macro selects this kind of output.  Though it can be called anywhere
2907 between @code{AC_INIT} and @code{AC_OUTPUT}, it is customary to call
2908 it right after @code{AC_INIT}.
2910 The package should @samp{#include} the configuration header file before
2911 any other header files, to prevent inconsistencies in declarations (for
2912 example, if it redefines @code{const}).
2914 To provide for VPATH builds, remember to pass the C compiler a @option{-I.}
2915 option (or @option{-I..}; whichever directory contains @file{config.h}).
2916 Even if you use @samp{#include "config.h"}, the preprocessor searches only
2917 the directory of the currently read file, i.e., the source directory, not
2918 the build directory.
2920 With the appropriate @option{-I} option, you can use
2921 @samp{#include <config.h>}.  Actually, it's a good habit to use it,
2922 because in the rare case when the source directory contains another
2923 @file{config.h}, the build directory should be searched first.
2926 @defmac AC_CONFIG_HEADERS (@var{header} @dots{}, @ovar{cmds}, @ovar{init-cmds})
2927 @acindex{CONFIG_HEADERS}
2928 @cvindex HAVE_CONFIG_H
2929 This macro is one of the instantiating macros; see @ref{Configuration
2930 Actions}.  Make @code{AC_OUTPUT} create the file(s) in the
2931 blank-or-newline-separated list @var{header} containing C preprocessor
2932 @code{#define} statements, and replace @samp{@@DEFS@@} in generated
2933 files with @option{-DHAVE_CONFIG_H} instead of the value of @code{DEFS}.
2934 The usual name for @var{header} is @file{config.h}.
2936 If @var{header} already exists and its contents are identical to what
2937 @code{AC_OUTPUT} would put in it, it is left alone.  Doing this allows
2938 making some changes in the configuration without needlessly causing
2939 object files that depend on the header file to be recompiled.
2941 Usually the input file is named @file{@var{header}.in}; however, you can
2942 override the input file name by appending to @var{header} a
2943 colon-separated list of input files.  For example, you might need to make
2944 the input file name acceptable to @acronym{DOS} variants:
2946 @example
2947 AC_CONFIG_HEADERS([config.h:config.hin])
2948 @end example
2950 @end defmac
2952 @defmac AH_HEADER
2953 @ahindex{HEADER}
2954 This macro is defined as the name of the first declared config header
2955 and undefined if no config headers have been declared up to this point.
2956 A third-party macro may, for example, require use of a config header
2957 without invoking AC_CONFIG_HEADERS twice, like this:
2959 @example
2960 AC_CONFIG_COMMANDS_PRE(
2961         [m4_ifndef([AH_HEADER], [AC_CONFIG_HEADERS([config.h])])])
2962 @end example
2964 @end defmac
2966 @xref{Configuration Actions}, for more details on @var{header}.
2968 @menu
2969 * Header Templates::            Input for the configuration headers
2970 * autoheader Invocation::       How to create configuration templates
2971 * Autoheader Macros::           How to specify CPP templates
2972 @end menu
2974 @node Header Templates
2975 @subsection Configuration Header Templates
2976 @cindex Configuration Header Template
2977 @cindex Header templates
2978 @cindex @file{config.h.in}
2980 Your distribution should contain a template file that looks as you want
2981 the final header file to look, including comments, with @code{#undef}
2982 statements which are used as hooks.  For example, suppose your
2983 @file{configure.ac} makes these calls:
2985 @example
2986 AC_CONFIG_HEADERS([conf.h])
2987 AC_CHECK_HEADERS([unistd.h])
2988 @end example
2990 @noindent
2991 Then you could have code like the following in @file{conf.h.in}.  On
2992 systems that have @file{unistd.h}, @command{configure} defines
2993 @samp{HAVE_UNISTD_H} to 1.  On other systems, the whole line is
2994 commented out (in case the system predefines that symbol).
2996 @example
2997 @group
2998 /* Define as 1 if you have unistd.h.  */
2999 #undef HAVE_UNISTD_H
3000 @end group
3001 @end example
3003 Pay attention that @samp{#undef} is in the first column, and there is
3004 nothing after @samp{HAVE_UNISTD_H}, not even white space.  You can
3005 then decode the configuration header using the preprocessor directives:
3007 @example
3008 @group
3009 #include <conf.h>
3011 #ifdef HAVE_UNISTD_H
3012 # include <unistd.h>
3013 #else
3014 /* We are in trouble.  */
3015 #endif
3016 @end group
3017 @end example
3019 The use of old form templates, with @samp{#define} instead of
3020 @samp{#undef} is strongly discouraged.  Similarly with old templates
3021 with comments on the same line as the @samp{#undef}.  Anyway, putting
3022 comments in preprocessor macros has never been a good idea.
3024 Since it is a tedious task to keep a template header up to date, you may
3025 use @command{autoheader} to generate it, see @ref{autoheader Invocation}.
3028 @node autoheader Invocation
3029 @subsection Using @command{autoheader} to Create @file{config.h.in}
3030 @cindex @command{autoheader}
3032 The @command{autoheader} program can create a template file of C
3033 @samp{#define} statements for @command{configure} to use.
3034 It searches for the first invocation of @code{AC_CONFIG_HEADERS} in
3035 @file{configure} sources to determine the name of the template.
3036 (If the first call of @code{AC_CONFIG_HEADERS} specifies more than one
3037 input file name, @command{autoheader} uses the first one.)
3039 It is recommended that only one input file is used.  If you want to append
3040 a boilerplate code, it is preferable to use
3041 @samp{AH_BOTTOM([#include <conf_post.h>])}.
3042 File @file{conf_post.h} is not processed during the configuration then,
3043 which make things clearer.  Analogically, @code{AH_TOP} can be used to
3044 prepend a boilerplate code.
3046 In order to do its job, @command{autoheader} needs you to document all
3047 of the symbols that you might use.  Typically this is done via an
3048 @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED} call whose first argument
3049 is a literal symbol and whose third argument describes the symbol
3050 (@pxref{Defining Symbols}).  Alternatively, you can use
3051 @code{AH_TEMPLATE} (@pxref{Autoheader Macros}), or you can supply a
3052 suitable input file for a subsequent configuration header file.
3053 Symbols defined by Autoconf's builtin tests are already documented properly;
3054 you need to document only those that you
3055 define yourself.
3057 You might wonder why @command{autoheader} is needed: after all, why
3058 would @command{configure} need to ``patch'' a @file{config.h.in} to
3059 produce a @file{config.h} instead of just creating @file{config.h} from
3060 scratch?  Well, when everything rocks, the answer is just that we are
3061 wasting our time maintaining @command{autoheader}: generating
3062 @file{config.h} directly is all that is needed.  When things go wrong,
3063 however, you'll be thankful for the existence of @command{autoheader}.
3065 The fact that the symbols are documented is important in order to
3066 @emph{check} that @file{config.h} makes sense.  The fact that there is a
3067 well-defined list of symbols that should be defined (or not) is
3068 also important for people who are porting packages to environments where
3069 @command{configure} cannot be run: they just have to @emph{fill in the
3070 blanks}.
3072 But let's come back to the point: the invocation of @command{autoheader}@dots{}
3074 If you give @command{autoheader} an argument, it uses that file instead
3075 of @file{configure.ac} and writes the header file to the standard output
3076 instead of to @file{config.h.in}.  If you give @command{autoheader} an
3077 argument of @option{-}, it reads the standard input instead of
3078 @file{configure.ac} and writes the header file to the standard output.
3080 @command{autoheader} accepts the following options:
3082 @table @option
3083 @item --help
3084 @itemx -h
3085 Print a summary of the command line options and exit.
3087 @item --version
3088 @itemx -V
3089 Print the version number of Autoconf and exit.
3091 @item --verbose
3092 @itemx -v
3093 Report processing steps.
3095 @item --debug
3096 @itemx -d
3097 Don't remove the temporary files.
3099 @item --force
3100 @itemx -f
3101 Remake the template file even if newer than its input files.
3103 @item --include=@var{dir}
3104 @itemx -I @var{dir}
3105 Append @var{dir} to the include path.  Multiple invocations accumulate.
3107 @item --prepend-include=@var{dir}
3108 @item -B @var{dir}
3109 Prepend @var{dir} to the include path.  Multiple invocations accumulate.
3111 @item --warnings=@var{category}
3112 @itemx -W @var{category}
3113 @evindex WARNINGS
3114 Report the warnings related to @var{category} (which can actually be a
3115 comma separated list).  Current categories include:
3117 @table @samp
3118 @item obsolete
3119 report the uses of obsolete constructs
3121 @item all
3122 report all the warnings
3124 @item none
3125 report none
3127 @item error
3128 treats warnings as errors
3130 @item no-@var{category}
3131 disable warnings falling into @var{category}
3132 @end table
3134 @end table
3138 @node Autoheader Macros
3139 @subsection Autoheader Macros
3140 @cindex Autoheader macros
3142 @command{autoheader} scans @file{configure.ac} and figures out which C
3143 preprocessor symbols it might define.  It knows how to generate
3144 templates for symbols defined by @code{AC_CHECK_HEADERS},
3145 @code{AC_CHECK_FUNCS} etc., but if you @code{AC_DEFINE} any additional
3146 symbol, you must define a template for it.  If there are missing
3147 templates, @command{autoheader} fails with an error message.
3149 The template for a @var{symbol} is created
3150 by @command{autoheader} from
3151 the @var{description} argument to an @code{AC_DEFINE};
3152 see @ref{Defining Symbols}.
3154 For special needs, you can use the following macros.
3157 @defmac AH_TEMPLATE (@var{key}, @var{description})
3158 @ahindex{TEMPLATE}
3159 Tell @command{autoheader} to generate a template for @var{key}.  This macro
3160 generates standard templates just like @code{AC_DEFINE} when a
3161 @var{description} is given.
3163 For example:
3165 @example
3166 AH_TEMPLATE([CRAY_STACKSEG_END],
3167             [Define to one of _getb67, GETB67, getb67
3168              for Cray-2 and Cray-YMP systems.  This
3169              function is required for alloca.c support
3170              on those systems.])
3171 @end example
3173 @noindent
3174 generates the following template, with the description properly
3175 justified.
3177 @example
3178 /* Define to one of _getb67, GETB67, getb67 for Cray-2 and
3179    Cray-YMP systems.  This function is required for alloca.c
3180    support on those systems.  */
3181 #undef CRAY_STACKSEG_END
3182 @end example
3183 @end defmac
3186 @defmac AH_VERBATIM (@var{key}, @var{template})
3187 @ahindex{VERBATIM}
3188 Tell @command{autoheader} to include the @var{template} as-is in the header
3189 template file.  This @var{template} is associated with the @var{key},
3190 which is used to sort all the different templates and guarantee their
3191 uniqueness.  It should be a symbol that can be defined via @code{AC_DEFINE}.
3192 @end defmac
3195 @defmac AH_TOP (@var{text})
3196 @ahindex{TOP}
3197 Include @var{text} at the top of the header template file.
3198 @end defmac
3201 @defmac AH_BOTTOM (@var{text})
3202 @ahindex{BOTTOM}
3203 Include @var{text} at the bottom of the header template file.
3204 @end defmac
3207 Please note that @var{text} gets included ``verbatim'' to the template file,
3208 not to the resulting config header, so it can easily get mangled when the
3209 template is processed.  There is rarely a need for something other than
3211 @example
3212 AH_BOTTOM([#include <custom.h>])
3213 @end example
3217 @node Configuration Commands
3218 @section Running Arbitrary Configuration Commands
3219 @cindex Configuration commands
3220 @cindex Commands for configuration
3222 You can execute arbitrary commands before, during, and after
3223 @file{config.status} is run.  The three following macros accumulate the
3224 commands to run when they are called multiple times.
3225 @code{AC_CONFIG_COMMANDS} replaces the obsolete macro
3226 @code{AC_OUTPUT_COMMANDS}; see @ref{Obsolete Macros}, for details.
3228 @defmac AC_CONFIG_COMMANDS (@var{tag}@dots{}, @ovar{cmds}, @ovar{init-cmds})
3229 @acindex{CONFIG_COMMANDS}
3230 Specify additional shell commands to run at the end of
3231 @file{config.status}, and shell commands to initialize any variables
3232 from @command{configure}.  Associate the commands with @var{tag}.
3233 Since typically the @var{cmds} create a file, @var{tag} should
3234 naturally be the name of that file.  If needed, the directory hosting
3235 @var{tag} is created.  This macro is one of the instantiating macros;
3236 see @ref{Configuration Actions}.
3238 Here is an unrealistic example:
3239 @example
3240 fubar=42
3241 AC_CONFIG_COMMANDS([fubar],
3242                    [echo this is extra $fubar, and so on.],
3243                    [fubar=$fubar])
3244 @end example
3246 Here is a better one:
3247 @example
3248 AC_CONFIG_COMMANDS([timestamp], [date >timestamp])
3249 @end example
3250 @end defmac
3252 The following two macros look similar, but in fact they are not of the same
3253 breed: they are executed directly by @file{configure}, so you cannot use
3254 @file{config.status} to rerun them.
3256 @c Yet it is good to leave them here.  The user sees them together and
3257 @c decides which best fits their needs.
3259 @defmac AC_CONFIG_COMMANDS_PRE (@var{cmds})
3260 @acindex{CONFIG_COMMANDS_PRE}
3261 Execute the @var{cmds} right before creating @file{config.status}.
3263 This macro presents the last opportunity to call @code{AC_SUBST},
3264 @code{AC_DEFINE}, or @code{AC_CONFIG_FOOS} macros.
3265 @end defmac
3267 @defmac AC_CONFIG_COMMANDS_POST (@var{cmds})
3268 @acindex{CONFIG_COMMANDS_POST}
3269 Execute the @var{cmds} right after creating @file{config.status}.
3270 @end defmac
3275 @node Configuration Links
3276 @section Creating Configuration Links
3277 @cindex Configuration links
3278 @cindex Links for configuration
3280 You may find it convenient to create links whose destinations depend upon
3281 results of tests.  One can use @code{AC_CONFIG_COMMANDS} but the
3282 creation of relative symbolic links can be delicate when the package is
3283 built in a directory different from the source directory.
3285 @defmac AC_CONFIG_LINKS (@var{dest}:@var{source}@dots{}, @ovar{cmds}, @ovar{init-cmds})
3286 @acindex{CONFIG_LINKS}
3287 @cindex Links
3288 Make @code{AC_OUTPUT} link each of the existing files @var{source} to
3289 the corresponding link name @var{dest}.  Makes a symbolic link if
3290 possible, otherwise a hard link if possible, otherwise a copy.  The
3291 @var{dest} and @var{source} names should be relative to the top level
3292 source or build directory.  This macro is one of the instantiating
3293 macros; see @ref{Configuration Actions}.
3295 For example, this call:
3297 @example
3298 AC_CONFIG_LINKS([host.h:config/$machine.h
3299                 object.h:config/$obj_format.h])
3300 @end example
3302 @noindent
3303 creates in the current directory @file{host.h} as a link to
3304 @file{@var{srcdir}/config/$machine.h}, and @file{object.h} as a
3305 link to @file{@var{srcdir}/config/$obj_format.h}.
3307 The tempting value @samp{.} for @var{dest} is invalid: it makes it
3308 impossible for @samp{config.status} to guess the links to establish.
3310 One can then run:
3311 @example
3312 ./config.status host.h object.h
3313 @end example
3314 @noindent
3315 to create the links.
3316 @end defmac
3320 @node Subdirectories
3321 @section Configuring Other Packages in Subdirectories
3322 @cindex Configure subdirectories
3323 @cindex Subdirectory configure
3325 In most situations, calling @code{AC_OUTPUT} is sufficient to produce
3326 makefiles in subdirectories.  However, @command{configure} scripts
3327 that control more than one independent package can use
3328 @code{AC_CONFIG_SUBDIRS} to run @command{configure} scripts for other
3329 packages in subdirectories.
3331 @defmac AC_CONFIG_SUBDIRS (@var{dir} @dots{})
3332 @acindex{CONFIG_SUBDIRS}
3333 @ovindex subdirs
3334 Make @code{AC_OUTPUT} run @command{configure} in each subdirectory
3335 @var{dir} in the given blank-or-newline-separated list.  Each @var{dir} should
3336 be a literal, i.e., please do not use:
3338 @example
3339 if test "$package_foo_enabled" = yes; then
3340   $my_subdirs="$my_subdirs foo"
3342 AC_CONFIG_SUBDIRS([$my_subdirs])
3343 @end example
3345 @noindent
3346 because this prevents @samp{./configure --help=recursive} from
3347 displaying the options of the package @code{foo}.  Instead, you should
3348 write:
3350 @example
3351 if test "$package_foo_enabled" = yes; then
3352   AC_CONFIG_SUBDIRS([foo])
3354 @end example
3356 If a given @var{dir} is not found, an error is reported: if the
3357 subdirectory is optional, write:
3359 @example
3360 if test -d "$srcdir/foo"; then
3361   AC_CONFIG_SUBDIRS([foo])
3363 @end example
3365 @c NB: Yes, below we mean configure.in, not configure.ac.
3366 If a given @var{dir} contains @command{configure.gnu}, it is run instead
3367 of @command{configure}.  This is for packages that might use a
3368 non-Autoconf script @command{Configure}, which can't be called through a
3369 wrapper @command{configure} since it would be the same file on
3370 case-insensitive file systems.  Likewise, if a @var{dir} contains
3371 @file{configure.in} but no @command{configure}, the Cygnus
3372 @command{configure} script found by @code{AC_CONFIG_AUX_DIR} is used.
3374 The subdirectory @command{configure} scripts are given the same command
3375 line options that were given to this @command{configure} script, with minor
3376 changes if needed, which include:
3378 @itemize @minus
3379 @item
3380 adjusting a relative name for the cache file;
3382 @item
3383 adjusting a relative name for the source directory;
3385 @item
3386 propagating the current value of @code{$prefix}, including if it was
3387 defaulted, and if the default values of the top level and of the subdirectory
3388 @file{configure} differ.
3389 @end itemize
3391 This macro also sets the output variable @code{subdirs} to the list of
3392 directories @samp{@var{dir} @dots{}}.  Make rules can use
3393 this variable to determine which subdirectories to recurse into.
3395 This macro may be called multiple times.
3396 @end defmac
3398 @node Default Prefix
3399 @section Default Prefix
3400 @cindex Install prefix
3401 @cindex Prefix for install
3403 By default, @command{configure} sets the prefix for files it installs to
3404 @file{/usr/local}.  The user of @command{configure} can select a different
3405 prefix using the @option{--prefix} and @option{--exec-prefix} options.
3406 There are two ways to change the default: when creating
3407 @command{configure}, and when running it.
3409 Some software packages might want to install in a directory other than
3410 @file{/usr/local} by default.  To accomplish that, use the
3411 @code{AC_PREFIX_DEFAULT} macro.
3413 @defmac AC_PREFIX_DEFAULT (@var{prefix})
3414 @acindex{PREFIX_DEFAULT}
3415 Set the default installation prefix to @var{prefix} instead of
3416 @file{/usr/local}.
3417 @end defmac
3419 It may be convenient for users to have @command{configure} guess the
3420 installation prefix from the location of a related program that they
3421 have already installed.  If you wish to do that, you can call
3422 @code{AC_PREFIX_PROGRAM}.
3424 @defmac AC_PREFIX_PROGRAM (@var{program})
3425 @acindex{PREFIX_PROGRAM}
3426 If the user did not specify an installation prefix (using the
3427 @option{--prefix} option), guess a value for it by looking for
3428 @var{program} in @env{PATH}, the way the shell does.  If @var{program}
3429 is found, set the prefix to the parent of the directory containing
3430 @var{program}, else default the prefix as described above
3431 (@file{/usr/local} or @code{AC_PREFIX_DEFAULT}).  For example, if
3432 @var{program} is @code{gcc} and the @env{PATH} contains
3433 @file{/usr/local/gnu/bin/gcc}, set the prefix to @file{/usr/local/gnu}.
3434 @end defmac
3438 @c ======================================================== Existing tests
3440 @node Existing Tests
3441 @chapter Existing Tests
3443 These macros test for particular system features that packages might
3444 need or want to use.  If you need to test for a kind of feature that
3445 none of these macros check for, you can probably do it by calling
3446 primitive test macros with appropriate arguments (@pxref{Writing
3447 Tests}).
3449 These tests print messages telling the user which feature they're
3450 checking for, and what they find.  They cache their results for future
3451 @command{configure} runs (@pxref{Caching Results}).
3453 Some of these macros set output variables.  @xref{Makefile
3454 Substitutions}, for how to get their values.  The phrase ``define
3455 @var{name}'' is used below as a shorthand to mean ``define the C
3456 preprocessor symbol @var{name} to the value 1''.  @xref{Defining
3457 Symbols}, for how to get those symbol definitions into your program.
3459 @menu
3460 * Common Behavior::             Macros' standard schemes
3461 * Alternative Programs::        Selecting between alternative programs
3462 * Files::                       Checking for the existence of files
3463 * Libraries::                   Library archives that might be missing
3464 * Library Functions::           C library functions that might be missing
3465 * Header Files::                Header files that might be missing
3466 * Declarations::                Declarations that may be missing
3467 * Structures::                  Structures or members that might be missing
3468 * Types::                       Types that might be missing
3469 * Compilers and Preprocessors::  Checking for compiling programs
3470 * System Services::             Operating system services
3471 * Posix Variants::              Special kludges for specific Posix variants
3472 * Erlang Libraries::            Checking for the existence of Erlang libraries
3473 @end menu
3475 @node Common Behavior
3476 @section Common Behavior
3477 @cindex Common autoconf behavior
3479 Much effort has been expended to make Autoconf easy to learn.  The most
3480 obvious way to reach this goal is simply to enforce standard interfaces
3481 and behaviors, avoiding exceptions as much as possible.  Because of
3482 history and inertia, unfortunately, there are still too many exceptions
3483 in Autoconf; nevertheless, this section describes some of the common
3484 rules.
3486 @menu
3487 * Standard Symbols::            Symbols defined by the macros
3488 * Default Includes::            Includes used by the generic macros
3489 @end menu
3491 @node Standard Symbols
3492 @subsection Standard Symbols
3493 @cindex Standard symbols
3495 All the generic macros that @code{AC_DEFINE} a symbol as a result of
3496 their test transform their @var{argument} values to a standard alphabet.
3497 First, @var{argument} is converted to upper case and any asterisks
3498 (@samp{*}) are each converted to @samp{P}.  Any remaining characters
3499 that are not alphanumeric are converted to underscores.
3501 For instance,
3503 @example
3504 AC_CHECK_TYPES([struct $Expensive*])
3505 @end example
3507 @noindent
3508 defines the symbol @samp{HAVE_STRUCT__EXPENSIVEP} if the check
3509 succeeds.
3512 @node Default Includes
3513 @subsection Default Includes
3514 @cindex Default includes
3515 @cindex Includes, default
3517 Several tests depend upon a set of header files.  Since these headers
3518 are not universally available, tests actually have to provide a set of
3519 protected includes, such as:
3521 @example
3522 @group
3523 #ifdef TIME_WITH_SYS_TIME
3524 # include <sys/time.h>
3525 # include <time.h>
3526 #else
3527 # ifdef HAVE_SYS_TIME_H
3528 #  include <sys/time.h>
3529 # else
3530 #  include <time.h>
3531 # endif
3532 #endif
3533 @end group
3534 @end example
3536 @noindent
3537 Unless you know exactly what you are doing, you should avoid using
3538 unconditional includes, and check the existence of the headers you
3539 include beforehand (@pxref{Header Files}).
3541 Most generic macros use the following macro to provide the default set
3542 of includes:
3544 @defmac AC_INCLUDES_DEFAULT (@ovar{include-directives})
3545 @acindex{INCLUDES_DEFAULT}
3546 Expand to @var{include-directives} if defined, otherwise to:
3548 @example
3549 @group
3550 #include <stdio.h>
3551 #ifdef HAVE_SYS_TYPES_H
3552 # include <sys/types.h>
3553 #endif
3554 #ifdef HAVE_SYS_STAT_H
3555 # include <sys/stat.h>
3556 #endif
3557 #ifdef STDC_HEADERS
3558 # include <stdlib.h>
3559 # include <stddef.h>
3560 #else
3561 # ifdef HAVE_STDLIB_H
3562 #  include <stdlib.h>
3563 # endif
3564 #endif
3565 #ifdef HAVE_STRING_H
3566 # if !defined STDC_HEADERS && defined HAVE_MEMORY_H
3567 #  include <memory.h>
3568 # endif
3569 # include <string.h>
3570 #endif
3571 #ifdef HAVE_STRINGS_H
3572 # include <strings.h>
3573 #endif
3574 #ifdef HAVE_INTTYPES_H
3575 # include <inttypes.h>
3576 #endif
3577 #ifdef HAVE_STDINT_H
3578 # include <stdint.h>
3579 #endif
3580 #ifdef HAVE_UNISTD_H
3581 # include <unistd.h>
3582 #endif
3583 @end group
3584 @end example
3586 If the default includes are used, then check for the presence of these
3587 headers and their compatibility, i.e., you don't need to run
3588 @code{AC_HEADER_STDC}, nor check for @file{stdlib.h} etc.
3590 These headers are checked for in the same order as they are included.
3591 For instance, on some systems @file{string.h} and @file{strings.h} both
3592 exist, but conflict.  Then @code{HAVE_STRING_H} is defined, not
3593 @code{HAVE_STRINGS_H}.
3594 @end defmac
3596 @node Alternative Programs
3597 @section Alternative Programs
3598 @cindex Programs, checking
3600 These macros check for the presence or behavior of particular programs.
3601 They are used to choose between several alternative programs and to
3602 decide what to do once one has been chosen.  If there is no macro
3603 specifically defined to check for a program you need, and you don't need
3604 to check for any special properties of it, then you can use one of the
3605 general program-check macros.
3607 @menu
3608 * Particular Programs::         Special handling to find certain programs
3609 * Generic Programs::            How to find other programs
3610 @end menu
3612 @node Particular Programs
3613 @subsection Particular Program Checks
3615 These macros check for particular programs---whether they exist, and
3616 in some cases whether they support certain features.
3618 @defmac AC_PROG_AWK
3619 @acindex{PROG_AWK}
3620 @ovindex AWK
3621 Check for @code{gawk}, @code{mawk}, @code{nawk}, and @code{awk}, in that
3622 order, and set output variable @code{AWK} to the first one that is found.
3623 It tries @code{gawk} first because that is reported to be the
3624 best implementation.
3625 @end defmac
3627 @defmac AC_PROG_GREP
3628 @acindex{PROG_GREP}
3629 @ovindex GREP
3630 Look for the best available @code{grep} or @code{ggrep} that accepts the
3631 longest input lines possible, and that supports multiple @option{-e} options.
3632 Set the output variable @code{GREP} to whatever is chosen.
3633 @xref{Limitations of Usual Tools}, for more information about
3634 portability problems with the @command{grep} command family.
3635 @end defmac
3637 @defmac AC_PROG_EGREP
3638 @acindex{PROG_EGREP}
3639 @ovindex EGREP
3640 Check whether @code{$GREP -E} works, or else look for the best available
3641 @code{egrep} or @code{gegrep} that accepts the longest input lines possible.
3642 Set the output variable @code{EGREP} to whatever is chosen.
3643 @end defmac
3645 @defmac AC_PROG_FGREP
3646 @acindex{PROG_FGREP}
3647 @ovindex FGREP
3648 Check whether @code{$GREP -F} works, or else look for the best available
3649 @code{fgrep} or @code{gfgrep} that accepts the longest input lines possible.
3650 Set the output variable @code{FGREP} to whatever is chosen.
3651 @end defmac
3653 @defmac AC_PROG_INSTALL
3654 @acindex{PROG_INSTALL}
3655 @ovindex INSTALL
3656 @ovindex INSTALL_PROGRAM
3657 @ovindex INSTALL_DATA
3658 @ovindex INSTALL_SCRIPT
3659 Set output variable @code{INSTALL} to the name of a @acronym{BSD}-compatible
3660 @command{install} program, if one is found in the current @env{PATH}.
3661 Otherwise, set @code{INSTALL} to @samp{@var{dir}/install-sh -c},
3662 checking the directories specified to @code{AC_CONFIG_AUX_DIR} (or its
3663 default directories) to determine @var{dir} (@pxref{Output}).  Also set
3664 the variables @code{INSTALL_PROGRAM} and @code{INSTALL_SCRIPT} to
3665 @samp{$@{INSTALL@}} and @code{INSTALL_DATA} to @samp{$@{INSTALL@} -m 644}.
3667 @samp{@@INSTALL@@} is special, as its value may vary for different
3668 configuration files.
3670 This macro screens out various instances of @command{install} known not to
3671 work.  It prefers to find a C program rather than a shell script, for
3672 speed.  Instead of @file{install-sh}, it can also use @file{install.sh},
3673 but that name is obsolete because some @command{make} programs have a rule
3674 that creates @file{install} from it if there is no makefile.
3676 Autoconf comes with a copy of @file{install-sh} that you can use.  If
3677 you use @code{AC_PROG_INSTALL}, you must include either
3678 @file{install-sh} or @file{install.sh} in your distribution; otherwise
3679 @command{configure} produces an error message saying it can't find
3680 them---even if the system you're on has a good @command{install} program.
3681 This check is a safety measure to prevent you from accidentally leaving
3682 that file out, which would prevent your package from installing on
3683 systems that don't have a @acronym{BSD}-compatible @command{install} program.
3685 If you need to use your own installation program because it has features
3686 not found in standard @command{install} programs, there is no reason to use
3687 @code{AC_PROG_INSTALL}; just put the file name of your program into your
3688 @file{Makefile.in} files.
3689 @end defmac
3691 @defmac AC_PROG_MKDIR_P
3692 @acindex{PROG_MKDIR_P}
3693 @ovindex MKDIR_P
3694 Set output variable @code{MKDIR_P} to a program that ensures that for
3695 each argument, a directory named by this argument exists, creating it
3696 and its parent directories if needed, and without race conditions when
3697 two instances of the program attempt to make the same directory at
3698 nearly the same time.
3700 This macro uses the @samp{mkdir -p} command if possible.  Otherwise, it
3701 falls back on invoking @command{install-sh} with the @option{-d} option,
3702 so your package should
3703 contain @file{install-sh} as described under @code{AC_PROG_INSTALL}.
3704 An @file{install-sh} file that predates Autoconf 2.60 or Automake 1.10
3705 is vulnerable to race conditions, so if you want to support parallel
3706 installs from
3707 different packages into the same directory you need to make sure you
3708 have an up-to-date @file{install-sh}.  In particular, be careful about
3709 using @samp{autoreconf -if} if your Automake predates Automake 1.10.
3711 This macro is related to the @code{AS_MKDIR_P} macro (@pxref{Programming
3712 in M4sh}), but it sets an output variable intended for use in other
3713 files, whereas @code{AS_MKDIR_P} is intended for use in scripts like
3714 @command{configure}.  Also, @code{AS_MKDIR_P} does not accept options,
3715 but @code{MKDIR_P} supports the @option{-m} option, e.g., a makefile
3716 might invoke @code{$(MKDIR_P) -m 0 dir} to create an inaccessible
3717 directory, and conversely a makefile should use @code{$(MKDIR_P) --
3718 $(FOO)} if @var{FOO} might yield a value that begins with @samp{-}.
3719 Finally, @code{AS_MKDIR_P} does not check for race condition
3720 vulnerability, whereas @code{AC_PROG_MKDIR_P} does.
3722 @samp{@@MKDIR_P@@} is special, as its value may vary for different
3723 configuration files.
3724 @end defmac
3726 @defmac AC_PROG_LEX
3727 @acindex{PROG_LEX}
3728 @ovindex LEX
3729 @ovindex LEXLIB
3730 @cvindex YYTEXT_POINTER
3731 @ovindex LEX_OUTPUT_ROOT
3732 If @code{flex} is found, set output variable @code{LEX} to @samp{flex}
3733 and @code{LEXLIB} to @option{-lfl}, if that library is in a standard
3734 place.  Otherwise set @code{LEX} to @samp{lex} and @code{LEXLIB} to
3735 @option{-ll}.
3737 Define @code{YYTEXT_POINTER} if @code{yytext} defaults to @samp{char *} instead
3738 of to @samp{char []}.  Also set output variable @code{LEX_OUTPUT_ROOT} to
3739 the base of the file name that the lexer generates; usually
3740 @file{lex.yy}, but sometimes something else.  These results vary
3741 according to whether @code{lex} or @code{flex} is being used.
3743 You are encouraged to use Flex in your sources, since it is both more
3744 pleasant to use than plain Lex and the C source it produces is portable.
3745 In order to ensure portability, however, you must either provide a
3746 function @code{yywrap} or, if you don't use it (e.g., your scanner has
3747 no @samp{#include}-like feature), simply include a @samp{%noyywrap}
3748 statement in the scanner's source.  Once this done, the scanner is
3749 portable (unless @emph{you} felt free to use nonportable constructs) and
3750 does not depend on any library.  In this case, and in this case only, it
3751 is suggested that you use this Autoconf snippet:
3753 @example
3754 AC_PROG_LEX
3755 if test "$LEX" != flex; then
3756   LEX="$SHELL $missing_dir/missing flex"
3757   AC_SUBST([LEX_OUTPUT_ROOT], [lex.yy])
3758   AC_SUBST([LEXLIB], [''])
3760 @end example
3762 The shell script @command{missing} can be found in the Automake
3763 distribution.
3765 To ensure backward compatibility, Automake's @code{AM_PROG_LEX} invokes
3766 (indirectly) this macro twice, which causes an annoying but benign
3767 ``@code{AC_PROG_LEX} invoked multiple times'' warning.  Future versions
3768 of Automake will fix this issue; meanwhile, just ignore this message.
3770 As part of running the test, this macro may delete any file in the
3771 configuration directory named @file{lex.yy.c} or @file{lexyy.c}.
3772 @end defmac
3774 @defmac AC_PROG_LN_S
3775 @acindex{PROG_LN_S}
3776 @ovindex LN_S
3777 If @samp{ln -s} works on the current file system (the operating system
3778 and file system support symbolic links), set the output variable
3779 @code{LN_S} to @samp{ln -s}; otherwise, if @samp{ln} works, set
3780 @code{LN_S} to @samp{ln}, and otherwise set it to @samp{cp -p}.
3782 If you make a link in a directory other than the current directory, its
3783 meaning depends on whether @samp{ln} or @samp{ln -s} is used.  To safely
3784 create links using @samp{$(LN_S)}, either find out which form is used
3785 and adjust the arguments, or always invoke @code{ln} in the directory
3786 where the link is to be created.
3788 In other words, it does not work to do:
3789 @example
3790 $(LN_S) foo /x/bar
3791 @end example
3793 Instead, do:
3795 @example
3796 (cd /x && $(LN_S) foo bar)
3797 @end example
3798 @end defmac
3800 @defmac AC_PROG_RANLIB
3801 @acindex{PROG_RANLIB}
3802 @ovindex RANLIB
3803 Set output variable @code{RANLIB} to @samp{ranlib} if @code{ranlib}
3804 is found, and otherwise to @samp{:} (do nothing).
3805 @end defmac
3807 @defmac AC_PROG_SED
3808 @acindex{PROG_SED}
3809 @ovindex SED
3810 Set output variable @code{SED} to a Sed implementation that conforms to
3811 Posix and does not have arbitrary length limits.  Report an error if no
3812 acceptable Sed is found.  @xref{Limitations of Usual Tools}, for more
3813 information about portability problems with Sed.
3814 @end defmac
3816 @defmac AC_PROG_YACC
3817 @acindex{PROG_YACC}
3818 @ovindex YACC
3819 If @code{bison} is found, set output variable @code{YACC} to @samp{bison
3820 -y}.  Otherwise, if @code{byacc} is found, set @code{YACC} to
3821 @samp{byacc}.  Otherwise set @code{YACC} to @samp{yacc}.
3822 @end defmac
3824 @node Generic Programs
3825 @subsection Generic Program and File Checks
3827 These macros are used to find programs not covered by the ``particular''
3828 test macros.  If you need to check the behavior of a program as well as
3829 find out whether it is present, you have to write your own test for it
3830 (@pxref{Writing Tests}).  By default, these macros use the environment
3831 variable @env{PATH}.  If you need to check for a program that might not
3832 be in the user's @env{PATH}, you can pass a modified path to use
3833 instead, like this:
3835 @example
3836 AC_PATH_PROG([INETD], [inetd], [/usr/libexec/inetd],
3837              [$PATH:/usr/libexec:/usr/sbin:/usr/etc:/etc])
3838 @end example
3840 You are strongly encouraged to declare the @var{variable} passed to
3841 @code{AC_CHECK_PROG} etc.@: as precious, @xref{Setting Output Variables},
3842 @code{AC_ARG_VAR}, for more details.
3844 @defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @var{value-if-found}, @ovar{value-if-not-found}, @ovar{path},  @ovar{reject})
3845 @acindex{CHECK_PROG}
3846 Check whether program @var{prog-to-check-for} exists in @env{PATH}.  If
3847 it is found, set @var{variable} to @var{value-if-found}, otherwise to
3848 @var{value-if-not-found}, if given.  Always pass over @var{reject} (an
3849 absolute file name) even if it is the first found in the search path; in
3850 that case, set @var{variable} using the absolute file name of the
3851 @var{prog-to-check-for} found that is not @var{reject}.  If
3852 @var{variable} was already set, do nothing.  Calls @code{AC_SUBST} for
3853 @var{variable}.
3854 @end defmac
3856 @defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3857 @acindex{CHECK_PROGS}
3858 Check for each program in the blank-separated list
3859 @var{progs-to-check-for} existing in the @env{PATH}.  If one is found, set
3860 @var{variable} to the name of that program.  Otherwise, continue
3861 checking the next program in the list.  If none of the programs in the
3862 list are found, set @var{variable} to @var{value-if-not-found}; if
3863 @var{value-if-not-found} is not specified, the value of @var{variable}
3864 is not changed.  Calls @code{AC_SUBST} for @var{variable}.
3865 @end defmac
3867 @defmac AC_CHECK_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3868 @acindex{CHECK_TARGET_TOOL}
3869 Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
3870 with a prefix of the target type as determined by
3871 @code{AC_CANONICAL_TARGET}, followed by a dash (@pxref{Canonicalizing}).
3872 If the tool cannot be found with a prefix, and if the build and target
3873 types are equal, then it is also searched for without a prefix.
3875 As noted in @ref{Specifying Names, , Specifying the system type}, the
3876 target is rarely specified, because most of the time it is the same
3877 as the host: it is the type of system for which any compiler tool in
3878 the package produces code.  What this macro looks for is,
3879 for example, @emph{a tool @r{(assembler, linker, etc.)}@: that the
3880 compiler driver @r{(@command{gcc} for the @acronym{GNU} C Compiler)}
3881 uses to produce objects, archives or executables}.
3882 @end defmac
3884 @defmac AC_CHECK_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3885 @acindex{CHECK_TOOL}
3886 Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
3887 with a prefix of the host type as determined by
3888 @code{AC_CANONICAL_HOST}, followed by a dash (@pxref{Canonicalizing}).
3889 For example, if the user runs @samp{configure --host=i386-gnu}, then
3890 this call:
3891 @example
3892 AC_CHECK_TOOL([RANLIB], [ranlib], [:])
3893 @end example
3894 @noindent
3895 sets @code{RANLIB} to @file{i386-gnu-ranlib} if that program exists in
3896 @env{PATH}, or otherwise to @samp{ranlib} if that program exists in
3897 @env{PATH}, or to @samp{:} if neither program exists.
3899 In the future, when cross-compiling this macro will @emph{only}
3900 accept program names that are prefixed with the host type.
3901 For more information, see @ref{Specifying Names, , Specifying the
3902 system type}.
3903 @end defmac
3905 @defmac AC_CHECK_TARGET_TOOLS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3906 @acindex{CHECK_TARGET_TOOLS}
3907 Like @code{AC_CHECK_TARGET_TOOL}, each of the tools in the list
3908 @var{progs-to-check-for} are checked with a prefix of the target type as
3909 determined by @code{AC_CANONICAL_TARGET}, followed by a dash
3910 (@pxref{Canonicalizing}).  If none of the tools can be found with a
3911 prefix, and if the build and target types are equal, then the first one
3912 without a prefix is used.  If a tool is found, set @var{variable} to
3913 the name of that program.  If none of the tools in the list are found,
3914 set @var{variable} to @var{value-if-not-found}; if @var{value-if-not-found}
3915 is not specified, the value of @var{variable} is not changed.  Calls
3916 @code{AC_SUBST} for @var{variable}.
3917 @end defmac
3919 @defmac AC_CHECK_TOOLS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3920 @acindex{CHECK_TOOLS}
3921 Like @code{AC_CHECK_TOOL}, each of the tools in the list
3922 @var{progs-to-check-for} are checked with a prefix of the host type as
3923 determined by @code{AC_CANONICAL_HOST}, followed by a dash
3924 (@pxref{Canonicalizing}).  If none of the tools can be found with a
3925 prefix, then the first one without a prefix is used.  If a tool is found,
3926 set @var{variable} to the name of that program.  If none of the tools in
3927 the list are found, set @var{variable} to @var{value-if-not-found}; if
3928 @var{value-if-not-found} is not specified, the value of @var{variable}
3929 is not changed.  Calls @code{AC_SUBST} for @var{variable}.
3931 In the future, when cross-compiling this macro will @emph{not}
3932 accept program names that are not prefixed with the host type.
3933 @end defmac
3935 @defmac AC_PATH_PROG (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3936 @acindex{PATH_PROG}
3937 Like @code{AC_CHECK_PROG}, but set @var{variable} to the absolute
3938 name of @var{prog-to-check-for} if found.
3939 @end defmac
3941 @defmac AC_PATH_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3942 @acindex{PATH_PROGS}
3943 Like @code{AC_CHECK_PROGS}, but if any of @var{progs-to-check-for}
3944 are found, set @var{variable} to the absolute name of the program
3945 found.
3946 @end defmac
3948 @defmac AC_PATH_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3949 @acindex{PATH_TARGET_TOOL}
3950 Like @code{AC_CHECK_TARGET_TOOL}, but set @var{variable} to the absolute
3951 name of the program if it is found.
3952 @end defmac
3954 @defmac AC_PATH_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3955 @acindex{PATH_TOOL}
3956 Like @code{AC_CHECK_TOOL}, but set @var{variable} to the absolute
3957 name of the program if it is found.
3959 In the future, when cross-compiling this macro will @emph{not}
3960 accept program names that are not prefixed with the host type.
3961 @end defmac
3964 @node Files
3965 @section Files
3966 @cindex File, checking
3968 You might also need to check for the existence of files.  Before using
3969 these macros, ask yourself whether a runtime test might not be a better
3970 solution.  Be aware that, like most Autoconf macros, they test a feature
3971 of the host machine, and therefore, they die when cross-compiling.
3973 @defmac AC_CHECK_FILE (@var{file}, @ovar{action-if-found}, @ovar{action-if-not-found})
3974 @acindex{CHECK_FILE}
3975 Check whether file @var{file} exists on the native system.  If it is
3976 found, execute @var{action-if-found}, otherwise do
3977 @var{action-if-not-found}, if given.
3978 @end defmac
3980 @defmac AC_CHECK_FILES (@var{files}, @ovar{action-if-found}, @ovar{action-if-not-found})
3981 @acindex{CHECK_FILES}
3982 Executes @code{AC_CHECK_FILE} once for each file listed in @var{files}.
3983 Additionally, defines @samp{HAVE_@var{file}} (@pxref{Standard Symbols})
3984 for each file found.
3985 @end defmac
3988 @node Libraries
3989 @section Library Files
3990 @cindex Library, checking
3992 The following macros check for the presence of certain C, C++, or Fortran
3993 library archive files.
3995 @defmac AC_CHECK_LIB (@var{library}, @var{function}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
3996 @acindex{CHECK_LIB}
3997 Test whether the library @var{library} is available by trying to link
3998 a test program that calls function @var{function} with the library.
3999 @var{function} should be a function provided by the library.
4000 Use the base
4001 name of the library; e.g., to check for @option{-lmp}, use @samp{mp} as
4002 the @var{library} argument.
4004 @var{action-if-found} is a list of shell commands to run if the link
4005 with the library succeeds; @var{action-if-not-found} is a list of shell
4006 commands to run if the link fails.  If @var{action-if-found} is not
4007 specified, the default action prepends @option{-l@var{library}} to
4008 @code{LIBS} and defines @samp{HAVE_LIB@var{library}} (in all
4009 capitals).  This macro is intended to support building @code{LIBS} in
4010 a right-to-left (least-dependent to most-dependent) fashion such that
4011 library dependencies are satisfied as a natural side effect of
4012 consecutive tests.  Linkers are sensitive to library ordering
4013 so the order in which @code{LIBS} is generated is important to reliable
4014 detection of libraries.
4016 If linking with @var{library} results in unresolved symbols that would
4017 be resolved by linking with additional libraries, give those libraries
4018 as the @var{other-libraries} argument, separated by spaces:
4019 e.g., @option{-lXt -lX11}.  Otherwise, this macro fails to detect
4020 that @var{library} is present, because linking the test program
4021 always fails with unresolved symbols.  The @var{other-libraries} argument
4022 should be limited to cases where it is desirable to test for one library
4023 in the presence of another that is not already in @code{LIBS}.
4025 @code{AC_CHECK_LIB} requires some care in usage, and should be avoided
4026 in some common cases.  Many standard functions like @code{gethostbyname}
4027 appear in the standard C library on some hosts, and in special libraries
4028 like @code{nsl} on other hosts.  On some hosts the special libraries
4029 contain variant implementations that you may not want to use.  These
4030 days it is normally better to use @code{AC_SEARCH_LIBS([gethostbyname],
4031 [nsl])} instead of @code{AC_CHECK_LIB([nsl], [gethostbyname])}.
4032 @end defmac
4035 @defmac AC_SEARCH_LIBS (@var{function}, @var{search-libs}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
4036 @acindex{SEARCH_LIBS}
4037 Search for a library defining @var{function} if it's not already
4038 available.  This equates to calling
4039 @samp{AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])])} first with
4040 no libraries, then for each library listed in @var{search-libs}.
4042 Add @option{-l@var{library}} to @code{LIBS} for the first library found
4043 to contain @var{function}, and run @var{action-if-found}.  If the
4044 function is not found, run @var{action-if-not-found}.
4046 If linking with @var{library} results in unresolved symbols that would
4047 be resolved by linking with additional libraries, give those libraries
4048 as the @var{other-libraries} argument, separated by spaces:
4049 e.g., @option{-lXt -lX11}.  Otherwise, this macro fails to detect
4050 that @var{function} is present, because linking the test program
4051 always fails with unresolved symbols.
4052 @end defmac
4056 @node Library Functions
4057 @section Library Functions
4059 The following macros check for particular C library functions.
4060 If there is no macro specifically defined to check for a function you need,
4061 and you don't need to check for any special properties of
4062 it, then you can use one of the general function-check macros.
4064 @menu
4065 * Function Portability::        Pitfalls with usual functions
4066 * Particular Functions::        Special handling to find certain functions
4067 * Generic Functions::           How to find other functions
4068 @end menu
4070 @node Function Portability
4071 @subsection Portability of C Functions
4072 @cindex Portability of C functions
4073 @cindex C function portability
4075 Most usual functions can either be missing, or be buggy, or be limited
4076 on some architectures.  This section tries to make an inventory of these
4077 portability issues.  By definition, this list always requires
4078 additions.  Please help us keeping it as complete as possible.
4080 @table @asis
4081 @item @code{exit}
4082 @c @fuindex exit
4083 @prindex @code{exit}
4084 On ancient hosts, @code{exit} returned @code{int}.
4085 This is because @code{exit} predates @code{void}, and there was a long
4086 tradition of it returning @code{int}.
4088 On current hosts, the problem more likely is that @code{exit} is not
4089 declared, due to C++ problems of some sort or another.  For this reason
4090 we suggest that test programs not invoke @code{exit}, but return from
4091 @code{main} instead.
4093 @item @code{free}
4094 @c @fuindex free
4095 @prindex @code{free}
4096 The C standard says a call @code{free (NULL)} does nothing, but
4097 some old systems don't support this (e.g., NextStep).
4099 @item @code{isinf}
4100 @itemx @code{isnan}
4101 @c @fuindex isinf
4102 @c @fuindex isnan
4103 @prindex @code{isinf}
4104 @prindex @code{isnan}
4105 The C99 standard says that @code{isinf} and @code{isnan} are
4106 macros.  On some systems just macros are available
4107 (e.g., @acronym{HP-UX} and Solaris 10), on
4108 some systems both macros and functions (e.g., glibc 2.3.2), and on some
4109 systems only functions (e.g., IRIX 6 and Solaris 9).  In some cases
4110 these functions are declared in nonstandard headers like
4111 @code{<sunmath.h>} and defined in non-default libraries like
4112 @option{-lm} or @option{-lsunmath}.
4114 The C99 @code{isinf} and @code{isnan} macros work correctly with
4115 @code{long double} arguments, but pre-C99 systems that use functions
4116 typically assume @code{double} arguments.  On such a system,
4117 @code{isinf} incorrectly returns true for a finite @code{long double}
4118 argument that is outside the range of @code{double}.
4120 To work around this porting mess, you can use code like the following.
4122 @smallexample
4123 #include <math.h>
4125 #ifndef isnan
4126 # define isnan(x) \
4127     (sizeof (x) == sizeof (long double) ? isnan_ld (x) \
4128      : sizeof (x) == sizeof (double) ? isnan_d (x) \
4129      : isnan_f (x))
4130 static inline int isnan_f  (float       x) @{ return x != x; @}
4131 static inline int isnan_d  (double      x) @{ return x != x; @}
4132 static inline int isnan_ld (long double x) @{ return x != x; @}
4133 #endif
4135 #ifndef isinf
4136 # define isinf(x) \
4137     (sizeof (x) == sizeof (long double) ? isinf_ld (x) \
4138      : sizeof (x) == sizeof (double) ? isinf_d (x) \
4139      : isinf_f (x))
4140 static inline int isinf_f  (float       x) @{ return isnan (x - x); @}
4141 static inline int isinf_d  (double      x) @{ return isnan (x - x); @}
4142 static inline int isinf_ld (long double x) @{ return isnan (x - x); @}
4143 #endif
4144 @end smallexample
4146 Use @code{AC_C_INLINE} (@pxref{C Compiler}) so that this code works on
4147 compilers that lack the @code{inline} keyword.  Some optimizing
4148 compilers mishandle these definitions, but systems with that bug
4149 typically have missing or broken @code{isnan} functions anyway, so it's
4150 probably not worth worrying about.
4152 @item @code{malloc}
4153 @c @fuindex malloc
4154 @prindex @code{malloc}
4155 The C standard says a call @code{malloc (0)} is implementation
4156 dependent.  It can return either @code{NULL} or a new non-null pointer.
4157 The latter is more common (e.g., the @acronym{GNU} C Library) but is by
4158 no means universal.  @code{AC_FUNC_MALLOC}
4159 can be used to insist on non-@code{NULL} (@pxref{Particular Functions}).
4161 @item @code{putenv}
4162 @c @fuindex putenv
4163 @prindex @code{putenv}
4164 Posix prefers @code{setenv} to @code{putenv}; among other things,
4165 @code{putenv} is not required of all Posix implementations, but
4166 @code{setenv} is.
4168 Posix specifies that @code{putenv} puts the given string directly in
4169 @code{environ}, but some systems make a copy of it instead (e.g.,
4170 glibc 2.0, or @acronym{BSD}).  And when a copy is made, @code{unsetenv} might
4171 not free it, causing a memory leak (e.g., Free@acronym{BSD} 4).
4173 On some systems @code{putenv ("FOO")} removes @samp{FOO} from the
4174 environment, but this is not standard usage and it dumps core
4175 on some systems (e.g., AIX).
4177 On MinGW, a call @code{putenv ("FOO=")} removes @samp{FOO} from the
4178 environment, rather than inserting it with an empty value.
4180 @item @code{realloc}
4181 @c @fuindex realloc
4182 @prindex @code{realloc}
4183 The C standard says a call @code{realloc (NULL, size)} is equivalent
4184 to @code{malloc (size)}, but some old systems don't support this (e.g.,
4185 NextStep).
4187 @item @code{signal} handler
4188 @c @fuindex signal
4189 @prindex @code{signal}
4190 Normally @code{signal} takes a handler function with a return type of
4191 @code{void}, but some old systems required @code{int} instead.  Any
4192 actual @code{int} value returned is not used; this is only a
4193 difference in the function prototype demanded.
4195 All systems we know of in current use return @code{void}.  The
4196 @code{int} was to support K&R C, where of course @code{void} is not
4197 available.  @code{AC_TYPE_SIGNAL} (@pxref{Particular Types}) can be
4198 used to establish the correct type in all cases.
4200 @item @code{snprintf}
4201 @c @fuindex snprintf
4202 @prindex @code{snprintf}
4203 @c @fuindex vsnprintf
4204 @prindex @code{vsnprintf}
4205 The C99 standard says that if the output array isn't big enough
4206 and if no other errors occur, @code{snprintf} and @code{vsnprintf}
4207 truncate the output and return the number of bytes that ought to have
4208 been produced.  Some older systems return the truncated length (e.g.,
4209 @acronym{GNU} C Library 2.0.x or @sc{irix} 6.5), some a negative value
4210 (e.g., earlier @acronym{GNU} C Library versions), and some the buffer
4211 length without truncation (e.g., 32-bit Solaris 7).  Also, some buggy
4212 older systems ignore the length and overrun the buffer (e.g., 64-bit
4213 Solaris 7).
4215 @item @code{sprintf}
4216 @c @fuindex sprintf
4217 @prindex @code{sprintf}
4218 @c @fuindex vsprintf
4219 @prindex @code{vsprintf}
4220 The C standard says @code{sprintf} and @code{vsprintf} return the
4221 number of bytes written.  On some ancient systems (SunOS 4 for
4222 instance) they return the buffer pointer instead, but these no
4223 longer need to be worried about.
4225 @item @code{sscanf}
4226 @c @fuindex sscanf
4227 @prindex @code{sscanf}
4228 On various old systems, e.g., @acronym{HP-UX} 9, @code{sscanf} requires that its
4229 input string be writable (though it doesn't actually change it).  This
4230 can be a problem when using @command{gcc} since it normally puts
4231 constant strings in read-only memory (@pxref{Incompatibilities,
4232 Incompatibilities of @acronym{GCC}, , gcc, Using and
4233 Porting the @acronym{GNU} Compiler Collection}).  Apparently in some cases even
4234 having format strings read-only can be a problem.
4236 @item @code{strerror_r}
4237 @c @fuindex strerror_r
4238 @prindex @code{strerror_r}
4239 Posix specifies that @code{strerror_r} returns an @code{int}, but many
4240 systems (e.g., @acronym{GNU} C Library version 2.2.4) provide a
4241 different version returning a @code{char *}.  @code{AC_FUNC_STRERROR_R}
4242 can detect which is in use (@pxref{Particular Functions}).
4244 @item @code{strnlen}
4245 @c @fuindex strnlen
4246 @prindex @code{strnlen}
4247 @acronym{AIX} 4.3 provides a broken version which produces the
4248 following results:
4250 @example
4251 strnlen ("foobar", 0) = 0
4252 strnlen ("foobar", 1) = 3
4253 strnlen ("foobar", 2) = 2
4254 strnlen ("foobar", 3) = 1
4255 strnlen ("foobar", 4) = 0
4256 strnlen ("foobar", 5) = 6
4257 strnlen ("foobar", 6) = 6
4258 strnlen ("foobar", 7) = 6
4259 strnlen ("foobar", 8) = 6
4260 strnlen ("foobar", 9) = 6
4261 @end example
4263 @item @code{sysconf}
4264 @c @fuindex sysconf
4265 @prindex @code{sysconf}
4266 @code{_SC_PAGESIZE} is standard, but some older systems (e.g., @acronym{HP-UX}
4267 9) have @code{_SC_PAGE_SIZE} instead.  This can be tested with
4268 @code{#ifdef}.
4270 @item @code{unlink}
4271 @c @fuindex unlink
4272 @prindex @code{unlink}
4273 The Posix spec says that @code{unlink} causes the given file to be
4274 removed only after there are no more open file handles for it.  Some
4275 non-Posix hosts have trouble with this requirement, though,
4276 and some @acronym{DOS} variants even corrupt the file system.
4278 @item @code{unsetenv}
4279 @c @fuindex unsetenv
4280 @prindex @code{unsetenv}
4281 On MinGW, @code{unsetenv} is not available, but a variable @samp{FOO}
4282 can be removed with a call @code{putenv ("FOO=")}, as described under
4283 @code{putenv} above.
4285 @item @code{va_copy}
4286 @c @fuindex va_copy
4287 @prindex @code{va_copy}
4288 The C99 standard provides @code{va_copy} for copying
4289 @code{va_list} variables.  It may be available in older environments
4290 too, though possibly as @code{__va_copy} (e.g., @command{gcc} in strict
4291 pre-C99 mode).  These can be tested with @code{#ifdef}.  A fallback to
4292 @code{memcpy (&dst, &src, sizeof (va_list))} gives maximum
4293 portability.
4295 @item @code{va_list}
4296 @c @fuindex va_list
4297 @prindex @code{va_list}
4298 @code{va_list} is not necessarily just a pointer.  It can be a
4299 @code{struct} (e.g., @command{gcc} on Alpha), which means @code{NULL} is
4300 not portable.  Or it can be an array (e.g., @command{gcc} in some
4301 PowerPC configurations), which means as a function parameter it can be
4302 effectively call-by-reference and library routines might modify the
4303 value back in the caller (e.g., @code{vsnprintf} in the @acronym{GNU} C Library
4304 2.1).
4306 @item Signed @code{>>}
4307 Normally the C @code{>>} right shift of a signed type replicates the
4308 high bit, giving a so-called ``arithmetic'' shift.  But care should be
4309 taken since Standard C doesn't require that behavior.  On those
4310 few processors without a native arithmetic shift (for instance Cray
4311 vector systems) zero bits may be shifted in, the same as a shift of an
4312 unsigned type.
4314 @item Integer @code{/}
4315 C divides signed integers by truncating their quotient toward zero,
4316 yielding the same result as Fortran.  However, before C99 the standard
4317 allowed C implementations to take the floor or ceiling of the quotient
4318 in some cases.  Hardly any implementations took advantage of this
4319 freedom, though, and it's probably not worth worrying about this issue
4320 nowadays.
4321 @end table
4324 @node Particular Functions
4325 @subsection Particular Function Checks
4326 @cindex Function, checking
4328 These macros check for particular C functions---whether they exist, and
4329 in some cases how they respond when given certain arguments.
4331 @defmac AC_FUNC_ALLOCA
4332 @acindex{FUNC_ALLOCA}
4333 @cvindex C_ALLOCA
4334 @cvindex HAVE_ALLOCA_H
4335 @ovindex ALLOCA
4336 @c @fuindex alloca
4337 @prindex @code{alloca}
4338 @hdrindex{alloca.h}
4339 Check how to get @code{alloca}.  Tries to get a builtin version by
4340 checking for @file{alloca.h} or the predefined C preprocessor macros
4341 @code{__GNUC__} and @code{_AIX}.  If this macro finds @file{alloca.h},
4342 it defines @code{HAVE_ALLOCA_H}.
4344 If those attempts fail, it looks for the function in the standard C
4345 library.  If any of those methods succeed, it defines
4346 @code{HAVE_ALLOCA}.  Otherwise, it sets the output variable
4347 @code{ALLOCA} to @samp{$@{LIBOBJDIR@}alloca.o} and defines
4348 @code{C_ALLOCA} (so programs can periodically call @samp{alloca (0)} to
4349 garbage collect).  This variable is separate from @code{LIBOBJS} so
4350 multiple programs can share the value of @code{ALLOCA} without needing
4351 to create an actual library, in case only some of them use the code in
4352 @code{LIBOBJS}.  The @samp{$@{LIBOBJDIR@}} prefix serves the same
4353 purpose as in @code{LIBOBJS} (@pxref{AC_LIBOBJ vs LIBOBJS}).
4355 This macro does not try to get @code{alloca} from the System V R3
4356 @file{libPW} or the System V R4 @file{libucb} because those libraries
4357 contain some incompatible functions that cause trouble.  Some versions
4358 do not even contain @code{alloca} or contain a buggy version.  If you
4359 still want to use their @code{alloca}, use @code{ar} to extract
4360 @file{alloca.o} from them instead of compiling @file{alloca.c}.
4362 Source files that use @code{alloca} should start with a piece of code
4363 like the following, to declare it properly.
4365 @example
4366 @group
4367 #ifdef HAVE_ALLOCA_H
4368 # include <alloca.h>
4369 #elif defined __GNUC__
4370 # define alloca __builtin_alloca
4371 #elif defined _AIX
4372 # define alloca __alloca
4373 #elif defined _MSC_VER
4374 # include <malloc.h>
4375 # define alloca _alloca
4376 #else
4377 # include <stddef.h>
4378 # ifdef  __cplusplus
4379 extern "C"
4380 # endif
4381 void *alloca (size_t);
4382 #endif
4383 @end group
4384 @end example
4385 @end defmac
4387 @defmac AC_FUNC_CHOWN
4388 @acindex{FUNC_CHOWN}
4389 @c @fuindex chown
4390 @prindex @code{chown}
4391 If the @code{chown} function is available and works (in particular, it
4392 should accept @option{-1} for @code{uid} and @code{gid}), define
4393 @code{HAVE_CHOWN}.
4394 @end defmac
4397 @defmac AC_FUNC_CLOSEDIR_VOID
4398 @acindex{FUNC_CLOSEDIR_VOID}
4399 @cvindex CLOSEDIR_VOID
4400 @c @fuindex closedir
4401 @prindex @code{closedir}
4402 If the @code{closedir} function does not return a meaningful value,
4403 define @code{CLOSEDIR_VOID}.  Otherwise, callers ought to check its
4404 return value for an error indicator.
4406 Currently this test is implemented by running a test program.  When
4407 cross compiling the pessimistic assumption that @code{closedir} does not
4408 return a meaningful value is made.
4410 This macro is obsolescent, as @code{closedir} returns a meaningful value
4411 on current systems.  New programs need not use this macro.
4412 @end defmac
4414 @defmac AC_FUNC_ERROR_AT_LINE
4415 @acindex{FUNC_ERROR_AT_LINE}
4416 @c @fuindex error_at_line
4417 @prindex @code{error_at_line}
4418 If the @code{error_at_line} function is not found, require an
4419 @code{AC_LIBOBJ} replacement of @samp{error}.
4420 @end defmac
4422 @defmac AC_FUNC_FNMATCH
4423 @acindex{FUNC_FNMATCH}
4424 @c @fuindex fnmatch
4425 @prindex @code{fnmatch}
4426 If the @code{fnmatch} function conforms to Posix, define
4427 @code{HAVE_FNMATCH}.  Detect common implementation bugs, for example,
4428 the bugs in Solaris 2.4.
4430 Unlike the other specific
4431 @code{AC_FUNC} macros, @code{AC_FUNC_FNMATCH} does not replace a
4432 broken/missing @code{fnmatch}.  This is for historical reasons.
4433 See @code{AC_REPLACE_FNMATCH} below.
4435 This macro is obsolescent.  New programs should use Gnulib's
4436 @code{fnmatch-posix} module.  @xref{Gnulib}.
4437 @end defmac
4439 @defmac AC_FUNC_FNMATCH_GNU
4440 @acindex{FUNC_FNMATCH_GNU}
4441 @c @fuindex fnmatch
4442 @prindex @code{fnmatch}
4443 Behave like @code{AC_REPLACE_FNMATCH} (@emph{replace}) but also test
4444 whether @code{fnmatch} supports @acronym{GNU} extensions.  Detect common
4445 implementation bugs, for example, the bugs in the @acronym{GNU} C
4446 Library 2.1.
4448 This macro is obsolescent.  New programs should use Gnulib's
4449 @code{fnmatch-gnu} module.  @xref{Gnulib}.
4450 @end defmac
4452 @defmac AC_FUNC_FORK
4453 @acindex{FUNC_FORK}
4454 @cvindex HAVE_VFORK_H
4455 @cvindex HAVE_WORKING_FORK
4456 @cvindex HAVE_WORKING_VFORK
4457 @cvindex vfork
4458 @c @fuindex fork
4459 @prindex @code{fork}
4460 @c @fuindex vfork
4461 @prindex @code{vfork}
4462 @hdrindex{vfork.h}
4463 This macro checks for the @code{fork} and @code{vfork} functions.  If a
4464 working @code{fork} is found, define @code{HAVE_WORKING_FORK}.  This macro
4465 checks whether @code{fork} is just a stub by trying to run it.
4467 If @file{vfork.h} is found, define @code{HAVE_VFORK_H}.  If a working
4468 @code{vfork} is found, define @code{HAVE_WORKING_VFORK}.  Otherwise,
4469 define @code{vfork} to be @code{fork} for backward compatibility with
4470 previous versions of @command{autoconf}.  This macro checks for several known
4471 errors in implementations of @code{vfork} and considers the system to not
4472 have a working @code{vfork} if it detects any of them.  It is not considered
4473 to be an implementation error if a child's invocation of @code{signal}
4474 modifies the parent's signal handler, since child processes rarely change
4475 their signal handlers.
4477 Since this macro defines @code{vfork} only for backward compatibility with
4478 previous versions of @command{autoconf} you're encouraged to define it
4479 yourself in new code:
4480 @example
4481 @group
4482 #ifndef HAVE_WORKING_VFORK
4483 # define vfork fork
4484 #endif
4485 @end group
4486 @end example
4487 @end defmac
4489 @defmac AC_FUNC_FSEEKO
4490 @acindex{FUNC_FSEEKO}
4491 @cvindex _LARGEFILE_SOURCE
4492 @c @fuindex fseeko
4493 @prindex @code{fseeko}
4494 If the @code{fseeko} function is available, define @code{HAVE_FSEEKO}.
4495 Define @code{_LARGEFILE_SOURCE} if necessary to make the prototype
4496 visible on some systems (e.g., glibc 2.2).  Otherwise linkage problems
4497 may occur when compiling with @code{AC_SYS_LARGEFILE} on
4498 largefile-sensitive systems where @code{off_t} does not default to a
4499 64bit entity.
4500 @end defmac
4502 @defmac AC_FUNC_GETGROUPS
4503 @acindex{FUNC_GETGROUPS}
4504 @ovindex GETGROUPS_LIBS
4505 @c @fuindex getgroups
4506 @prindex @code{getgroups}
4507 If the @code{getgroups} function is available and works (unlike on
4508 Ultrix 4.3, where @samp{getgroups (0, 0)} always fails), define
4509 @code{HAVE_GETGROUPS}.  Set @code{GETGROUPS_LIBS} to any libraries
4510 needed to get that function.  This macro runs @code{AC_TYPE_GETGROUPS}.
4511 @end defmac
4513 @defmac AC_FUNC_GETLOADAVG
4514 @acindex{FUNC_GETLOADAVG}
4515 @cvindex SVR4
4516 @cvindex DGUX
4517 @cvindex UMAX
4518 @cvindex UMAX4_3
4519 @cvindex HAVE_NLIST_H
4520 @cvindex NLIST_NAME_UNION
4521 @cvindex GETLOADAVG_PRIVILEGED
4522 @cvindex NEED_SETGID
4523 @cvindex C_GETLOADAVG
4524 @ovindex LIBOBJS
4525 @ovindex NEED_SETGID
4526 @ovindex KMEM_GROUP
4527 @ovindex GETLOADAVG_LIBS
4528 @c @fuindex getloadavg
4529 @prindex @code{getloadavg}
4530 Check how to get the system load averages.  To perform its tests
4531 properly, this macro needs the file @file{getloadavg.c}; therefore, be
4532 sure to set the @code{AC_LIBOBJ} replacement directory properly (see
4533 @ref{Generic Functions}, @code{AC_CONFIG_LIBOBJ_DIR}).
4535 If the system has the @code{getloadavg} function, define
4536 @code{HAVE_GETLOADAVG}, and set @code{GETLOADAVG_LIBS} to any libraries
4537 necessary to get that function.  Also add @code{GETLOADAVG_LIBS} to
4538 @code{LIBS}.  Otherwise, require an @code{AC_LIBOBJ} replacement for
4539 @samp{getloadavg} with source code in @file{@var{dir}/getloadavg.c}, and
4540 possibly define several other C preprocessor macros and output
4541 variables:
4543 @enumerate
4544 @item
4545 Define @code{C_GETLOADAVG}.
4547 @item
4548 Define @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if on
4549 those systems.
4551 @item
4552 @hdrindex{nlist.h}
4553 If @file{nlist.h} is found, define @code{HAVE_NLIST_H}.
4555 @item
4556 If @samp{struct nlist} has an @samp{n_un.n_name} member, define
4557 @code{HAVE_STRUCT_NLIST_N_UN_N_NAME}.  The obsolete symbol
4558 @code{NLIST_NAME_UNION} is still defined, but do not depend upon it.
4560 @item
4561 Programs may need to be installed set-group-ID (or set-user-ID) for
4562 @code{getloadavg} to work.  In this case, define
4563 @code{GETLOADAVG_PRIVILEGED}, set the output variable @code{NEED_SETGID}
4564 to @samp{true} (and otherwise to @samp{false}), and set
4565 @code{KMEM_GROUP} to the name of the group that should own the installed
4566 program.
4567 @end enumerate
4569 The @code{AC_FUNC_GETLOADAVG} macro is obsolescent.  New programs should
4570 use Gnulib's @code{getloadavg} module.  @xref{Gnulib}.
4571 @end defmac
4573 @defmac AC_FUNC_GETMNTENT
4574 @acindex{FUNC_GETMNTENT}
4575 @cvindex HAVE_GETMNTENT
4576 @c @fuindex getmntent
4577 @prindex @code{getmntent}
4578 Check for @code{getmntent} in the standard C library, and then in the
4579 @file{sun}, @file{seq}, and @file{gen} libraries, for @sc{unicos},
4580 @sc{irix} 4, @sc{ptx}, and UnixWare, respectively.  Then, if
4581 @code{getmntent} is available, define @code{HAVE_GETMNTENT}.
4582 @end defmac
4584 @defmac AC_FUNC_GETPGRP
4585 @acindex{FUNC_GETPGRP}
4586 @cvindex GETPGRP_VOID
4587 @c @fuindex getpgid
4588 @c @fuindex getpgrp
4589 @prindex @code{getpgid}
4590 @prindex @code{getpgrp}
4591 Define @code{GETPGRP_VOID} if it is an error to pass 0 to
4592 @code{getpgrp}; this is the Posix behavior.  On older @acronym{BSD}
4593 systems, you must pass 0 to @code{getpgrp}, as it takes an argument and
4594 behaves like Posix's @code{getpgid}.
4596 @example
4597 #ifdef GETPGRP_VOID
4598   pid = getpgrp ();
4599 #else
4600   pid = getpgrp (0);
4601 #endif
4602 @end example
4604 This macro does not check whether
4605 @code{getpgrp} exists at all; if you need to work in that situation,
4606 first call @code{AC_CHECK_FUNC} for @code{getpgrp}.
4608 This macro is obsolescent, as current systems have a @code{getpgrp}
4609 whose signature conforms to Posix.  New programs need not use this macro.
4610 @end defmac
4612 @defmac AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK
4613 @acindex{FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK}
4614 @cvindex LSTAT_FOLLOWS_SLASHED_SYMLINK
4615 @c @fuindex lstat
4616 @prindex @code{lstat}
4617 If @file{link} is a symbolic link, then @code{lstat} should treat
4618 @file{link/} the same as @file{link/.}.  However, many older
4619 @code{lstat} implementations incorrectly ignore trailing slashes.
4621 It is safe to assume that if @code{lstat} incorrectly ignores
4622 trailing slashes, then other symbolic-link-aware functions like
4623 @code{unlink} also incorrectly ignore trailing slashes.
4625 If @code{lstat} behaves properly, define
4626 @code{LSTAT_FOLLOWS_SLASHED_SYMLINK}, otherwise require an
4627 @code{AC_LIBOBJ} replacement of @code{lstat}.
4628 @end defmac
4630 @defmac AC_FUNC_MALLOC
4631 @acindex{FUNC_MALLOC}
4632 @cvindex HAVE_MALLOC
4633 @cvindex malloc
4634 @c @fuindex malloc
4635 @prindex @code{malloc}
4636 If the @code{malloc} function is compatible with the @acronym{GNU} C
4637 library @code{malloc} (i.e., @samp{malloc (0)} returns a valid
4638 pointer), define @code{HAVE_MALLOC} to 1.  Otherwise define
4639 @code{HAVE_MALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
4640 @samp{malloc}, and define @code{malloc} to @code{rpl_malloc} so that the
4641 native @code{malloc} is not used in the main project.
4643 Typically, the replacement file @file{malloc.c} should look like (note
4644 the @samp{#undef malloc}):
4646 @verbatim
4647 #ifdef HAVE_CONFIG_H
4648 # include <config.h>
4649 #endif
4650 #undef malloc
4652 #include <sys/types.h>
4654 void *malloc ();
4656 /* Allocate an N-byte block of memory from the heap.
4657    If N is zero, allocate a 1-byte block.  */
4659 void *
4660 rpl_malloc (size_t n)
4662   if (n == 0)
4663     n = 1;
4664   return malloc (n);
4666 @end verbatim
4667 @end defmac
4669 @defmac AC_FUNC_MEMCMP
4670 @acindex{FUNC_MEMCMP}
4671 @ovindex LIBOBJS
4672 @c @fuindex memcmp
4673 @prindex @code{memcmp}
4674 If the @code{memcmp} function is not available, or does not work on
4675 8-bit data (like the one on SunOS 4.1.3), or fails when comparing 16
4676 bytes or more and with at least one buffer not starting on a 4-byte
4677 boundary (such as the one on NeXT x86 OpenStep), require an
4678 @code{AC_LIBOBJ} replacement for @samp{memcmp}.
4680 This macro is obsolescent, as current systems have a working
4681 @code{memcmp}.  New programs need not use this macro.
4682 @end defmac
4684 @defmac AC_FUNC_MBRTOWC
4685 @acindex{FUNC_MBRTOWC}
4686 @cvindex HAVE_MBRTOWC
4687 @c @fuindex mbrtowc
4688 @prindex @code{mbrtowc}
4689 Define @code{HAVE_MBRTOWC} to 1 if the function @code{mbrtowc} and the
4690 type @code{mbstate_t} are properly declared.
4691 @end defmac
4693 @defmac AC_FUNC_MKTIME
4694 @acindex{FUNC_MKTIME}
4695 @ovindex LIBOBJS
4696 @c @fuindex mktime
4697 @prindex @code{mktime}
4698 If the @code{mktime} function is not available, or does not work
4699 correctly, require an @code{AC_LIBOBJ} replacement for @samp{mktime}.
4700 For the purposes of this test, @code{mktime} should conform to the
4701 Posix standard and should be the inverse of
4702 @code{localtime}.
4703 @end defmac
4705 @defmac AC_FUNC_MMAP
4706 @acindex{FUNC_MMAP}
4707 @cvindex HAVE_MMAP
4708 @c @fuindex mmap
4709 @prindex @code{mmap}
4710 If the @code{mmap} function exists and works correctly, define
4711 @code{HAVE_MMAP}.  This checks only private fixed mapping of already-mapped
4712 memory.
4713 @end defmac
4715 @defmac AC_FUNC_OBSTACK
4716 @acindex{FUNC_OBSTACK}
4717 @cvindex HAVE_OBSTACK
4718 @cindex obstack
4719 If the obstacks are found, define @code{HAVE_OBSTACK}, else require an
4720 @code{AC_LIBOBJ} replacement for @samp{obstack}.
4721 @end defmac
4723 @defmac AC_FUNC_REALLOC
4724 @acindex{FUNC_REALLOC}
4725 @cvindex HAVE_REALLOC
4726 @cvindex realloc
4727 @c @fuindex realloc
4728 @prindex @code{realloc}
4729 If the @code{realloc} function is compatible with the @acronym{GNU} C
4730 library @code{realloc} (i.e., @samp{realloc (NULL, 0)} returns a
4731 valid pointer), define @code{HAVE_REALLOC} to 1.  Otherwise define
4732 @code{HAVE_REALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
4733 @samp{realloc}, and define @code{realloc} to @code{rpl_realloc} so that
4734 the native @code{realloc} is not used in the main project.  See
4735 @code{AC_FUNC_MALLOC} for details.
4736 @end defmac
4738 @defmac AC_FUNC_SELECT_ARGTYPES
4739 @acindex{FUNC_SELECT_ARGTYPES}
4740 @cvindex SELECT_TYPE_ARG1
4741 @cvindex SELECT_TYPE_ARG234
4742 @cvindex SELECT_TYPE_ARG5
4743 @c @fuindex select
4744 @prindex @code{select}
4745 Determines the correct type to be passed for each of the
4746 @code{select} function's arguments, and defines those types
4747 in @code{SELECT_TYPE_ARG1}, @code{SELECT_TYPE_ARG234}, and
4748 @code{SELECT_TYPE_ARG5} respectively.  @code{SELECT_TYPE_ARG1} defaults
4749 to @samp{int}, @code{SELECT_TYPE_ARG234} defaults to @samp{int *},
4750 and @code{SELECT_TYPE_ARG5} defaults to @samp{struct timeval *}.
4752 This macro is obsolescent, as current systems have a @code{select} whose
4753 signature conforms to Posix.  New programs need not use this macro.
4754 @end defmac
4756 @defmac AC_FUNC_SETPGRP
4757 @acindex{FUNC_SETPGRP}
4758 @cvindex SETPGRP_VOID
4759 @c @fuindex setpgrp
4760 @prindex @code{setpgrp}
4761 If @code{setpgrp} takes no argument (the Posix version), define
4762 @code{SETPGRP_VOID}.  Otherwise, it is the @acronym{BSD} version, which takes
4763 two process IDs as arguments.  This macro does not check whether
4764 @code{setpgrp} exists at all; if you need to work in that situation,
4765 first call @code{AC_CHECK_FUNC} for @code{setpgrp}.
4767 This macro is obsolescent, as current systems have a @code{setpgrp}
4768 whose signature conforms to Posix.  New programs need not use this macro.
4769 @end defmac
4771 @defmac AC_FUNC_STAT
4772 @defmacx AC_FUNC_LSTAT
4773 @acindex{FUNC_STAT}
4774 @acindex{FUNC_LSTAT}
4775 @cvindex HAVE_STAT_EMPTY_STRING_BUG
4776 @cvindex HAVE_LSTAT_EMPTY_STRING_BUG
4777 @c @fuindex stat
4778 @prindex @code{stat}
4779 @c @fuindex lstat
4780 @prindex @code{lstat}
4781 Determine whether @code{stat} or @code{lstat} have the bug that it
4782 succeeds when given the zero-length file name as argument.  The @code{stat}
4783 and @code{lstat} from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do
4784 this.
4786 If it does, then define @code{HAVE_STAT_EMPTY_STRING_BUG} (or
4787 @code{HAVE_LSTAT_EMPTY_STRING_BUG}) and ask for an @code{AC_LIBOBJ}
4788 replacement of it.
4790 These macros are obsolescent, as no current systems have the bug.
4791 New programs need not use these macros.
4792 @end defmac
4794 @defmac AC_FUNC_STRCOLL
4795 @acindex{FUNC_STRCOLL}
4796 @cvindex HAVE_STRCOLL
4797 @c @fuindex strcoll
4798 @prindex @code{strcoll}
4799 If the @code{strcoll} function exists and works correctly, define
4800 @code{HAVE_STRCOLL}.  This does a bit more than
4801 @samp{AC_CHECK_FUNCS(strcoll)}, because some systems have incorrect
4802 definitions of @code{strcoll} that should not be used.
4803 @end defmac
4805 @defmac AC_FUNC_STRERROR_R
4806 @acindex{FUNC_STRERROR_R}
4807 @cvindex HAVE_STRERROR_R
4808 @cvindex HAVE_DECL_STRERROR_R
4809 @cvindex STRERROR_R_CHAR_P
4810 @c @fuindex strerror_r
4811 @prindex @code{strerror_r}
4812 If @code{strerror_r} is available, define @code{HAVE_STRERROR_R}, and if
4813 it is declared, define @code{HAVE_DECL_STRERROR_R}.  If it returns a
4814 @code{char *} message, define @code{STRERROR_R_CHAR_P}; otherwise it
4815 returns an @code{int} error number.  The Thread-Safe Functions option of
4816 Posix requires @code{strerror_r} to return @code{int}, but
4817 many systems (including, for example, version 2.2.4 of the @acronym{GNU} C
4818 Library) return a @code{char *} value that is not necessarily equal to
4819 the buffer argument.
4820 @end defmac
4822 @defmac AC_FUNC_STRFTIME
4823 @acindex{FUNC_STRFTIME}
4824 @cvindex HAVE_STRFTIME
4825 @c @fuindex strftime
4826 @prindex @code{strftime}
4827 Check for @code{strftime} in the @file{intl} library, for SCO Unix.
4828 Then, if @code{strftime} is available, define @code{HAVE_STRFTIME}.
4830 This macro is obsolescent, as no current systems require the @file{intl}
4831 library for @code{strftime}.  New programs need not use this macro.
4832 @end defmac
4834 @defmac AC_FUNC_STRTOD
4835 @acindex{FUNC_STRTOD}
4836 @ovindex POW_LIB
4837 @c @fuindex strtod
4838 @prindex @code{strtod}
4839 If the @code{strtod} function does not exist or doesn't work correctly,
4840 ask for an @code{AC_LIBOBJ} replacement of @samp{strtod}.  In this case,
4841 because @file{strtod.c} is likely to need @samp{pow}, set the output
4842 variable @code{POW_LIB} to the extra library needed.
4843 @end defmac
4845 @defmac AC_FUNC_STRTOLD
4846 @acindex{FUNC_STRTOLD}
4847 @prindex @code{strtold}
4848 If the @code{strtold} function exists and conforms to C99, define
4849 @code{HAVE_STRTOLD}.
4850 @end defmac
4852 @defmac AC_FUNC_STRNLEN
4853 @acindex{FUNC_STRNLEN}
4854 @cvindex HAVE_STRNLEN
4855 @c @fuindex strnlen
4856 @prindex @code{strnlen}
4857 If the @code{strnlen} function is not available, or is buggy (like the one
4858 from @acronym{AIX} 4.3), require an @code{AC_LIBOBJ} replacement for it.
4859 @end defmac
4861 @defmac AC_FUNC_UTIME_NULL
4862 @acindex{FUNC_UTIME_NULL}
4863 @cvindex HAVE_UTIME_NULL
4864 @c @fuindex utime
4865 @prindex @code{utime}
4866 If @samp{utime (@var{file}, NULL)} sets @var{file}'s timestamp to
4867 the present, define @code{HAVE_UTIME_NULL}.
4869 This macro is obsolescent, as all current systems have a @code{utime}
4870 that behaves this way.  New programs need not use this macro.
4871 @end defmac
4873 @defmac AC_FUNC_VPRINTF
4874 @acindex{FUNC_VPRINTF}
4875 @cvindex HAVE_VPRINTF
4876 @cvindex HAVE_DOPRNT
4877 @c @fuindex vprintf
4878 @prindex @code{vprintf}
4879 If @code{vprintf} is found, define @code{HAVE_VPRINTF}.  Otherwise, if
4880 @code{_doprnt} is found, define @code{HAVE_DOPRNT}.  (If @code{vprintf}
4881 is available, you may assume that @code{vfprintf} and @code{vsprintf}
4882 are also available.)
4884 This macro is obsolescent, as all current systems have @code{vprintf}.
4885 New programs need not use this macro.
4886 @end defmac
4888 @defmac AC_REPLACE_FNMATCH
4889 @acindex{REPLACE_FNMATCH}
4890 @c @fuindex fnmatch
4891 @prindex @code{fnmatch}
4892 @hdrindex{fnmatch.h}
4893 If the @code{fnmatch} function does not conform to Posix (see
4894 @code{AC_FUNC_FNMATCH}), ask for its @code{AC_LIBOBJ} replacement.
4896 The files @file{fnmatch.c}, @file{fnmatch_loop.c}, and @file{fnmatch_.h}
4897 in the @code{AC_LIBOBJ} replacement directory are assumed to contain a
4898 copy of the source code of @acronym{GNU} @code{fnmatch}.  If necessary,
4899 this source code is compiled as an @code{AC_LIBOBJ} replacement, and the
4900 @file{fnmatch_.h} file is linked to @file{fnmatch.h} so that it can be
4901 included in place of the system @code{<fnmatch.h>}.
4903 This macro is obsolescent, as it assumes the use of particular source
4904 files.  New programs should use Gnulib's @code{fnmatch-posix} module,
4905 which provides this macro along with the source files.  @xref{Gnulib}.
4906 @end defmac
4910 @node Generic Functions
4911 @subsection Generic Function Checks
4913 These macros are used to find functions not covered by the ``particular''
4914 test macros.  If the functions might be in libraries other than the
4915 default C library, first call @code{AC_CHECK_LIB} for those libraries.
4916 If you need to check the behavior of a function as well as find out
4917 whether it is present, you have to write your own test for
4918 it (@pxref{Writing Tests}).
4920 @defmac AC_CHECK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found})
4921 @acindex{CHECK_FUNC}
4922 If C function @var{function} is available, run shell commands
4923 @var{action-if-found}, otherwise @var{action-if-not-found}.  If you just
4924 want to define a symbol if the function is available, consider using
4925 @code{AC_CHECK_FUNCS} instead.  This macro checks for functions with C
4926 linkage even when @code{AC_LANG(C++)} has been called, since C is more
4927 standardized than C++.  (@pxref{Language Choice}, for more information
4928 about selecting the language for checks.)
4929 @end defmac
4931 @defmac AC_CHECK_FUNCS (@var{function}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found})
4932 @acindex{CHECK_FUNCS}
4933 @cvindex HAVE_@var{function}
4934 For each @var{function} enumerated in the blank-or-newline-separated argument
4935 list, define @code{HAVE_@var{function}} (in all capitals) if it is available.
4936 If @var{action-if-found} is given, it is additional shell code to
4937 execute when one of the functions is found.  You can give it a value of
4938 @samp{break} to break out of the loop on the first match.  If
4939 @var{action-if-not-found} is given, it is executed when one of the
4940 functions is not found.
4941 @end defmac
4943 @defmac AC_CHECK_FUNCS_ONCE (@var{function}@dots{})
4944 @acindex{CHECK_FUNCS_ONCE}
4945 @cvindex HAVE_@var{function}
4946 For each @var{function} enumerated in the blank-or-newline-separated argument
4947 list, define @code{HAVE_@var{function}} (in all capitals) if it is available.
4948 This is a once-only variant of @code{AC_CHECK_FUNCS}.  It generates the
4949 checking code at most once, so that @command{configure} is smaller and
4950 faster; but the checks cannot be conditionalized and are always done once,
4951 early during the @command{configure} run.
4952 @end defmac
4954 @sp 1
4956 Autoconf follows a philosophy that was formed over the years by those
4957 who have struggled for portability: isolate the portability issues in
4958 specific files, and then program as if you were in a Posix
4959 environment.  Some functions may be missing or unfixable, and your
4960 package must be ready to replace them.
4962 Suitable replacements for many such problem functions are available from
4963 Gnulib (@pxref{Gnulib}).
4965 @defmac AC_LIBOBJ (@var{function})
4966 @acindex{LIBOBJ}
4967 @ovindex LIBOBJS
4968 Specify that @samp{@var{function}.c} must be included in the executables
4969 to replace a missing or broken implementation of @var{function}.
4971 Technically, it adds @samp{@var{function}.$ac_objext} to the output
4972 variable @code{LIBOBJS} if it is not already in, and calls
4973 @code{AC_LIBSOURCE} for @samp{@var{function}.c}.  You should not
4974 directly change @code{LIBOBJS}, since this is not traceable.
4975 @end defmac
4977 @defmac AC_LIBSOURCE (@var{file})
4978 @acindex{LIBSOURCE}
4979 Specify that @var{file} might be needed to compile the project.  If you
4980 need to know what files might be needed by a @file{configure.ac}, you
4981 should trace @code{AC_LIBSOURCE}.  @var{file} must be a literal.
4983 This macro is called automatically from @code{AC_LIBOBJ}, but you must
4984 call it explicitly if you pass a shell variable to @code{AC_LIBOBJ}.  In
4985 that case, since shell variables cannot be traced statically, you must
4986 pass to @code{AC_LIBSOURCE} any possible files that the shell variable
4987 might cause @code{AC_LIBOBJ} to need.  For example, if you want to pass
4988 a variable @code{$foo_or_bar} to @code{AC_LIBOBJ} that holds either
4989 @code{"foo"} or @code{"bar"}, you should do:
4991 @example
4992 AC_LIBSOURCE([foo.c])
4993 AC_LIBSOURCE([bar.c])
4994 AC_LIBOBJ([$foo_or_bar])
4995 @end example
4997 @noindent
4998 There is usually a way to avoid this, however, and you are encouraged to
4999 simply call @code{AC_LIBOBJ} with literal arguments.
5001 Note that this macro replaces the obsolete @code{AC_LIBOBJ_DECL}, with
5002 slightly different semantics: the old macro took the function name,
5003 e.g., @code{foo}, as its argument rather than the file name.
5004 @end defmac
5006 @defmac AC_LIBSOURCES (@var{files})
5007 @acindex{LIBSOURCES}
5008 Like @code{AC_LIBSOURCE}, but accepts one or more @var{files} in a
5009 comma-separated M4 list.  Thus, the above example might be rewritten:
5011 @example
5012 AC_LIBSOURCES([foo.c, bar.c])
5013 AC_LIBOBJ([$foo_or_bar])
5014 @end example
5015 @end defmac
5017 @defmac AC_CONFIG_LIBOBJ_DIR (@var{directory})
5018 @acindex{CONFIG_LIBOBJ_DIR}
5019 Specify that @code{AC_LIBOBJ} replacement files are to be found in
5020 @var{directory}, a name relative to the top level of the
5021 source tree.  The replacement directory defaults to @file{.}, the top
5022 level directory, and the most typical value is @file{lib}, corresponding
5023 to @samp{AC_CONFIG_LIBOBJ_DIR([lib])}.
5025 @command{configure} might need to know the replacement directory for the
5026 following reasons: (i) some checks use the replacement files, (ii) some
5027 macros bypass broken system headers by installing links to the
5028 replacement headers (iii) when used in conjunction with Automake,
5029 within each makefile, @var{directory} is used as a relative path
5030 from @code{$(top_srcdir)} to each object named in @code{LIBOBJS} and
5031 @code{LTLIBOBJS}, etc.
5032 @end defmac
5034 @sp 1
5036 It is common to merely check for the existence of a function, and ask
5037 for its @code{AC_LIBOBJ} replacement if missing.  The following macro is
5038 a convenient shorthand.
5040 @defmac AC_REPLACE_FUNCS (@var{function}@dots{})
5041 @acindex{REPLACE_FUNCS}
5042 @ovindex LIBOBJS
5043 Like @code{AC_CHECK_FUNCS}, but uses @samp{AC_LIBOBJ(@var{function})} as
5044 @var{action-if-not-found}.  You can declare your replacement function by
5045 enclosing the prototype in @samp{#ifndef HAVE_@var{function}}.  If the
5046 system has the function, it probably declares it in a header file you
5047 should be including, so you shouldn't redeclare it lest your declaration
5048 conflict.
5049 @end defmac
5051 @node Header Files
5052 @section Header Files
5053 @cindex Header, checking
5055 The following macros check for the presence of certain C header files.
5056 If there is no macro specifically defined to check for a header file you need,
5057 and you don't need to check for any special properties of
5058 it, then you can use one of the general header-file check macros.
5060 @menu
5061 * Header Portability::          Collected knowledge on common headers
5062 * Particular Headers::          Special handling to find certain headers
5063 * Generic Headers::             How to find other headers
5064 @end menu
5066 @node Header Portability
5067 @subsection Portability of Headers
5068 @cindex Portability of headers
5069 @cindex Header portability
5071 This section tries to collect knowledge about common headers, and the
5072 problems they cause.  By definition, this list always requires
5073 additions.  Please help us keeping it as complete as possible.
5075 @table @asis
5077 @item @file{limits.h}
5078 C99 says that @file{limits.h} defines @code{LLONG_MIN},
5079 @code{LLONG_MAX}, and @code{ULLONG_MAX}, but many almost-C99
5080 environments (e.g., default @acronym{GCC} 4.0.2 + glibc 2.4) do not
5081 define them.
5083 @item @file{inttypes.h} vs.@: @file{stdint.h}
5084 @hdrindex{inttypes.h}
5085 @hdrindex{stdint.h}
5086 The C99 standard says that @file{inttypes.h} includes
5087 @file{stdint.h}, so there's no need to include @file{stdint.h}
5088 separately in a standard environment.  Some implementations have
5089 @file{inttypes.h} but not @file{stdint.h} (e.g., Solaris 7), but we don't
5090 know of any implementation that has @file{stdint.h} but not
5091 @file{inttypes.h}.
5093 @item @file{linux/irda.h}
5094 @hdrindex{linux/irda.h}
5095 It requires @file{linux/types.h} and @file{sys/socket.h}.
5097 @item @file{linux/random.h}
5098 @hdrindex{linux/random.h}
5099 It requires @file{linux/types.h}.
5101 @item @file{net/if.h}
5102 @hdrindex{net/if.h}
5103 On Darwin, this file requires that @file{sys/socket.h} be included
5104 beforehand.  One should run:
5106 @example
5107 AC_CHECK_HEADERS([sys/socket.h])
5108 AC_CHECK_HEADERS([net/if.h], [], [],
5109 [#include <stdio.h>
5110 #ifdef STDC_HEADERS
5111 # include <stdlib.h>
5112 # include <stddef.h>
5113 #else
5114 # ifdef HAVE_STDLIB_H
5115 #  include <stdlib.h>
5116 # endif
5117 #endif
5118 #ifdef HAVE_SYS_SOCKET_H
5119 # include <sys/socket.h>
5120 #endif
5122 @end example
5124 @item @file{netinet/if_ether.h}
5125 @hdrindex{netinet/if_ether.h}
5126 On Darwin, this file requires that @file{stdio.h} and
5127 @file{sys/socket.h} be included beforehand.  One should run:
5129 @example
5130 AC_CHECK_HEADERS([sys/socket.h])
5131 AC_CHECK_HEADERS([netinet/if_ether.h], [], [],
5132 [#include <stdio.h>
5133 #ifdef STDC_HEADERS
5134 # include <stdlib.h>
5135 # include <stddef.h>
5136 #else
5137 # ifdef HAVE_STDLIB_H
5138 #  include <stdlib.h>
5139 # endif
5140 #endif
5141 #ifdef HAVE_SYS_SOCKET_H
5142 # include <sys/socket.h>
5143 #endif
5145 @end example
5147 @item @file{stdint.h}
5148 See above, item @file{inttypes.h} vs.@: @file{stdint.h}.
5150 @item @file{stdlib.h}
5151 @hdrindex{stdlib.h}
5152 On many systems (e.g., Darwin), @file{stdio.h} is a prerequisite.
5154 @item @file{sys/mount.h}
5155 @hdrindex{sys/mount.h}
5156 On Free@acronym{BSD} 4.8 on ia32 and using gcc version 2.95.4,
5157 @file{sys/params.h} is a prerequisite.
5159 @item @file{sys/ptem.h}
5160 @hdrindex{sys/ptem.h}
5161 On Solaris 8, @file{sys/stream.h} is a prerequisite.
5163 @item @file{sys/socket.h}
5164 @hdrindex{sys/socket.h}
5165 On Darwin, @file{stdlib.h} is a prerequisite.
5167 @item @file{sys/ucred.h}
5168 @hdrindex{sys/ucred.h}
5169 On Tru64 5.1, @file{sys/types.h} is a prerequisite.
5171 @item @file{X11/extensions/scrnsaver.h}
5172 @hdrindex{X11/extensions/scrnsaver.h}
5173 Using XFree86, this header requires @file{X11/Xlib.h}, which is probably
5174 so required that you might not even consider looking for it.
5176 @example
5177 AC_CHECK_HEADERS([X11/extensions/scrnsaver.h], [], [],
5178 [[#include <X11/Xlib.h>
5180 @end example
5181 @end table
5184 @node Particular Headers
5185 @subsection Particular Header Checks
5187 These macros check for particular system header files---whether they
5188 exist, and in some cases whether they declare certain symbols.
5190 @defmac AC_HEADER_ASSERT
5191 @acindex{HEADER_ASSERT}
5192 @cvindex NDEBUG
5193 @hdrindex{assert.h}
5194 Check whether to enable assertions in the style of @file{assert.h}.
5195 Assertions are enabled by default, but the user can override this by
5196 invoking @command{configure} with the @option{--disable-assert} option.
5197 @end defmac
5199 @defmac AC_HEADER_DIRENT
5200 @acindex{HEADER_DIRENT}
5201 @cvindex HAVE_DIRENT_H
5202 @cvindex HAVE_NDIR_H
5203 @cvindex HAVE_SYS_DIR_H
5204 @cvindex HAVE_SYS_NDIR_H
5205 @hdrindex{dirent.h}
5206 @hdrindex{sys/ndir.h}
5207 @hdrindex{sys/dir.h}
5208 @hdrindex{ndir.h}
5209 Check for the following header files.  For the first one that is
5210 found and defines @samp{DIR}, define the listed C preprocessor macro:
5212 @multitable {@file{sys/ndir.h}} {@code{HAVE_SYS_NDIR_H}}
5213 @item @file{dirent.h}   @tab @code{HAVE_DIRENT_H}
5214 @item @file{sys/ndir.h} @tab @code{HAVE_SYS_NDIR_H}
5215 @item @file{sys/dir.h}  @tab @code{HAVE_SYS_DIR_H}
5216 @item @file{ndir.h}     @tab @code{HAVE_NDIR_H}
5217 @end multitable
5219 The directory-library declarations in your source code should look
5220 something like the following:
5222 @example
5223 @group
5224 #include <sys/types.h>
5225 #ifdef HAVE_DIRENT_H
5226 # include <dirent.h>
5227 # define NAMLEN(dirent) strlen ((dirent)->d_name)
5228 #else
5229 # define dirent direct
5230 # define NAMLEN(dirent) ((dirent)->d_namlen)
5231 # ifdef HAVE_SYS_NDIR_H
5232 #  include <sys/ndir.h>
5233 # endif
5234 # ifdef HAVE_SYS_DIR_H
5235 #  include <sys/dir.h>
5236 # endif
5237 # ifdef HAVE_NDIR_H
5238 #  include <ndir.h>
5239 # endif
5240 #endif
5241 @end group
5242 @end example
5244 Using the above declarations, the program would declare variables to be
5245 of type @code{struct dirent}, not @code{struct direct}, and would access
5246 the length of a directory entry name by passing a pointer to a
5247 @code{struct dirent} to the @code{NAMLEN} macro.
5249 This macro also checks for the SCO Xenix @file{dir} and @file{x} libraries.
5251 This macro is obsolescent, as all current systems with directory
5252 libraries have @code{<dirent.h>}.  New programs need not use this macro.
5254 Also see @code{AC_STRUCT_DIRENT_D_INO} and
5255 @code{AC_STRUCT_DIRENT_D_TYPE} (@pxref{Particular Structures}).
5256 @end defmac
5258 @defmac AC_HEADER_MAJOR
5259 @acindex{HEADER_MAJOR}
5260 @cvindex MAJOR_IN_MKDEV
5261 @cvindex MAJOR_IN_SYSMACROS
5262 @hdrindex{sys/mkdev.h}
5263 @hdrindex{sys/sysmacros.h}
5264 If @file{sys/types.h} does not define @code{major}, @code{minor}, and
5265 @code{makedev}, but @file{sys/mkdev.h} does, define
5266 @code{MAJOR_IN_MKDEV}; otherwise, if @file{sys/sysmacros.h} does, define
5267 @code{MAJOR_IN_SYSMACROS}.
5268 @end defmac
5270 @defmac AC_HEADER_RESOLV
5271 @acindex{HEADER_RESOLV}
5272 @cvindex HAVE_RESOLV_H
5273 @hdrindex{resolv.h}
5274 Checks for header @file{resolv.h}, checking for prerequisites first.
5275 To properly use @file{resolv.h}, your code should contain something like
5276 the following:
5278 @verbatim
5279 #ifdef HAVE_SYS_TYPES_H
5280 #  include <sys/types.h>
5281 #endif
5282 #ifdef HAVE_NETINET_IN_H
5283 #  include <netinet/in.h>   /* inet_ functions / structs */
5284 #endif
5285 #ifdef HAVE_ARPA_NAMESER_H
5286 #  include <arpa/nameser.h> /* DNS HEADER struct */
5287 #endif
5288 #ifdef HAVE_NETDB_H
5289 #  include <netdb.h>
5290 #endif
5291 #include <resolv.h>
5292 @end verbatim
5293 @end defmac
5295 @defmac AC_HEADER_STAT
5296 @acindex{HEADER_STAT}
5297 @cvindex STAT_MACROS_BROKEN
5298 @hdrindex{sys/stat.h}
5299 If the macros @code{S_ISDIR}, @code{S_ISREG}, etc.@: defined in
5300 @file{sys/stat.h} do not work properly (returning false positives),
5301 define @code{STAT_MACROS_BROKEN}.  This is the case on Tektronix UTekV,
5302 Amdahl UTS and Motorola System V/88.
5304 This macro is obsolescent, as no current systems have the bug.
5305 New programs need not use this macro.
5306 @end defmac
5308 @defmac AC_HEADER_STDBOOL
5309 @acindex{HEADER_STDBOOL}
5310 @cvindex HAVE_STDBOOL_H
5311 @cvindex HAVE__BOOL
5312 @hdrindex{stdbool.h}
5313 @hdrindex{system.h}
5314 If @file{stdbool.h} exists and conforms to C99, define
5315 @code{HAVE_STDBOOL_H} to 1; if the type @code{_Bool} is defined, define
5316 @code{HAVE__BOOL} to 1.  To fulfill the C99 requirements, your
5317 @file{system.h} could contain the following code:
5319 @verbatim
5320 #ifdef HAVE_STDBOOL_H
5321 # include <stdbool.h>
5322 #else
5323 # ifndef HAVE__BOOL
5324 #  ifdef __cplusplus
5325 typedef bool _Bool;
5326 #  else
5327 #   define _Bool signed char
5328 #  endif
5329 # endif
5330 # define bool _Bool
5331 # define false 0
5332 # define true 1
5333 # define __bool_true_false_are_defined 1
5334 #endif
5335 @end verbatim
5337 Alternatively you can use the @samp{stdbool} package of Gnulib
5338 (@pxref{Gnulib}); it packages the above code into a replacement header
5339 and contains a few other bells and whistles.
5341 @end defmac
5344 @defmac AC_HEADER_STDC
5345 @acindex{HEADER_STDC}
5346 @cvindex STDC_HEADERS
5347 @hdrindex{stdlib.h}
5348 @hdrindex{stdarg.h}
5349 @hdrindex{string.h}
5350 @hdrindex{float.h}
5351 @hdrindex{ctype.h}
5352 Define @code{STDC_HEADERS} if the system has C header files
5353 conforming to @acronym{ANSI} C89 (@acronym{ISO} C90).
5354 Specifically, this macro checks for @file{stdlib.h}, @file{stdarg.h},
5355 @file{string.h}, and @file{float.h}; if the system has those, it
5356 probably has the rest of the C89 header files.  This macro also
5357 checks whether @file{string.h} declares @code{memchr} (and thus
5358 presumably the other @code{mem} functions), whether @file{stdlib.h}
5359 declare @code{free} (and thus presumably @code{malloc} and other related
5360 functions), and whether the @file{ctype.h} macros work on characters
5361 with the high bit set, as the C standard requires.
5363 If you use this macro, your code can refer to @code{STDC_HEADERS} to
5364 determine whether the system has conforming header files (and probably C
5365 library functions).
5367 This macro is obsolescent, as current systems have conforming header
5368 files.  New programs need not use this macro.
5370 @hdrindex{string.h}
5371 @hdrindex{strings.h}
5372 Nowadays @file{string.h} is part of the C standard and declares functions like
5373 @code{strcpy}, and @file{strings.h} is standardized by Posix and declares
5374 @acronym{BSD} functions like @code{bcopy}; but
5375 historically, string functions were a major sticking point in this area.
5376 If you still want to worry about portability to ancient systems without
5377 standard headers, there is so much variation
5378 that it is probably easier to declare the functions you use than to
5379 figure out exactly what the system header files declare.  Some ancient systems
5380 contained a mix of functions from the C standard and from @acronym{BSD};
5381 some were mostly standard but lacked @samp{memmove}; some defined the
5382 @acronym{BSD} functions as macros in @file{string.h} or
5383 @file{strings.h}; some had only the @acronym{BSD} functions but
5384 @file{string.h}; some declared the memory functions in @file{memory.h},
5385 some in @file{string.h}; etc.  It is probably sufficient to check for
5386 one string function and one memory function; if the library had the
5387 standard versions of those then it probably had most of the others.
5388 If you put the following in @file{configure.ac}:
5390 @example
5391 # This example is obsolescent.
5392 # Nowadays you can omit these macro calls.
5393 AC_HEADER_STDC
5394 AC_CHECK_FUNCS([strchr memcpy])
5395 @end example
5397 @noindent
5398 then, in your code, you can use declarations like this:
5400 @example
5401 @group
5402 /* This example is obsolescent.
5403    Nowadays you can just #include <string.h>.  */
5404 #ifdef STDC_HEADERS
5405 # include <string.h>
5406 #else
5407 # ifndef HAVE_STRCHR
5408 #  define strchr index
5409 #  define strrchr rindex
5410 # endif
5411 char *strchr (), *strrchr ();
5412 # ifndef HAVE_MEMCPY
5413 #  define memcpy(d, s, n) bcopy ((s), (d), (n))
5414 #  define memmove(d, s, n) bcopy ((s), (d), (n))
5415 # endif
5416 #endif
5417 @end group
5418 @end example
5420 @noindent
5421 If you use a function like @code{memchr}, @code{memset}, @code{strtok},
5422 or @code{strspn}, which have no @acronym{BSD} equivalent, then macros don't
5423 suffice to port to ancient hosts; you must provide an implementation of
5424 each function.  An easy
5425 way to incorporate your implementations only when needed (since the ones
5426 in system C libraries may be hand optimized) is to, taking @code{memchr}
5427 for example, put it in @file{memchr.c} and use
5428 @samp{AC_REPLACE_FUNCS([memchr])}.
5429 @end defmac
5431 @defmac AC_HEADER_SYS_WAIT
5432 @acindex{HEADER_SYS_WAIT}
5433 @cvindex HAVE_SYS_WAIT_H
5434 @hdrindex{sys/wait.h}
5435 If @file{sys/wait.h} exists and is compatible with Posix, define
5436 @code{HAVE_SYS_WAIT_H}.  Incompatibility can occur if @file{sys/wait.h}
5437 does not exist, or if it uses the old @acronym{BSD} @code{union wait} instead
5438 of @code{int} to store a status value.  If @file{sys/wait.h} is not
5439 Posix compatible, then instead of including it, define the
5440 Posix macros with their usual interpretations.  Here is an
5441 example:
5443 @example
5444 @group
5445 #include <sys/types.h>
5446 #ifdef HAVE_SYS_WAIT_H
5447 # include <sys/wait.h>
5448 #endif
5449 #ifndef WEXITSTATUS
5450 # define WEXITSTATUS(stat_val) ((unsigned int) (stat_val) >> 8)
5451 #endif
5452 #ifndef WIFEXITED
5453 # define WIFEXITED(stat_val) (((stat_val) & 255) == 0)
5454 #endif
5455 @end group
5456 @end example
5458 @noindent
5459 This macro is obsolescent, as current systems are compatible with Posix.
5460 New programs need not use this macro.
5461 @end defmac
5463 @cvindex _POSIX_VERSION
5464 @hdrindex{unistd.h}
5465 @code{_POSIX_VERSION} is defined when @file{unistd.h} is included on
5466 Posix systems.  If there is no @file{unistd.h}, it is definitely
5467 not a Posix system.  However, some non-Posix systems do
5468 have @file{unistd.h}.
5470 The way to check whether the system supports Posix is:
5472 @example
5473 @group
5474 #ifdef HAVE_UNISTD_H
5475 # include <sys/types.h>
5476 # include <unistd.h>
5477 #endif
5479 #ifdef _POSIX_VERSION
5480 /* Code for Posix systems.  */
5481 #endif
5482 @end group
5483 @end example
5485 @defmac AC_HEADER_TIME
5486 @acindex{HEADER_TIME}
5487 @cvindex TIME_WITH_SYS_TIME
5488 @hdrindex{time.h}
5489 @hdrindex{sys/time.h}
5490 If a program may include both @file{time.h} and @file{sys/time.h},
5491 define @code{TIME_WITH_SYS_TIME}.  On some ancient systems,
5492 @file{sys/time.h} included @file{time.h}, but @file{time.h} was not
5493 protected against multiple inclusion, so programs could not explicitly
5494 include both files.  This macro is useful in programs that use, for
5495 example, @code{struct timeval} as well as
5496 @code{struct tm}.  It is best used in conjunction with
5497 @code{HAVE_SYS_TIME_H}, which can be checked for using
5498 @code{AC_CHECK_HEADERS([sys/time.h])}.
5500 @example
5501 @group
5502 #ifdef TIME_WITH_SYS_TIME
5503 # include <sys/time.h>
5504 # include <time.h>
5505 #else
5506 # ifdef HAVE_SYS_TIME_H
5507 #  include <sys/time.h>
5508 # else
5509 #  include <time.h>
5510 # endif
5511 #endif
5512 @end group
5513 @end example
5515 @noindent
5516 This macro is obsolescent, as current systems can include both files
5517 when they exist.  New programs need not use this macro.
5518 @end defmac
5521 @defmac AC_HEADER_TIOCGWINSZ
5522 @acindex{HEADER_TIOCGWINSZ}
5523 @cvindex GWINSZ_IN_SYS_IOCTL
5524 @hdrindex{sys/ioctl.h}
5525 @hdrindex{termios.h}
5526 @c FIXME: I need clarifications from Jim.
5527 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
5528 define @code{GWINSZ_IN_SYS_IOCTL}.  Otherwise @code{TIOCGWINSZ} can be
5529 found in @file{<termios.h>}.
5531 Use:
5533 @example
5534 @group
5535 #ifdef HAVE_TERMIOS_H
5536 # include <termios.h>
5537 #endif
5539 #ifdef GWINSZ_IN_SYS_IOCTL
5540 # include <sys/ioctl.h>
5541 #endif
5542 @end group
5543 @end example
5544 @end defmac
5546 @node Generic Headers
5547 @subsection Generic Header Checks
5549 These macros are used to find system header files not covered by the
5550 ``particular'' test macros.  If you need to check the contents of a header
5551 as well as find out whether it is present, you have to write your own
5552 test for it (@pxref{Writing Tests}).
5554 @defmac AC_CHECK_HEADER (@var{header-file}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5555 @acindex{CHECK_HEADER}
5556 If the system header file @var{header-file} is compilable, execute shell
5557 commands @var{action-if-found}, otherwise execute
5558 @var{action-if-not-found}.  If you just want to define a symbol if the
5559 header file is available, consider using @code{AC_CHECK_HEADERS}
5560 instead.
5562 For compatibility issues with older versions of Autoconf, please read
5563 below.
5564 @end defmac
5566 @defmac AC_CHECK_HEADERS (@var{header-file}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5567 @acindex{CHECK_HEADERS}
5568 @cvindex HAVE_@var{header}
5569 For each given system header file @var{header-file} in the
5570 blank-separated argument list that exists, define
5571 @code{HAVE_@var{header-file}} (in all capitals).  If @var{action-if-found}
5572 is given, it is additional shell code to execute when one of the header
5573 files is found.  You can give it a value of @samp{break} to break out of
5574 the loop on the first match.  If @var{action-if-not-found} is given, it
5575 is executed when one of the header files is not found.
5577 For compatibility issues with older versions of Autoconf, please read
5578 below.
5579 @end defmac
5581 Previous versions of Autoconf merely checked whether the header was
5582 accepted by the preprocessor.  This was changed because the old test was
5583 inappropriate for typical uses.  Headers are typically used to compile,
5584 not merely to preprocess, and the old behavior sometimes accepted
5585 headers that clashed at compile-time.  If you need to check whether a
5586 header is preprocessable, you can use @code{AC_PREPROC_IFELSE}
5587 (@pxref{Running the Preprocessor}).
5589 This scheme, which improves the robustness of the test, also requires
5590 that you make sure that headers that must be included before the
5591 @var{header-file} be part of the @var{includes}, (@pxref{Default
5592 Includes}).  If looking for @file{bar.h}, which requires that
5593 @file{foo.h} be included before if it exists, we suggest the following
5594 scheme:
5596 @verbatim
5597 AC_CHECK_HEADERS([foo.h])
5598 AC_CHECK_HEADERS([bar.h], [], [],
5599 [#ifdef HAVE_FOO_H
5600 # include <foo.h>
5601 # endif
5603 @end verbatim
5605 The following variant generates smaller, faster @command{configure}
5606 files if you do not need the full power of @code{AC_CHECK_HEADERS}.
5608 @defmac AC_CHECK_HEADERS_ONCE (@var{header-file}@dots{})
5609 @acindex{CHECK_HEADERS_ONCE}
5610 @cvindex HAVE_@var{header}
5611 For each given system header file @var{header-file} in the
5612 blank-separated argument list that exists, define
5613 @code{HAVE_@var{header-file}} (in all capitals).
5614 This is a once-only variant of @code{AC_CHECK_HEADERS}.  It generates the
5615 checking code at most once, so that @command{configure} is smaller and
5616 faster; but the checks cannot be conditionalized and are always done once,
5617 early during the @command{configure} run.
5618 @end defmac
5620 @node Declarations
5621 @section Declarations
5622 @cindex Declaration, checking
5624 The following macros check for the declaration of variables and
5625 functions.  If there is no macro specifically defined to check for a
5626 symbol you need, then you can use the general macros (@pxref{Generic
5627 Declarations}) or, for more complex tests, you may use
5628 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
5630 @menu
5631 * Particular Declarations::     Macros to check for certain declarations
5632 * Generic Declarations::        How to find other declarations
5633 @end menu
5635 @node Particular Declarations
5636 @subsection Particular Declaration Checks
5638 There are no specific macros for declarations.
5640 @node Generic Declarations
5641 @subsection Generic Declaration Checks
5643 These macros are used to find declarations not covered by the ``particular''
5644 test macros.
5646 @defmac AC_CHECK_DECL (@var{symbol}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5647 @acindex{CHECK_DECL}
5648 If @var{symbol} (a function, variable, or constant) is not declared in
5649 @var{includes} and a declaration is needed, run the shell commands
5650 @var{action-if-not-found}, otherwise @var{action-if-found}.  If no
5651 @var{includes} are specified, the default includes are used
5652 (@pxref{Default Includes}).
5654 This macro actually tests whether @var{symbol} is defined as a macro or
5655 can be used as an r-value, not whether it is really declared, because it
5656 is much safer to avoid
5657 introducing extra declarations when they are not needed.
5658 @end defmac
5660 @defmac AC_CHECK_DECLS (@var{symbols}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5661 @acindex{CHECK_DECLS}
5662 @cvindex HAVE_DECL_@var{symbol}
5663 For each of the @var{symbols} (@emph{comma}-separated list), define
5664 @code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
5665 @var{symbol} is declared, otherwise to @samp{0}.  If
5666 @var{action-if-not-found} is given, it is additional shell code to
5667 execute when one of the function declarations is needed, otherwise
5668 @var{action-if-found} is executed.
5670 This macro uses an M4 list as first argument:
5671 @example
5672 AC_CHECK_DECLS([strdup])
5673 AC_CHECK_DECLS([strlen])
5674 AC_CHECK_DECLS([malloc, realloc, calloc, free])
5675 @end example
5677 Unlike the other @samp{AC_CHECK_*S} macros, when a @var{symbol} is not
5678 declared, @code{HAVE_DECL_@var{symbol}} is defined to @samp{0} instead
5679 of leaving @code{HAVE_DECL_@var{symbol}} undeclared.  When you are
5680 @emph{sure} that the check was performed, use
5681 @code{HAVE_DECL_@var{symbol}} in @code{#if}:
5683 @example
5684 #if !HAVE_DECL_SYMBOL
5685 extern char *symbol;
5686 #endif
5687 @end example
5689 @noindent
5690 If the test may have not been performed, however, because it is safer
5691 @emph{not} to declare a symbol than to use a declaration that conflicts
5692 with the system's one, you should use:
5694 @example
5695 #if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC
5696 void *malloc (size_t *s);
5697 #endif
5698 @end example
5700 @noindent
5701 You fall into the second category only in extreme situations: either
5702 your files may be used without being configured, or they are used during
5703 the configuration.  In most cases the traditional approach is enough.
5704 @end defmac
5706 @defmac AC_CHECK_DECLS_ONCE (@var{symbols})
5707 @acindex{CHECK_DECLS_ONCE}
5708 @cvindex HAVE_DECL_@var{symbol}
5709 For each of the @var{symbols} (@emph{comma}-separated list), define
5710 @code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
5711 @var{symbol} is declared in the default include files, otherwise to
5712 @samp{0}.  This is a once-only variant of @code{AC_CHECK_DECLS}.  It
5713 generates the checking code at most once, so that @command{configure} is
5714 smaller and faster; but the checks cannot be conditionalized and are
5715 always done once, early during the @command{configure} run.
5716 @end defmac
5719 @node Structures
5720 @section Structures
5721 @cindex Structure, checking
5723 The following macros check for the presence of certain members in C
5724 structures.  If there is no macro specifically defined to check for a
5725 member you need, then you can use the general structure-member macros
5726 (@pxref{Generic Structures}) or, for more complex tests, you may use
5727 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
5729 @menu
5730 * Particular Structures::       Macros to check for certain structure members
5731 * Generic Structures::          How to find other structure members
5732 @end menu
5734 @node Particular Structures
5735 @subsection Particular Structure Checks
5737 The following macros check for certain structures or structure members.
5739 @defmac AC_STRUCT_DIRENT_D_INO
5740 @acindex{STRUCT_DIRENT_D_INO}
5741 @cvindex HAVE_STRUCT_DIRENT_D_INO
5742 Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular
5743 Headers}).  Then, if @code{struct dirent} contains a @code{d_ino}
5744 member, define @code{HAVE_STRUCT_DIRENT_D_INO}.
5746 @code{HAVE_STRUCT_DIRENT_D_INO} indicates only the presence of
5747 @code{d_ino}, not whether its contents are always reliable.
5748 Traditionally, a zero @code{d_ino} indicated a deleted directory entry,
5749 though current systems hide this detail from the user and never return
5750 zero @code{d_ino} values.
5751 Many current systems report an incorrect @code{d_ino} for a directory
5752 entry that is a mount point.
5753 @end defmac
5755 @defmac AC_STRUCT_DIRENT_D_TYPE
5756 @acindex{STRUCT_DIRENT_D_TYPE}
5757 @cvindex HAVE_STRUCT_DIRENT_D_TYPE
5758 Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular
5759 Headers}).  Then, if @code{struct dirent} contains a @code{d_type}
5760 member, define @code{HAVE_STRUCT_DIRENT_D_TYPE}.
5761 @end defmac
5763 @defmac AC_STRUCT_ST_BLKSIZE
5764 @acindex{STRUCT_ST_BLKSIZE}
5765 @cvindex HAVE_STRUCT_STAT_ST_BLKSIZE
5766 @cvindex HAVE_ST_BLKSIZE
5767 If @code{struct stat} contains an @code{st_blksize} member, define
5768 @code{HAVE_STRUCT_STAT_ST_BLKSIZE}.  The former name,
5769 @code{HAVE_ST_BLKSIZE} is to be avoided, as its support will cease in
5770 the future.  This macro is obsoleted, and should be replaced by
5772 @example
5773 AC_CHECK_MEMBERS([struct stat.st_blksize])
5774 @end example
5775 @end defmac
5777 @defmac AC_STRUCT_ST_BLOCKS
5778 @acindex{STRUCT_ST_BLOCKS}
5779 @cvindex HAVE_STRUCT_STAT_ST_BLOCKS
5780 @cvindex HAVE_ST_BLOCKS
5781 @ovindex LIBOBJS
5782 If @code{struct stat} contains an @code{st_blocks} member, define
5783 @code{HAVE_STRUCT_STAT_ST_BLOCKS}.  Otherwise, require an
5784 @code{AC_LIBOBJ} replacement of @samp{fileblocks}.  The former name,
5785 @code{HAVE_ST_BLOCKS} is to be avoided, as its support will cease in the
5786 future.
5787 @end defmac
5789 @defmac AC_STRUCT_ST_RDEV
5790 @acindex{STRUCT_ST_RDEV}
5791 @cvindex HAVE_ST_RDEV
5792 @cvindex HAVE_STRUCT_STAT_ST_RDEV
5793 If @code{struct stat} contains an @code{st_rdev} member, define
5794 @code{HAVE_STRUCT_STAT_ST_RDEV}.  The former name for this macro,
5795 @code{HAVE_ST_RDEV}, is to be avoided as it will cease to be supported
5796 in the future.  Actually, even the new macro is obsolete and should be
5797 replaced by:
5798 @example
5799 AC_CHECK_MEMBERS([struct stat.st_rdev])
5800 @end example
5801 @end defmac
5803 @defmac AC_STRUCT_TM
5804 @acindex{STRUCT_TM}
5805 @cvindex TM_IN_SYS_TIME
5806 @hdrindex{time.h}
5807 @hdrindex{sys/time.h}
5808 If @file{time.h} does not define @code{struct tm}, define
5809 @code{TM_IN_SYS_TIME}, which means that including @file{sys/time.h}
5810 had better define @code{struct tm}.
5812 This macro is obsolescent, as @file{time.h} defines @code{struct tm} in
5813 current systems.  New programs need not use this macro.
5814 @end defmac
5816 @defmac AC_STRUCT_TIMEZONE
5817 @acindex{STRUCT_TIMEZONE}
5818 @cvindex HAVE_TM_ZONE
5819 @cvindex HAVE_TZNAME
5820 Figure out how to get the current timezone.  If @code{struct tm} has a
5821 @code{tm_zone} member, define @code{HAVE_STRUCT_TM_TM_ZONE} (and the
5822 obsoleted @code{HAVE_TM_ZONE}).  Otherwise, if the external array
5823 @code{tzname} is found, define @code{HAVE_TZNAME}; if it is declared,
5824 define @code{HAVE_DECL_TZNAME}.
5825 @end defmac
5827 @node Generic Structures
5828 @subsection Generic Structure Checks
5830 These macros are used to find structure members not covered by the
5831 ``particular'' test macros.
5833 @defmac AC_CHECK_MEMBER (@var{aggregate}.@var{member}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5834 @acindex{CHECK_MEMBER}
5835 Check whether @var{member} is a member of the aggregate @var{aggregate}.
5836 If no @var{includes} are specified, the default includes are used
5837 (@pxref{Default Includes}).
5839 @example
5840 AC_CHECK_MEMBER([struct passwd.pw_gecos], [],
5841                 [AC_MSG_ERROR([We need `passwd.pw_gecos'!])],
5842                 [#include <pwd.h>])
5843 @end example
5845 You can use this macro for submembers:
5847 @example
5848 AC_CHECK_MEMBER(struct top.middle.bot)
5849 @end example
5850 @end defmac
5852 @defmac AC_CHECK_MEMBERS (@var{members}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5853 @acindex{CHECK_MEMBERS}
5854 Check for the existence of each @samp{@var{aggregate}.@var{member}} of
5855 @var{members} using the previous macro.  When @var{member} belongs to
5856 @var{aggregate}, define @code{HAVE_@var{aggregate}_@var{member}} (in all
5857 capitals, with spaces and dots replaced by underscores).  If
5858 @var{action-if-found} is given, it is executed for each of the found
5859 members.  If @var{action-if-not-found} is given, it is executed for each
5860 of the members that could not be found.
5862 This macro uses M4 lists:
5863 @example
5864 AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize])
5865 @end example
5866 @end defmac
5869 @node Types
5870 @section Types
5871 @cindex Types
5872 @cindex C types
5874 The following macros check for C types, either builtin or typedefs.  If
5875 there is no macro specifically defined to check for a type you need, and
5876 you don't need to check for any special properties of it, then you can
5877 use a general type-check macro.
5879 @menu
5880 * Particular Types::            Special handling to find certain types
5881 * Generic Types::               How to find other types
5882 @end menu
5884 @node Particular Types
5885 @subsection Particular Type Checks
5887 @hdrindex{sys/types.h}
5888 @hdrindex{stdlib.h}
5889 @hdrindex{stdint.h}
5890 @hdrindex{inttypes.h}
5891 These macros check for particular C types in @file{sys/types.h},
5892 @file{stdlib.h}, @file{stdint.h}, @file{inttypes.h} and others, if they
5893 exist.
5895 The Gnulib @code{stdint} module is an alternate way to define many of
5896 these symbols; it is useful if you prefer your code to assume a
5897 C99-or-better environment.  @xref{Gnulib}.
5899 @defmac AC_TYPE_GETGROUPS
5900 @acindex{TYPE_GETGROUPS}
5901 @cvindex GETGROUPS_T
5902 Define @code{GETGROUPS_T} to be whichever of @code{gid_t} or @code{int}
5903 is the base type of the array argument to @code{getgroups}.
5904 @end defmac
5906 @defmac AC_TYPE_INT8_T
5907 @acindex{TYPE_INT8_T}
5908 @cvindex HAVE_INT8_T
5909 @cvindex int8_t
5910 If @file{stdint.h} or @file{inttypes.h} does not define the type
5911 @code{int8_t}, define @code{int8_t} to a signed
5912 integer type that is exactly 8 bits wide and that uses two's complement
5913 representation, if such a type exists.
5914 If you are worried about porting to hosts that lack such a type, you can
5915 use the results of this macro in C89-or-later code as follows:
5917 @example
5918 #if HAVE_STDINT_H
5919 # include <stdint.h>
5920 #endif
5921 #if defined INT8_MAX || defined int8_t
5922  @emph{code using int8_t}
5923 #else
5924  @emph{complicated alternative using >8-bit 'signed char'}
5925 #endif
5926 @end example
5927 @end defmac
5929 @defmac AC_TYPE_INT16_T
5930 @acindex{TYPE_INT16_T}
5931 @cvindex HAVE_INT16_T
5932 @cvindex int16_t
5933 This is like @code{AC_TYPE_INT8_T}, except for 16-bit integers.
5934 @end defmac
5936 @defmac AC_TYPE_INT32_T
5937 @acindex{TYPE_INT32_T}
5938 @cvindex HAVE_INT32_T
5939 @cvindex int32_t
5940 This is like @code{AC_TYPE_INT8_T}, except for 32-bit integers.
5941 @end defmac
5943 @defmac AC_TYPE_INT64_T
5944 @acindex{TYPE_INT64_T}
5945 @cvindex HAVE_INT64_T
5946 @cvindex int64_t
5947 This is like @code{AC_TYPE_INT8_T}, except for 64-bit integers.
5948 @end defmac
5950 @defmac AC_TYPE_INTMAX_T
5951 @acindex{TYPE_INTMAX_T}
5952 @cvindex HAVE_INTMAX_T
5953 @cvindex intmax_t
5954 If @file{stdint.h} or @file{inttypes.h} defines the type @code{intmax_t},
5955 define @code{HAVE_INTMAX_T}.  Otherwise, define @code{intmax_t} to the
5956 widest signed integer type.
5957 @end defmac
5959 @defmac AC_TYPE_INTPTR_T
5960 @acindex{TYPE_INTPTR_T}
5961 @cvindex HAVE_INTPTR_T
5962 @cvindex intptr_t
5963 If @file{stdint.h} or @file{inttypes.h} defines the type @code{intptr_t},
5964 define @code{HAVE_INTPTR_T}.  Otherwise, define @code{intptr_t} to a
5965 signed integer type wide enough to hold a pointer, if such a type
5966 exists.
5967 @end defmac
5969 @defmac AC_TYPE_LONG_DOUBLE
5970 @acindex{TYPE_LONG_DOUBLE}
5971 @cvindex HAVE_LONG_DOUBLE
5972 If the C compiler supports a working @code{long double} type, define
5973 @code{HAVE_LONG_DOUBLE}.  The @code{long double} type might have the
5974 same range and precision as @code{double}.
5976 This macro is obsolescent, as current C compilers support @code{long
5977 double}.  New programs need not use this macro.
5978 @end defmac
5980 @defmac AC_TYPE_LONG_DOUBLE_WIDER
5981 @acindex{TYPE_LONG_DOUBLE_WIDER}
5982 @cvindex HAVE_LONG_DOUBLE_WIDER
5983 If the C compiler supports a working @code{long double} type with more
5984 range or precision than the @code{double} type, define
5985 @code{HAVE_LONG_DOUBLE_WIDER}.
5986 @end defmac
5988 @defmac AC_TYPE_LONG_LONG_INT
5989 @acindex{TYPE_LONG_LONG_INT}
5990 @cvindex HAVE_LONG_LONG_INT
5991 If the C compiler supports a working @code{long long int} type, define
5992 @code{HAVE_LONG_LONG_INT}.
5993 @end defmac
5995 @defmac AC_TYPE_MBSTATE_T
5996 @acindex{TYPE_MBSTATE_T}
5997 @cvindex mbstate_t
5998 @hdrindex{wchar.h}
5999 Define @code{HAVE_MBSTATE_T} if @code{<wchar.h>} declares the
6000 @code{mbstate_t} type.  Also, define @code{mbstate_t} to be a type if
6001 @code{<wchar.h>} does not declare it.
6002 @end defmac
6004 @defmac AC_TYPE_MODE_T
6005 @acindex{TYPE_MODE_T}
6006 @cvindex mode_t
6007 Define @code{mode_t} to a suitable type, if standard headers do not
6008 define it.
6009 @end defmac
6011 @defmac AC_TYPE_OFF_T
6012 @acindex{TYPE_OFF_T}
6013 @cvindex off_t
6014 Define @code{off_t} to a suitable type, if standard headers do not
6015 define it.
6016 @end defmac
6018 @defmac AC_TYPE_PID_T
6019 @acindex{TYPE_PID_T}
6020 @cvindex pid_t
6021 Define @code{pid_t} to a suitable type, if standard headers do not
6022 define it.
6023 @end defmac
6025 @defmac AC_TYPE_SIGNAL
6026 @acindex{TYPE_SIGNAL}
6027 @cvindex RETSIGTYPE
6028 @hdrindex{signal.h}
6029 If @file{signal.h} declares @code{signal} as returning a pointer to a
6030 function returning @code{void}, define @code{RETSIGTYPE} to be
6031 @code{void}; otherwise, define it to be @code{int}.
6033 Define signal handlers as returning type @code{RETSIGTYPE}:
6035 @example
6036 @group
6037 RETSIGTYPE
6038 hup_handler ()
6040 @dots{}
6042 @end group
6043 @end example
6044 @end defmac
6046 @defmac AC_TYPE_SIZE_T
6047 @acindex{TYPE_SIZE_T}
6048 @cvindex size_t
6049 Define @code{size_t} to a suitable type, if standard headers do not
6050 define it.
6051 @end defmac
6053 @defmac AC_TYPE_SSIZE_T
6054 @acindex{TYPE_SSIZE_T}
6055 @cvindex ssize_t
6056 Define @code{ssize_t} to a suitable type, if standard headers do not
6057 define it.
6058 @end defmac
6060 @defmac AC_TYPE_UID_T
6061 @acindex{TYPE_UID_T}
6062 @cvindex uid_t
6063 @cvindex gid_t
6064 Define @code{uid_t} and @code{gid_t} to suitable types, if standard
6065 headers do not define them.
6066 @end defmac
6068 @defmac AC_TYPE_UINT8_T
6069 @acindex{TYPE_UINT8_T}
6070 @cvindex HAVE_UINT8_T
6071 @cvindex uint8_t
6072 If @file{stdint.h} or @file{inttypes.h} does not define the type
6073 @code{uint8_t}, define @code{uint8_t} to an
6074 unsigned integer type that is exactly 8 bits wide, if such a type
6075 exists.
6076 This is like @code{AC_TYPE_INT8_T}, except for unsigned integers.
6077 @end defmac
6079 @defmac AC_TYPE_UINT16_T
6080 @acindex{TYPE_UINT16_T}
6081 @cvindex HAVE_UINT16_T
6082 @cvindex uint16_t
6083 This is like @code{AC_TYPE_UINT8_T}, except for 16-bit integers.
6084 @end defmac
6086 @defmac AC_TYPE_UINT32_T
6087 @acindex{TYPE_UINT32_T}
6088 @cvindex HAVE_UINT32_T
6089 @cvindex uint32_t
6090 This is like @code{AC_TYPE_UINT8_T}, except for 32-bit integers.
6091 @end defmac
6093 @defmac AC_TYPE_UINT64_T
6094 @acindex{TYPE_UINT64_T}
6095 @cvindex HAVE_UINT64_T
6096 @cvindex uint64_t
6097 This is like @code{AC_TYPE_UINT8_T}, except for 64-bit integers.
6098 @end defmac
6100 @defmac AC_TYPE_UINTMAX_T
6101 @acindex{TYPE_UINTMAX_T}
6102 @cvindex HAVE_UINTMAX_T
6103 @cvindex uintmax_t
6104 If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintmax_t},
6105 define @code{HAVE_UINTMAX_T}.  Otherwise, define @code{uintmax_t} to the
6106 widest unsigned integer type.
6107 @end defmac
6109 @defmac AC_TYPE_UINTPTR_T
6110 @acindex{TYPE_UINTPTR_T}
6111 @cvindex HAVE_UINTPTR_T
6112 @cvindex uintptr_t
6113 If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintptr_t},
6114 define @code{HAVE_UINTPTR_T}.  Otherwise, define @code{uintptr_t} to an
6115 unsigned integer type wide enough to hold a pointer, if such a type
6116 exists.
6117 @end defmac
6119 @defmac AC_TYPE_UNSIGNED_LONG_LONG_INT
6120 @acindex{TYPE_UNSIGNED_LONG_LONG_INT}
6121 @cvindex HAVE_UNSIGNED_LONG_LONG_INT
6122 If the C compiler supports a working @code{unsigned long long int} type,
6123 define @code{HAVE_UNSIGNED_LONG_LONG_INT}.
6124 @end defmac
6126 @node Generic Types
6127 @subsection Generic Type Checks
6129 These macros are used to check for types not covered by the ``particular''
6130 test macros.
6132 @defmac AC_CHECK_TYPE (@var{type}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
6133 @acindex{CHECK_TYPE}
6134 Check whether @var{type} is defined.  It may be a compiler builtin type
6135 or defined by the @var{includes} (@pxref{Default Includes}).
6137 In C, @var{type} must be a type-name, so that the expression @samp{sizeof
6138 (@var{type})} is valid (but @samp{sizeof ((@var{type}))} is not).  The
6139 same test is applied when compiling for C++, which means that in C++
6140 @var{type} should be a type-id and should not be an anonymous
6141 @samp{struct} or @samp{union}.
6142 @end defmac
6145 @defmac AC_CHECK_TYPES (@var{types}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
6146 @acindex{CHECK_TYPES}
6147 For each @var{type} of the @var{types} that is defined, define
6148 @code{HAVE_@var{type}} (in all capitals).  Each @var{type} must follow
6149 the rules of @code{AC_CHECK_TYPE}.  If no @var{includes} are
6150 specified, the default includes are used (@pxref{Default Includes}).  If
6151 @var{action-if-found} is given, it is additional shell code to execute
6152 when one of the types is found.  If @var{action-if-not-found} is given,
6153 it is executed when one of the types is not found.
6155 This macro uses M4 lists:
6156 @example
6157 AC_CHECK_TYPES([ptrdiff_t])
6158 AC_CHECK_TYPES([unsigned long long int, uintmax_t])
6159 @end example
6161 @end defmac
6163 Autoconf, up to 2.13, used to provide to another version of
6164 @code{AC_CHECK_TYPE}, broken by design.  In order to keep backward
6165 compatibility, a simple heuristic, quite safe but not totally, is
6166 implemented.  In case of doubt, read the documentation of the former
6167 @code{AC_CHECK_TYPE}, see @ref{Obsolete Macros}.
6170 @node Compilers and Preprocessors
6171 @section Compilers and Preprocessors
6172 @cindex Compilers
6173 @cindex Preprocessors
6175 @ovindex EXEEXT
6176 All the tests for compilers (@code{AC_PROG_CC}, @code{AC_PROG_CXX},
6177 @code{AC_PROG_F77}) define the output variable @code{EXEEXT} based on
6178 the output of the compiler, typically to the empty string if
6179 Posix and @samp{.exe} if a @acronym{DOS} variant.
6181 @ovindex OBJEXT
6182 They also define the output variable @code{OBJEXT} based on the
6183 output of the compiler, after @file{.c} files have been excluded, typically
6184 to @samp{o} if Posix, @samp{obj} if a @acronym{DOS} variant.
6186 If the compiler being used does not produce executables, the tests fail.  If
6187 the executables can't be run, and cross-compilation is not enabled, they
6188 fail too.  @xref{Manual Configuration}, for more on support for cross
6189 compiling.
6191 @menu
6192 * Specific Compiler Characteristics::  Some portability issues
6193 * Generic Compiler Characteristics::  Language independent tests and features
6194 * C Compiler::                  Checking its characteristics
6195 * C++ Compiler::                Likewise
6196 * Objective C Compiler::        Likewise
6197 * Erlang Compiler and Interpreter::  Likewise
6198 * Fortran Compiler::            Likewise
6199 @end menu
6201 @node Specific Compiler Characteristics
6202 @subsection Specific Compiler Characteristics
6204 Some compilers exhibit different behaviors.
6206 @table @asis
6207 @item Static/Dynamic Expressions
6208 Autoconf relies on a trick to extract one bit of information from the C
6209 compiler: using negative array sizes.  For instance the following
6210 excerpt of a C source demonstrates how to test whether @samp{int} objects are 4
6211 bytes wide:
6213 @example
6214 static int test_array[sizeof (int) == 4 ? 1 : -1];
6215 @end example
6217 @noindent
6218 To our knowledge, there is a single compiler that does not support this
6219 trick: the @acronym{HP} C compilers (the real ones, not only the ``bundled'') on
6220 @acronym{HP-UX} 11.00.
6221 They incorrectly reject the above program with the diagnostic
6222 ``Variable-length arrays cannot have static storage.''
6223 This bug comes from @acronym{HP} compilers' mishandling of @code{sizeof (int)},
6224 not from the @code{? 1 : -1}, and
6225 Autoconf works around this problem by casting @code{sizeof (int)} to
6226 @code{long int} before comparing it.
6227 @end table
6229 @node Generic Compiler Characteristics
6230 @subsection Generic Compiler Characteristics
6232 @defmac AC_CHECK_SIZEOF (@var{type-or-expr}, @ovar{unused}, @dvar{includes, default-includes})
6233 @acindex{CHECK_SIZEOF}
6234 Define @code{SIZEOF_@var{type-or-expr}} (@pxref{Standard Symbols}) to be
6235 the size in bytes of @var{type-or-expr}, which may be either a type or
6236 an expression returning a value that has a size.  If the expression
6237 @samp{sizeof (@var{type-or-expr})} is invalid, the result is 0.  If no
6238 @var{includes} are specified, the default includes are used
6239 (@pxref{Default Includes}).
6241 This macro now works even when cross-compiling.  The @var{unused}
6242 argument was used when cross-compiling.
6244 For example, the call
6246 @example
6247 AC_CHECK_SIZEOF([int *])
6248 @end example
6250 @noindent
6251 defines @code{SIZEOF_INT_P} to be 8 on DEC Alpha AXP systems.
6252 @end defmac
6254 @defmac AC_CHECK_ALIGNOF (@var{type}, @dvar{includes, default-includes})
6255 @acindex{CHECK_ALIGNOF}
6256 Define @code{ALIGNOF_@var{type}} (@pxref{Standard Symbols}) to be the
6257 alignment in bytes of @var{type}.  @samp{@var{type} y;} must be valid as
6258 a structure member declaration.  If @samp{type} is unknown, the result
6259 is 0.  If no @var{includes} are specified, the default includes are used
6260 (@pxref{Default Includes}).
6261 @end defmac
6263 @defmac AC_COMPUTE_INT (@var{var}, @var{expression}, @dvar{includes, default-includes}, @ovar{action-if-fails})
6264 @acindex{COMPUTE_INT}
6265 Store into the shell variable @var{var} the value of the integer
6266 @var{expression}.  The
6267 value should fit in an initializer in a C variable of type @code{signed
6268 long}.  To support cross compilation (in which case, the macro only works on
6269 hosts that use twos-complement arithmetic), it should be possible to evaluate
6270 the expression at compile-time.  If no @var{includes} are specified, the default
6271 includes are used (@pxref{Default Includes}).
6273 Execute @var{action-if-fails} if the value cannot be determined correctly.
6274 @end defmac
6276 @defmac AC_LANG_WERROR
6277 @acindex{LANG_WERROR}
6278 Normally Autoconf ignores warnings generated by the compiler, linker, and
6279 preprocessor.  If this macro is used, warnings count as fatal
6280 errors for the current language.  This macro is useful when the
6281 results of configuration are used where warnings are unacceptable; for
6282 instance, if parts of a program are built with the @acronym{GCC}
6283 @option{-Werror}
6284 option.  If the whole program is built using @option{-Werror} it is
6285 often simpler to put @option{-Werror} in the compiler flags (@code{CFLAGS},
6286 etc.).
6287 @end defmac
6289 @defmac AC_OPENMP
6290 @acindex{OPENMP}
6291 @cvindex _OPENMP
6292 OpenMP (@url{http://www.openmp.org/}) specifies extensions of C, C++,
6293 and Fortran that simplify optimization of shared memory parallelism,
6294 which is a common problem on multicore CPUs.
6296 If the current language is C, the macro @code{AC_OPENMP} sets the
6297 variable @code{OPENMP_CFLAGS} to the C compiler flags needed for
6298 supporting OpenMP@.  @code{OPENMP_CFLAGS} is set to empty if the
6299 compiler already supports OpenMP, if it has no way to activate OpenMP
6300 support, or if the user rejects OpenMP support by invoking
6301 @samp{configure} with the @samp{--disable-openmp} option.
6303 @code{OPENMP_CFLAGS} needs to be used when compiling programs, when
6304 preprocessing program source, and when linking programs.  Therefore you
6305 need to add @code{$(OPENMP_CFLAGS)} to the @code{CFLAGS} of C programs
6306 that use OpenMP@.  If you preprocess OpenMP-specific C code, you also
6307 need to add @code{$(OPENMP_CFLAGS)} to @code{CPPFLAGS}.  The presence of
6308 OpenMP support is revealed at compile time by the preprocessor macro
6309 @code{_OPENMP}.
6311 Linking a program with @code{OPENMP_CFLAGS} typically adds one more
6312 shared library to the program's dependencies, so its use is recommended
6313 only on programs that actually require OpenMP.
6315 If the current language is C++, @code{AC_OPENMP} sets the variable
6316 @code{OPENMP_CXXFLAGS}, suitably for the C++ compiler.  The same remarks
6317 hold as for C.
6319 If the current language is Fortran 77 or Fortran, @code{AC_OPENMP} sets
6320 the variable @code{OPENMP_FFLAGS} or @code{OPENMP_FCFLAGS},
6321 respectively.  Similar remarks as for C hold, except that
6322 @code{CPPFLAGS} is not used for Fortran, and no preprocessor macro
6323 signals OpenMP support.
6324 @end defmac
6326 @node C Compiler
6327 @subsection C Compiler Characteristics
6329 The following macros provide ways to find and exercise a C Compiler.
6330 There are a few constructs that ought to be avoided, but do not deserve
6331 being checked for, since they can easily be worked around.
6333 @table @asis
6334 @item Don't use lines containing solitary backslashes
6335 They tickle a bug in the @acronym{HP-UX} C compiler (checked on
6336 @acronym{HP-UX} 10.20,
6337 11.00, and 11i).  When given the following source:
6339 @example
6340 #ifdef __STDC__
6342 * A comment with backslash-newlines in it.  %@{ %@} *\
6345 char str[] = "\\
6346 " A string with backslash-newlines in it %@{ %@} \\
6348 char apostrophe = '\\
6352 #endif
6353 @end example
6355 @noindent
6356 the compiler incorrectly fails with the diagnostics ``Non-terminating
6357 comment at end of file'' and ``Missing @samp{#endif} at end of file.''
6358 Removing the lines with solitary backslashes solves the problem.
6360 @item Don't compile several files at once if output matters to you
6361 Some compilers, such as @acronym{HP}'s, report names of files being
6362 compiled when given more than one file operand.  For instance:
6364 @example
6365 $ @kbd{cc a.c b.c}
6366 a.c:
6367 b.c:
6368 @end example
6370 @noindent
6371 This can cause problems if you observe the output of the compiler to
6372 detect failures.  Invoking @samp{cc -c a.c && cc -c b.c && cc -o c a.o
6373 b.o} solves the issue.
6375 @item Don't rely on @code{#error} failing
6376 The @sc{irix} C compiler does not fail when #error is preprocessed; it
6377 simply emits a diagnostic and continues, exiting successfully.  So,
6378 instead of an error directive like @code{#error "Unsupported word size"}
6379 it is more portable to use an invalid directive like @code{#Unsupported
6380 word size} in Autoconf tests.  In ordinary source code, @code{#error} is
6381 OK, since installers with inadequate compilers like @sc{irix} can simply
6382 examine these compilers' diagnostic output.
6384 @item Don't rely on correct @code{#line} support
6385 On Solaris, @command{c89} (at least Sun C 5.3 through 5.8)
6386 diagnoses @code{#line} directives whose line
6387 numbers are greater than 32767.  Nothing in Posix
6388 makes this invalid.  That is why Autoconf stopped issuing
6389 @code{#line} directives.
6390 @end table
6392 @defmac AC_PROG_CC (@ovar{compiler-search-list})
6393 @acindex{PROG_CC}
6394 @ovindex CC
6395 @ovindex CFLAGS
6396 Determine a C compiler to use.  If @code{CC} is not already set in the
6397 environment, check for @code{gcc} and @code{cc}, then for other C
6398 compilers.  Set output variable @code{CC} to the name of the compiler
6399 found.
6401 This macro may, however, be invoked with an optional first argument
6402 which, if specified, must be a blank-separated list of C compilers to
6403 search for.  This just gives the user an opportunity to specify an
6404 alternative search list for the C compiler.  For example, if you didn't
6405 like the default order, then you could invoke @code{AC_PROG_CC} like
6406 this:
6408 @example
6409 AC_PROG_CC([gcc cl cc])
6410 @end example
6412 If the C compiler does not handle function prototypes correctly by
6413 default, try to add an option to output variable @code{CC} to make it
6414 so.  This macro tries various options that select standard-conformance
6415 modes on various systems.
6417 After calling this macro you can check whether the C compiler has been
6418 set to accept @acronym{ANSI} C89 (@acronym{ISO} C90); if not, the shell
6419 variable
6420 @code{ac_cv_prog_cc_c89} is set to @samp{no}.  See also
6421 @code{AC_C_PROTOTYPES} below.
6423 If using the @acronym{GNU} C compiler, set shell variable @code{GCC} to
6424 @samp{yes}.  If output variable @code{CFLAGS} was not already set, set
6425 it to @option{-g -O2} for the @acronym{GNU} C compiler (@option{-O2} on systems
6426 where @acronym{GCC} does not accept @option{-g}), or @option{-g} for
6427 other compilers.
6428 @end defmac
6430 @defmac AC_PROG_CC_C_O
6431 @acindex{PROG_CC_C_O}
6432 @cvindex NO_MINUS_C_MINUS_O
6433 If the C compiler does not accept the @option{-c} and @option{-o} options
6434 simultaneously, define @code{NO_MINUS_C_MINUS_O}.  This macro actually
6435 tests both the compiler found by @code{AC_PROG_CC}, and, if different,
6436 the first @code{cc} in the path.  The test fails if one fails.  This
6437 macro was created for @acronym{GNU} Make to choose the default C compilation
6438 rule.
6439 @end defmac
6442 @defmac AC_PROG_CPP
6443 @acindex{PROG_CPP}
6444 @ovindex CPP
6445 Set output variable @code{CPP} to a command that runs the
6446 C preprocessor.  If @samp{$CC -E} doesn't work, @file{/lib/cpp} is used.
6447 It is only portable to run @code{CPP} on files with a @file{.c}
6448 extension.
6450 Some preprocessors don't indicate missing include files by the error
6451 status.  For such preprocessors an internal variable is set that causes
6452 other macros to check the standard error from the preprocessor and
6453 consider the test failed if any warnings have been reported.
6454 For most preprocessors, though, warnings do not cause include-file
6455 tests to fail unless @code{AC_PROG_CPP_WERROR} is also specified.
6456 @end defmac
6458 @defmac AC_PROG_CPP_WERROR
6459 @acindex{PROG_CPP_WERROR}
6460 @ovindex CPP
6461 This acts like @code{AC_PROG_CPP}, except it treats warnings from the
6462 preprocessor as errors even if the preprocessor exit status indicates
6463 success.  This is useful for avoiding headers that generate mandatory
6464 warnings, such as deprecation notices.
6465 @end defmac
6468 The following macros check for C compiler or machine architecture
6469 features.  To check for characteristics not listed here, use
6470 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
6471 @code{AC_RUN_IFELSE} (@pxref{Runtime}).
6473 @defmac AC_PROG_CC_STDC
6474 @acindex{PROG_CC_STDC}
6475 If the C compiler cannot compile @acronym{ISO} Standard C (currently
6476 C99), try to add an option to output variable @code{CC} to make it work.
6477 If the compiler does not support C99, fall back to supporting
6478 @acronym{ANSI} C89 (@acronym{ISO} C90).
6480 After calling this macro you can check whether the C compiler has been
6481 set to accept Standard C; if not, the shell variable
6482 @code{ac_cv_prog_cc_stdc} is set to @samp{no}.
6483 @end defmac
6485 @defmac AC_PROG_CC_C89
6486 @acindex{PROG_CC_C89}
6487 If the C compiler is not in @acronym{ANSI} C89 (@acronym{ISO} C90) mode by
6488 default, try to add an option to output variable @code{CC} to make it
6489 so.  This macro tries various options that select @acronym{ANSI} C89 on
6490 some system or another.  It considers the compiler to be in
6491 @acronym{ANSI} C89 mode if it handles function prototypes correctly.
6493 After calling this macro you can check whether the C compiler has been
6494 set to accept @acronym{ANSI} C89; if not, the shell variable
6495 @code{ac_cv_prog_cc_c89} is set to @samp{no}.
6497 This macro is called automatically by @code{AC_PROG_CC}.
6498 @end defmac
6500 @defmac AC_PROG_CC_C99
6501 @acindex{PROG_CC_C99}
6502 If the C compiler is not in C99 mode by default, try to add an
6503 option to output variable @code{CC} to make it so.  This macro tries
6504 various options that select C99 on some system or another.  It
6505 considers the compiler to be in C99 mode if it handles @code{_Bool},
6506 @code{//} comments, flexible array members, @code{inline}, signed and
6507 unsigned @code{long long int}, mixed code and declarations, named
6508 initialization of structs,
6509 @code{restrict}, @code{va_copy}, varargs macros, variable declarations
6510 in @code{for} loops, and variable length arrays.
6512 After calling this macro you can check whether the C compiler has been
6513 set to accept C99; if not, the shell variable
6514 @code{ac_cv_prog_cc_c99} is set to @samp{no}.
6515 @end defmac
6517 @defmac AC_C_BACKSLASH_A
6518 @acindex{HAVE_C_BACKSLASH_A}
6519 Define @samp{HAVE_C_BACKSLASH_A} to 1 if the C compiler understands
6520 @samp{\a}.
6522 This macro is obsolescent, as current C compilers understand @samp{\a}.
6523 New programs need not use this macro.
6524 @end defmac
6526 @defmac AC_C_BIGENDIAN (@ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-unknown}, @ovar{action-if-universal})
6527 @acindex{C_BIGENDIAN}
6528 @cvindex WORDS_BIGENDIAN
6529 @cindex Endianness
6530 If words are stored with the most significant byte first (like Motorola
6531 and SPARC CPUs), execute @var{action-if-true}.  If words are stored with
6532 the least significant byte first (like Intel and VAX CPUs), execute
6533 @var{action-if-false}.
6535 This macro runs a test-case if endianness cannot be determined from the
6536 system header files.  When cross-compiling, the test-case is not run but
6537 grep'ed for some magic values.  @var{action-if-unknown} is executed if
6538 the latter case fails to determine the byte sex of the host system.
6540 In some cases a single run of a compiler can generate code for multiple
6541 architectures.  This can happen, for example, when generating Mac OS X
6542 universal binary files, which work on both PowerPC and Intel
6543 architectures.  In this case, the different variants might be for
6544 different architectures whose endiannesses differ.  If
6545 @command{configure} detects this, it executes @var{action-if-universal}
6546 instead of @var{action-if-unknown}.
6548 The default for @var{action-if-true} is to define
6549 @samp{WORDS_BIGENDIAN}.  The default for @var{action-if-false} is to do
6550 nothing.  The default for @var{action-if-unknown} is to
6551 abort configure and tell the installer how to bypass this test.
6552 And finally, the default for @var{action-if-universal} is to define
6553 @samp{WORDS_BIGENDIAN} or not, depending on the architecture that the
6554 code is being generated for.
6556 If you use this macro without specifying @var{action-if-universal}, you
6557 should also use @code{AC_CONFIG_HEADERS}; otherwise
6558 @samp{WORDS_BIGENDIAN} may be set incorrectly for Mac OS X universal
6559 binary files.
6560 @end defmac
6562 @defmac AC_C_CONST
6563 @acindex{C_CONST}
6564 @cvindex const
6565 If the C compiler does not fully support the @code{const} keyword,
6566 define @code{const} to be empty.  Some C compilers that do
6567 not define @code{__STDC__} do support @code{const}; some compilers that
6568 define @code{__STDC__} do not completely support @code{const}.  Programs
6569 can simply use @code{const} as if every C compiler supported it; for
6570 those that don't, the makefile or configuration header file
6571 defines it as empty.
6573 Occasionally installers use a C++ compiler to compile C code, typically
6574 because they lack a C compiler.  This causes problems with @code{const},
6575 because C and C++ treat @code{const} differently.  For example:
6577 @example
6578 const int foo;
6579 @end example
6581 @noindent
6582 is valid in C but not in C++.  These differences unfortunately cannot be
6583 papered over by defining @code{const} to be empty.
6585 If @command{autoconf} detects this situation, it leaves @code{const} alone,
6586 as this generally yields better results in practice.  However, using a
6587 C++ compiler to compile C code is not recommended or supported, and
6588 installers who run into trouble in this area should get a C compiler
6589 like @acronym{GCC} to compile their C code.
6591 This macro is obsolescent, as current C compilers support @code{const}.
6592 New programs need not use this macro.
6593 @end defmac
6595 @defmac AC_C_RESTRICT
6596 @acindex{C_RESTRICT}
6597 @cvindex restrict
6598 If the C compiler recognizes a variant spelling for the @code{restrict}
6599 keyword (@code{__restrict}, @code{__restrict__}, or @code{_Restrict}),
6600 then define @code{restrict} to that; this is more likely to do the right
6601 thing with compilers that support language variants where plain
6602 @code{restrict} is not a keyword.  Otherwise, if the C compiler
6603 recognizes the @code{restrict} keyword, don't do anything.
6604 Otherwise, define @code{restrict} to be empty.
6605 Thus, programs may simply use @code{restrict} as if every C compiler
6606 supported it; for those that do not, the makefile
6607 or configuration header defines it away.
6609 Although support in C++ for the @code{restrict} keyword is not
6610 required, several C++ compilers do accept the keyword.
6611 This macro works for them, too.
6612 @end defmac
6614 @defmac AC_C_VOLATILE
6615 @acindex{C_VOLATILE}
6616 @cvindex volatile
6617 If the C compiler does not understand the keyword @code{volatile},
6618 define @code{volatile} to be empty.  Programs can simply use
6619 @code{volatile} as if every C compiler supported it; for those that do
6620 not, the makefile or configuration header defines it as
6621 empty.
6623 If the correctness of your program depends on the semantics of
6624 @code{volatile}, simply defining it to be empty does, in a sense, break
6625 your code.  However, given that the compiler does not support
6626 @code{volatile}, you are at its mercy anyway.  At least your
6627 program compiles, when it wouldn't before.
6628 @xref{Volatile Objects}, for more about @code{volatile}.
6630 In general, the @code{volatile} keyword is a standard C feature, so
6631 you might expect that @code{volatile} is available only when
6632 @code{__STDC__} is defined.  However, Ultrix 4.3's native compiler does
6633 support volatile, but does not define @code{__STDC__}.
6635 This macro is obsolescent, as current C compilers support @code{volatile}.
6636 New programs need not use this macro.
6637 @end defmac
6639 @defmac AC_C_INLINE
6640 @acindex{C_INLINE}
6641 @cvindex inline
6642 If the C compiler supports the keyword @code{inline}, do nothing.
6643 Otherwise define @code{inline} to @code{__inline__} or @code{__inline}
6644 if it accepts one of those, otherwise define @code{inline} to be empty.
6645 @end defmac
6647 @defmac AC_C_CHAR_UNSIGNED
6648 @acindex{C_CHAR_UNSIGNED}
6649 @cvindex __CHAR_UNSIGNED__
6650 If the C type @code{char} is unsigned, define @code{__CHAR_UNSIGNED__},
6651 unless the C compiler predefines it.
6652 @end defmac
6654 @defmac AC_C_STRINGIZE
6655 @acindex{C_STRINGIZE}
6656 @cvindex HAVE_STRINGIZE
6657 If the C preprocessor supports the stringizing operator, define
6658 @code{HAVE_STRINGIZE}.  The stringizing operator is @samp{#} and is
6659 found in macros such as this:
6661 @example
6662 #define x(y) #y
6663 @end example
6665 This macro is obsolescent, as current C compilers support the
6666 stringizing operator.  New programs need not use this macro.
6667 @end defmac
6669 @defmac AC_C_FLEXIBLE_ARRAY_MEMBER
6670 @acindex{C_FLEXIBLE_ARRAY_MEMBER}
6671 @cvindex FLEXIBLE_ARRAY_MEMBER
6672 If the C compiler supports flexible array members, define
6673 @code{FLEXIBLE_ARRAY_MEMBER} to nothing; otherwise define it to 1.
6674 That way, a declaration like this:
6676 @example
6677 struct s
6678   @{
6679     size_t n_vals;
6680     double val[FLEXIBLE_ARRAY_MEMBER];
6681   @};
6682 @end example
6684 @noindent
6685 will let applications use the ``struct hack'' even with compilers that
6686 do not support flexible array members.  To allocate and use such an
6687 object, you can use code like this:
6689 @example
6690 size_t i;
6691 size_t n = compute_value_count ();
6692 struct s *p =
6693    malloc (offsetof (struct s, val)
6694            + n * sizeof (double));
6695 p->n_vals = n;
6696 for (i = 0; i < n; i++)
6697   p->val[i] = compute_value (i);
6698 @end example
6699 @end defmac
6701 @defmac AC_C_VARARRAYS
6702 @acindex{C_VARARRAYS}
6703 @cvindex HAVE_C_VARARRAYS
6704 If the C compiler supports variable-length arrays, define
6705 @code{HAVE_C_VARARRAYS}.  A variable-length array is an array of automatic
6706 storage duration whose length is determined at run time, when the array
6707 is declared.
6708 @end defmac
6710 @defmac AC_C_TYPEOF
6711 @acindex{C_TYPEOF}
6712 @cvindex HAVE_TYPEOF
6713 @cvindex typeof
6714 If the C compiler supports @acronym{GCC}'s @code{typeof} syntax either
6715 directly or
6716 through a different spelling of the keyword (e.g., @code{__typeof__}),
6717 define @code{HAVE_TYPEOF}.  If the support is available only through a
6718 different spelling, define @code{typeof} to that spelling.
6719 @end defmac
6721 @defmac AC_C_PROTOTYPES
6722 @acindex{C_PROTOTYPES}
6723 @cvindex PROTOTYPES
6724 @cvindex __PROTOTYPES
6725 @cvindex PARAMS
6726 If function prototypes are understood by the compiler (as determined by
6727 @code{AC_PROG_CC}), define @code{PROTOTYPES} and @code{__PROTOTYPES}.
6728 Defining @code{__PROTOTYPES} is for the benefit of
6729 header files that cannot use macros that infringe on user name space.
6731 This macro is obsolescent, as current C compilers support prototypes.
6732 New programs need not use this macro.
6733 @end defmac
6735 @defmac AC_PROG_GCC_TRADITIONAL
6736 @acindex{PROG_GCC_TRADITIONAL}
6737 @ovindex CC
6738 Add @option{-traditional} to output variable @code{CC} if using the
6739 @acronym{GNU} C compiler and @code{ioctl} does not work properly without
6740 @option{-traditional}.  That usually happens when the fixed header files
6741 have not been installed on an old system.
6743 This macro is obsolescent, since current versions of the @acronym{GNU} C
6744 compiler fix the header files automatically when installed.
6745 @end defmac
6748 @node C++ Compiler
6749 @subsection C++ Compiler Characteristics
6752 @defmac AC_PROG_CXX (@ovar{compiler-search-list})
6753 @acindex{PROG_CXX}
6754 @ovindex CXX
6755 @ovindex CXXFLAGS
6756 Determine a C++ compiler to use.  Check whether the environment variable
6757 @code{CXX} or @code{CCC} (in that order) is set; if so, then set output
6758 variable @code{CXX} to its value.
6760 Otherwise, if the macro is invoked without an argument, then search for
6761 a C++ compiler under the likely names (first @code{g++} and @code{c++}
6762 then other names).  If none of those checks succeed, then as a last
6763 resort set @code{CXX} to @code{g++}.
6765 This macro may, however, be invoked with an optional first argument
6766 which, if specified, must be a blank-separated list of C++ compilers to
6767 search for.  This just gives the user an opportunity to specify an
6768 alternative search list for the C++ compiler.  For example, if you
6769 didn't like the default order, then you could invoke @code{AC_PROG_CXX}
6770 like this:
6772 @example
6773 AC_PROG_CXX([gcc cl KCC CC cxx cc++ xlC aCC c++ g++])
6774 @end example
6776 If using the @acronym{GNU} C++ compiler, set shell variable @code{GXX} to
6777 @samp{yes}.  If output variable @code{CXXFLAGS} was not already set, set
6778 it to @option{-g -O2} for the @acronym{GNU} C++ compiler (@option{-O2} on
6779 systems where G++ does not accept @option{-g}), or @option{-g} for other
6780 compilers.
6781 @end defmac
6783 @defmac AC_PROG_CXXCPP
6784 @acindex{PROG_CXXCPP}
6785 @ovindex CXXCPP
6786 Set output variable @code{CXXCPP} to a command that runs the C++
6787 preprocessor.  If @samp{$CXX -E} doesn't work, @file{/lib/cpp} is used.
6788 It is portable to run @code{CXXCPP} only on files with a @file{.c},
6789 @file{.C}, @file{.cc}, or @file{.cpp} extension.
6791 Some preprocessors don't indicate missing include files by the error
6792 status.  For such preprocessors an internal variable is set that causes
6793 other macros to check the standard error from the preprocessor and
6794 consider the test failed if any warnings have been reported.  However,
6795 it is not known whether such broken preprocessors exist for C++.
6796 @end defmac
6798 @defmac AC_PROG_CXX_C_O
6799 @acindex{PROG_CXX_C_O}
6800 @cvindex CXX_NO_MINUS_C_MINUS_O
6801 Test whether the C++ compiler accepts the options @option{-c} and
6802 @option{-o} simultaneously, and define @code{CXX_NO_MINUS_C_MINUS_O},
6803 if it does not.
6804 @end defmac
6807 @node Objective C Compiler
6808 @subsection Objective C Compiler Characteristics
6811 @defmac AC_PROG_OBJC (@ovar{compiler-search-list})
6812 @acindex{PROG_OBJC}
6813 @ovindex OBJC
6814 @ovindex OBJCFLAGS
6815 Determine an Objective C compiler to use.  If @code{OBJC} is not already
6816 set in the environment, check for Objective C compilers.  Set output
6817 variable @code{OBJC} to the name of the compiler found.
6819 This macro may, however, be invoked with an optional first argument
6820 which, if specified, must be a blank-separated list of Objective C compilers to
6821 search for.  This just gives the user an opportunity to specify an
6822 alternative search list for the Objective C compiler.  For example, if you
6823 didn't like the default order, then you could invoke @code{AC_PROG_OBJC}
6824 like this:
6826 @example
6827 AC_PROG_OBJC([gcc objcc objc])
6828 @end example
6830 If using the @acronym{GNU} Objective C compiler, set shell variable
6831 @code{GOBJC} to @samp{yes}.  If output variable @code{OBJCFLAGS} was not
6832 already set, set it to @option{-g -O2} for the @acronym{GNU} Objective C
6833 compiler (@option{-O2} on systems where @command{gcc} does not accept
6834 @option{-g}), or @option{-g} for other compilers.
6835 @end defmac
6837 @defmac AC_PROG_OBJCPP
6838 @acindex{PROG_OBJCPP}
6839 @ovindex OBJCPP
6840 Set output variable @code{OBJCPP} to a command that runs the Objective C
6841 preprocessor.  If @samp{$OBJC -E} doesn't work, @file{/lib/cpp} is used.
6842 @end defmac
6845 @node Erlang Compiler and Interpreter
6846 @subsection Erlang Compiler and Interpreter Characteristics
6847 @cindex Erlang
6849 Autoconf defines the following macros for determining paths to the essential
6850 Erlang/OTP programs:
6852 @defmac AC_ERLANG_PATH_ERLC (@ovar{value-if-not-found}, @ovar{path})
6853 @acindex{ERLANG_PATH_ERLC}
6854 @ovindex ERLC
6855 @ovindex ERLCFLAGS
6856 Determine an Erlang compiler to use.  If @code{ERLC} is not already set in the
6857 environment, check for @command{erlc}.  Set output variable @code{ERLC} to the
6858 complete path of the compiler command found.  In addition, if @code{ERLCFLAGS}
6859 is not set in the environment, set it to an empty value.
6861 The two optional arguments have the same meaning as the two last arguments of
6862 macro @code{AC_PROG_PATH} for looking for the @command{erlc} program.  For
6863 example, to look for @command{erlc} only in the @file{/usr/lib/erlang/bin}
6864 directory:
6866 @example
6867 AC_ERLANG_PATH_ERLC([not found], [/usr/lib/erlang/bin])
6868 @end example
6869 @end defmac
6871 @defmac AC_ERLANG_NEED_ERLC (@ovar{path})
6872 @acindex{ERLANG_NEED_ERLC}
6873 A simplified variant of the @code{AC_ERLANG_PATH_ERLC} macro, that prints an
6874 error message and exits the @command{configure} script if the @command{erlc}
6875 program is not found.
6876 @end defmac
6878 @defmac AC_ERLANG_PATH_ERL (@ovar{value-if-not-found}, @ovar{path})
6879 @acindex{ERLANG_PATH_ERL}
6880 @ovindex ERL
6881 Determine an Erlang interpreter to use.  If @code{ERL} is not already set in the
6882 environment, check for @command{erl}.  Set output variable @code{ERL} to the
6883 complete path of the interpreter command found.
6885 The two optional arguments have the same meaning as the two last arguments of
6886 macro @code{AC_PROG_PATH} for looking for the @command{erl} program.  For
6887 example, to look for @command{erl} only in the @file{/usr/lib/erlang/bin}
6888 directory:
6890 @example
6891 AC_ERLANG_PATH_ERL([not found], [/usr/lib/erlang/bin])
6892 @end example
6893 @end defmac
6895 @defmac AC_ERLANG_NEED_ERL (@ovar{path})
6896 @acindex{ERLANG_NEED_ERL}
6897 A simplified variant of the @code{AC_ERLANG_PATH_ERL} macro, that prints an
6898 error message and exits the @command{configure} script if the @command{erl}
6899 program is not found.
6900 @end defmac
6903 @node Fortran Compiler
6904 @subsection Fortran Compiler Characteristics
6905 @cindex Fortran
6906 @cindex F77
6908 The Autoconf Fortran support is divided into two categories: legacy
6909 Fortran 77 macros (@code{F77}), and modern Fortran macros (@code{FC}).
6910 The former are intended for traditional Fortran 77 code, and have output
6911 variables like @code{F77}, @code{FFLAGS}, and @code{FLIBS}.  The latter
6912 are for newer programs that can (or must) compile under the newer
6913 Fortran standards, and have output variables like @code{FC},
6914 @code{FCFLAGS}, and @code{FCLIBS}.
6916 Except for two new macros @code{AC_FC_SRCEXT} and
6917 @code{AC_FC_FREEFORM} (see below), the @code{FC} and @code{F77} macros
6918 behave almost identically, and so they are documented together in this
6919 section.
6922 @defmac AC_PROG_F77 (@ovar{compiler-search-list})
6923 @acindex{PROG_F77}
6924 @ovindex F77
6925 @ovindex FFLAGS
6926 Determine a Fortran 77 compiler to use.  If @code{F77} is not already
6927 set in the environment, then check for @code{g77} and @code{f77}, and
6928 then some other names.  Set the output variable @code{F77} to the name
6929 of the compiler found.
6931 This macro may, however, be invoked with an optional first argument
6932 which, if specified, must be a blank-separated list of Fortran 77
6933 compilers to search for.  This just gives the user an opportunity to
6934 specify an alternative search list for the Fortran 77 compiler.  For
6935 example, if you didn't like the default order, then you could invoke
6936 @code{AC_PROG_F77} like this:
6938 @example
6939 AC_PROG_F77([fl32 f77 fort77 xlf g77 f90 xlf90])
6940 @end example
6942 If using @code{g77} (the @acronym{GNU} Fortran 77 compiler), then
6943 set the shell variable @code{G77} to @samp{yes}.
6944 If the output variable @code{FFLAGS} was not already set in the
6945 environment, then set it to @option{-g -02} for @code{g77} (or @option{-O2}
6946 where @code{g77} does not accept @option{-g}).  Otherwise, set
6947 @code{FFLAGS} to @option{-g} for all other Fortran 77 compilers.
6948 @end defmac
6950 @defmac AC_PROG_FC (@ovar{compiler-search-list}, @ovar{dialect})
6951 @acindex{PROG_FC}
6952 @ovindex FC
6953 @ovindex FCFLAGS
6954 Determine a Fortran compiler to use.  If @code{FC} is not already set in
6955 the environment, then @code{dialect} is a hint to indicate what Fortran
6956 dialect to search for; the default is to search for the newest available
6957 dialect.  Set the output variable @code{FC} to the name of the compiler
6958 found.
6960 By default, newer dialects are preferred over older dialects, but if
6961 @code{dialect} is specified then older dialects are preferred starting
6962 with the specified dialect.  @code{dialect} can currently be one of
6963 Fortran 77, Fortran 90, or Fortran 95.  However, this is only a hint of
6964 which compiler @emph{name} to prefer (e.g., @code{f90} or @code{f95}),
6965 and no attempt is made to guarantee that a particular language standard
6966 is actually supported.  Thus, it is preferable that you avoid the
6967 @code{dialect} option, and use AC_PROG_FC only for code compatible with
6968 the latest Fortran standard.
6970 This macro may, alternatively, be invoked with an optional first argument
6971 which, if specified, must be a blank-separated list of Fortran
6972 compilers to search for, just as in @code{AC_PROG_F77}.
6974 If the output variable @code{FCFLAGS} was not already set in the
6975 environment, then set it to @option{-g -02} for @acronym{GNU} @code{g77} (or
6976 @option{-O2} where @code{g77} does not accept @option{-g}).  Otherwise,
6977 set @code{FCFLAGS} to @option{-g} for all other Fortran compilers.
6978 @end defmac
6980 @defmac AC_PROG_F77_C_O
6981 @defmacx AC_PROG_FC_C_O
6982 @acindex{PROG_F77_C_O}
6983 @acindex{PROG_FC_C_O}
6984 @cvindex F77_NO_MINUS_C_MINUS_O
6985 @cvindex FC_NO_MINUS_C_MINUS_O
6986 Test whether the Fortran compiler accepts the options @option{-c} and
6987 @option{-o} simultaneously, and define @code{F77_NO_MINUS_C_MINUS_O} or
6988 @code{FC_NO_MINUS_C_MINUS_O}, respectively, if it does not.
6989 @end defmac
6991 The following macros check for Fortran compiler characteristics.
6992 To check for characteristics not listed here, use
6993 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
6994 @code{AC_RUN_IFELSE} (@pxref{Runtime}), making sure to first set the
6995 current language to Fortran 77 or Fortran via @code{AC_LANG([Fortran 77])}
6996 or @code{AC_LANG(Fortran)} (@pxref{Language Choice}).
6999 @defmac AC_F77_LIBRARY_LDFLAGS
7000 @defmacx AC_FC_LIBRARY_LDFLAGS
7001 @acindex{F77_LIBRARY_LDFLAGS}
7002 @ovindex FLIBS
7003 @acindex{FC_LIBRARY_LDFLAGS}
7004 @ovindex FCLIBS
7005 Determine the linker flags (e.g., @option{-L} and @option{-l}) for the
7006 @dfn{Fortran intrinsic and runtime libraries} that are required to
7007 successfully link a Fortran program or shared library.  The output
7008 variable @code{FLIBS} or @code{FCLIBS} is set to these flags (which
7009 should be included after @code{LIBS} when linking).
7011 This macro is intended to be used in those situations when it is
7012 necessary to mix, e.g., C++ and Fortran source code in a single
7013 program or shared library (@pxref{Mixing Fortran 77 With C and C++, , ,
7014 automake, @acronym{GNU} Automake}).
7016 For example, if object files from a C++ and Fortran compiler must be
7017 linked together, then the C++ compiler/linker must be used for linking
7018 (since special C++-ish things need to happen at link time like calling
7019 global constructors, instantiating templates, enabling exception
7020 support, etc.).
7022 However, the Fortran intrinsic and runtime libraries must be linked in
7023 as well, but the C++ compiler/linker doesn't know by default how to add
7024 these Fortran 77 libraries.  Hence, this macro was created to determine
7025 these Fortran libraries.
7027 The macros @code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or
7028 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} are probably also necessary to
7029 link C/C++ with Fortran; see below.
7030 @end defmac
7032 @defmac AC_F77_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
7033 @defmacx AC_FC_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
7034 @acindex{F77_DUMMY_MAIN}
7035 @cvindex F77_DUMMY_MAIN
7036 With many compilers, the Fortran libraries detected by
7037 @code{AC_F77_LIBRARY_LDFLAGS} or @code{AC_FC_LIBRARY_LDFLAGS} provide
7038 their own @code{main} entry function that initializes things like
7039 Fortran I/O, and which then calls a user-provided entry function named
7040 (say) @code{MAIN__} to run the user's program.  The
7041 @code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or
7042 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros figure out how to deal with
7043 this interaction.
7045 When using Fortran for purely numerical functions (no I/O, etc.)@: often
7046 one prefers to provide one's own @code{main} and skip the Fortran
7047 library initializations.  In this case, however, one may still need to
7048 provide a dummy @code{MAIN__} routine in order to prevent linking errors
7049 on some systems.  @code{AC_F77_DUMMY_MAIN} or @code{AC_FC_DUMMY_MAIN}
7050 detects whether any such routine is @emph{required} for linking, and
7051 what its name is; the shell variable @code{F77_DUMMY_MAIN} or
7052 @code{FC_DUMMY_MAIN} holds this name, @code{unknown} when no solution
7053 was found, and @code{none} when no such dummy main is needed.
7055 By default, @var{action-if-found} defines @code{F77_DUMMY_MAIN} or
7056 @code{FC_DUMMY_MAIN} to the name of this routine (e.g., @code{MAIN__})
7057 @emph{if} it is required.  @var{action-if-not-found} defaults to
7058 exiting with an error.
7060 In order to link with Fortran routines, the user's C/C++ program should
7061 then include the following code to define the dummy main if it is
7062 needed:
7064 @example
7065 #ifdef F77_DUMMY_MAIN
7066 #  ifdef __cplusplus
7067      extern "C"
7068 #  endif
7069    int F77_DUMMY_MAIN() @{ return 1; @}
7070 #endif
7071 @end example
7073 (Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
7075 Note that this macro is called automatically from @code{AC_F77_WRAPPERS}
7076 or @code{AC_FC_WRAPPERS}; there is generally no need to call it
7077 explicitly unless one wants to change the default actions.
7078 @end defmac
7080 @defmac AC_F77_MAIN
7081 @defmacx AC_FC_MAIN
7082 @acindex{F77_MAIN}
7083 @cvindex F77_MAIN
7084 @acindex{FC_MAIN}
7085 @cvindex FC_MAIN
7086 As discussed above, many Fortran libraries allow you to provide an entry
7087 point called (say) @code{MAIN__} instead of the usual @code{main}, which
7088 is then called by a @code{main} function in the Fortran libraries that
7089 initializes things like Fortran I/O@.  The
7090 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros detect whether it is
7091 @emph{possible} to utilize such an alternate main function, and defines
7092 @code{F77_MAIN} and @code{FC_MAIN} to the name of the function.  (If no
7093 alternate main function name is found, @code{F77_MAIN} and @code{FC_MAIN} are
7094 simply defined to @code{main}.)
7096 Thus, when calling Fortran routines from C that perform things like I/O,
7097 one should use this macro and declare the "main" function like so:
7099 @example
7100 #ifdef __cplusplus
7101   extern "C"
7102 #endif
7103 int F77_MAIN(int argc, char *argv[]);
7104 @end example
7106 (Again, replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
7107 @end defmac
7109 @defmac AC_F77_WRAPPERS
7110 @defmacx AC_FC_WRAPPERS
7111 @acindex{F77_WRAPPERS}
7112 @cvindex F77_FUNC
7113 @cvindex F77_FUNC_
7114 @acindex{FC_WRAPPERS}
7115 @cvindex FC_FUNC
7116 @cvindex FC_FUNC_
7117 Defines C macros @code{F77_FUNC (name, NAME)}, @code{FC_FUNC (name, NAME)},
7118 @code{F77_FUNC_(name, NAME)}, and @code{FC_FUNC_(name, NAME)} to properly
7119 mangle the names of C/C++ identifiers, and identifiers with underscores,
7120 respectively, so that they match the name-mangling scheme used by the
7121 Fortran compiler.
7123 Fortran is case-insensitive, and in order to achieve this the Fortran
7124 compiler converts all identifiers into a canonical case and format.  To
7125 call a Fortran subroutine from C or to write a C function that is
7126 callable from Fortran, the C program must explicitly use identifiers in
7127 the format expected by the Fortran compiler.  In order to do this, one
7128 simply wraps all C identifiers in one of the macros provided by
7129 @code{AC_F77_WRAPPERS} or @code{AC_FC_WRAPPERS}.  For example, suppose
7130 you have the following Fortran 77 subroutine:
7132 @example
7133       subroutine foobar (x, y)
7134       double precision x, y
7135       y = 3.14159 * x
7136       return
7137       end
7138 @end example
7140 You would then declare its prototype in C or C++ as:
7142 @example
7143 #define FOOBAR_F77 F77_FUNC (foobar, FOOBAR)
7144 #ifdef __cplusplus
7145 extern "C"  /* prevent C++ name mangling */
7146 #endif
7147 void FOOBAR_F77(double *x, double *y);
7148 @end example
7150 Note that we pass both the lowercase and uppercase versions of the
7151 function name to @code{F77_FUNC} so that it can select the right one.
7152 Note also that all parameters to Fortran 77 routines are passed as
7153 pointers (@pxref{Mixing Fortran 77 With C and C++, , , automake, @acronym{GNU}
7154 Automake}).
7156 (Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
7158 Although Autoconf tries to be intelligent about detecting the
7159 name-mangling scheme of the Fortran compiler, there may be Fortran
7160 compilers that it doesn't support yet.  In this case, the above code
7161 generates a compile-time error, but some other behavior
7162 (e.g., disabling Fortran-related features) can be induced by checking
7163 whether @code{F77_FUNC} or @code{FC_FUNC} is defined.
7165 Now, to call that routine from a C program, we would do something like:
7167 @example
7169     double x = 2.7183, y;
7170     FOOBAR_F77 (&x, &y);
7172 @end example
7174 If the Fortran identifier contains an underscore (e.g., @code{foo_bar}),
7175 you should use @code{F77_FUNC_} or @code{FC_FUNC_} instead of
7176 @code{F77_FUNC} or @code{FC_FUNC} (with the same arguments).  This is
7177 because some Fortran compilers mangle names differently if they contain
7178 an underscore.
7179 @end defmac
7181 @defmac AC_F77_FUNC (@var{name}, @ovar{shellvar})
7182 @defmacx AC_FC_FUNC (@var{name}, @ovar{shellvar})
7183 @acindex{F77_FUNC}
7184 @acindex{FC_FUNC}
7185 Given an identifier @var{name}, set the shell variable @var{shellvar} to
7186 hold the mangled version @var{name} according to the rules of the
7187 Fortran linker (see also @code{AC_F77_WRAPPERS} or
7188 @code{AC_FC_WRAPPERS}).  @var{shellvar} is optional; if it is not
7189 supplied, the shell variable is simply @var{name}.  The purpose of
7190 this macro is to give the caller a way to access the name-mangling
7191 information other than through the C preprocessor as above, for example,
7192 to call Fortran routines from some language other than C/C++.
7193 @end defmac
7195 @defmac AC_FC_SRCEXT (@var{ext}, @ovar{action-if-success}, @ovar{action-if-failure})
7196 @acindex{FC_SRCEXT}
7197 By default, the @code{FC} macros perform their tests using a @file{.f}
7198 extension for source-code files.  Some compilers, however, only enable
7199 newer language features for appropriately named files, e.g., Fortran 90
7200 features only for @file{.f90} files.  On the other hand, some other
7201 compilers expect all source files to end in @file{.f} and require
7202 special flags to support other file name extensions.  The
7203 @code{AC_FC_SRCEXT} macro deals with both of these issues.
7205 The @code{AC_FC_SRCEXT} tries to get the @code{FC} compiler to accept files
7206 ending with the extension .@var{ext} (i.e., @var{ext} does @emph{not}
7207 contain the dot).  If any special compiler flags are needed for this, it
7208 stores them in the output variable @code{FCFLAGS_}@var{ext}.  This
7209 extension and these flags are then used for all subsequent @code{FC} tests
7210 (until @code{AC_FC_SRCEXT} is called again).
7212 For example, you would use @code{AC_FC_SRCEXT(f90)} to employ the
7213 @file{.f90} extension in future tests, and it would set a
7214 @code{FCFLAGS_f90} output variable with any extra flags that are needed
7215 to compile such files.
7217 The @code{FCFLAGS_}@var{ext} can @emph{not} be simply absorbed into
7218 @code{FCFLAGS}, for two reasons based on the limitations of some
7219 compilers.  First, only one @code{FCFLAGS_}@var{ext} can be used at a
7220 time, so files with different extensions must be compiled separately.
7221 Second, @code{FCFLAGS_}@var{ext} must appear @emph{immediately} before
7222 the source-code file name when compiling.  So, continuing the example
7223 above, you might compile a @file{foo.f90} file in your makefile with the
7224 command:
7226 @example
7227 foo.o: foo.f90
7228      $(FC) -c $(FCFLAGS) $(FCFLAGS_f90) '$(srcdir)/foo.f90'
7229 @end example
7231 If @code{AC_FC_SRCEXT} succeeds in compiling files with the @var{ext}
7232 extension, it calls @var{action-if-success} (defaults to nothing).  If
7233 it fails, and cannot find a way to make the @code{FC} compiler accept such
7234 files, it calls @var{action-if-failure} (defaults to exiting with an
7235 error message).
7237 @end defmac
7239 @defmac AC_FC_FREEFORM (@ovar{action-if-success}, @ovar{action-if-failure})
7240 @acindex{FC_FREEFORM}
7242 The @code{AC_FC_FREEFORM} tries to ensure that the Fortran compiler
7243 (@code{$FC}) allows free-format source code (as opposed to the older
7244 fixed-format style from Fortran 77).  If necessary, it may add some
7245 additional flags to @code{FCFLAGS}.
7247 This macro is most important if you are using the default @file{.f}
7248 extension, since many compilers interpret this extension as indicating
7249 fixed-format source unless an additional flag is supplied.  If you
7250 specify a different extension with @code{AC_FC_SRCEXT}, such as
7251 @file{.f90} or @file{.f95}, then @code{AC_FC_FREEFORM} ordinarily
7252 succeeds without modifying @code{FCFLAGS}.
7254 If @code{AC_FC_FREEFORM} succeeds in compiling free-form source, it
7255 calls @var{action-if-success} (defaults to nothing).  If it fails, it
7256 calls @var{action-if-failure} (defaults to exiting with an error
7257 message).
7258 @end defmac
7260 @node System Services
7261 @section System Services
7263 The following macros check for operating system services or capabilities.
7265 @defmac AC_PATH_X
7266 @acindex{PATH_X}
7267 @evindex XMKMF
7268 @cindex X Window System
7269 Try to locate the X Window System include files and libraries.  If the
7270 user gave the command line options @option{--x-includes=@var{dir}} and
7271 @option{--x-libraries=@var{dir}}, use those directories.
7273 If either or both were not given, get the missing values by running
7274 @code{xmkmf} (or an executable pointed to by the @code{XMKMF}
7275 environment variable) on a trivial @file{Imakefile} and examining the
7276 makefile that it produces.  Setting @code{XMKMF} to @samp{false}
7277 disables this method.
7279 If this method fails to find the X Window System, @command{configure}
7280 looks for the files in several directories where they often reside.
7281 If either method is successful, set the shell variables
7282 @code{x_includes} and @code{x_libraries} to their locations, unless they
7283 are in directories the compiler searches by default.
7285 If both methods fail, or the user gave the command line option
7286 @option{--without-x}, set the shell variable @code{no_x} to @samp{yes};
7287 otherwise set it to the empty string.
7288 @end defmac
7290 @defmac AC_PATH_XTRA
7291 @acindex{PATH_XTRA}
7292 @ovindex X_CFLAGS
7293 @ovindex X_LIBS
7294 @ovindex X_EXTRA_LIBS
7295 @ovindex X_PRE_LIBS
7296 @cvindex X_DISPLAY_MISSING
7297 An enhanced version of @code{AC_PATH_X}.  It adds the C compiler flags
7298 that X needs to output variable @code{X_CFLAGS}, and the X linker flags
7299 to @code{X_LIBS}.  Define @code{X_DISPLAY_MISSING} if X is not
7300 available.
7302 This macro also checks for special libraries that some systems need in
7303 order to compile X programs.  It adds any that the system needs to
7304 output variable @code{X_EXTRA_LIBS}.  And it checks for special X11R6
7305 libraries that need to be linked with before @option{-lX11}, and adds
7306 any found to the output variable @code{X_PRE_LIBS}.
7308 @c This is an incomplete kludge.  Make a real way to do it.
7309 @c If you need to check for other X functions or libraries yourself, then
7310 @c after calling this macro, add the contents of @code{X_EXTRA_LIBS} to
7311 @c @code{LIBS} temporarily, like this: (FIXME - add example)
7312 @end defmac
7314 @defmac AC_SYS_INTERPRETER
7315 @acindex{SYS_INTERPRETER}
7316 Check whether the system supports starting scripts with a line of the
7317 form @samp{#!/bin/sh} to select the interpreter to use for the script.
7318 After running this macro, shell code in @file{configure.ac} can check
7319 the shell variable @code{interpval}; it is set to @samp{yes}
7320 if the system supports @samp{#!}, @samp{no} if not.
7321 @end defmac
7323 @defmac AC_SYS_LARGEFILE
7324 @acindex{SYS_LARGEFILE}
7325 @cvindex _FILE_OFFSET_BITS
7326 @cvindex _LARGE_FILES
7327 @ovindex CC
7328 @cindex Large file support
7329 @cindex LFS
7330 Arrange for
7331 @uref{http://www.unix-systems.org/@/version2/@/whatsnew/@/lfs20mar.html,
7332 large-file support}.  On some hosts, one must use special compiler
7333 options to build programs that can access large files.  Append any such
7334 options to the output variable @code{CC}.  Define
7335 @code{_FILE_OFFSET_BITS} and @code{_LARGE_FILES} if necessary.
7337 Large-file support can be disabled by configuring with the
7338 @option{--disable-largefile} option.
7340 If you use this macro, check that your program works even when
7341 @code{off_t} is wider than @code{long int}, since this is common when
7342 large-file support is enabled.  For example, it is not correct to print
7343 an arbitrary @code{off_t} value @code{X} with @code{printf ("%ld",
7344 (long int) X)}.
7346 The LFS introduced the @code{fseeko} and @code{ftello} functions to
7347 replace their C counterparts @code{fseek} and @code{ftell} that do not
7348 use @code{off_t}.  Take care to use @code{AC_FUNC_FSEEKO} to make their
7349 prototypes available when using them and large-file support is
7350 enabled.
7351 @end defmac
7353 @defmac AC_SYS_LONG_FILE_NAMES
7354 @acindex{SYS_LONG_FILE_NAMES}
7355 @cvindex HAVE_LONG_FILE_NAMES
7356 If the system supports file names longer than 14 characters, define
7357 @code{HAVE_LONG_FILE_NAMES}.
7358 @end defmac
7360 @defmac AC_SYS_POSIX_TERMIOS
7361 @acindex{SYS_POSIX_TERMIOS}
7362 @cindex Posix termios headers
7363 @cindex termios Posix headers
7364 Check to see if the Posix termios headers and functions are available on the
7365 system.  If so, set the shell variable @code{ac_cv_sys_posix_termios} to
7366 @samp{yes}.  If not, set the variable to @samp{no}.
7367 @end defmac
7369 @node Posix Variants
7370 @section Posix Variants
7372 The following macros check for certain operating systems that need
7373 special treatment for some programs, due to exceptional oddities in
7374 their header files or libraries.  These macros are warts; they will be
7375 replaced by a more systematic approach, based on the functions they make
7376 available or the environments they provide.
7378 @defmac AC_AIX
7379 @acindex{AIX}
7380 @cvindex _ALL_SOURCE
7381 If on @acronym{AIX}, define @code{_ALL_SOURCE}.
7382 Allows the use of some @acronym{BSD}
7383 functions.  Should be called before any macros that run the C compiler.
7384 @end defmac
7386 @defmac AC_GNU_SOURCE
7387 @acindex{GNU_SOURCE}
7388 @cvindex _GNU_SOURCE
7389 If using the @acronym{GNU} C library, define @code{_GNU_SOURCE}.
7390 Allows the use of some @acronym{GNU} functions.  Should be called
7391 before any macros that run the C compiler.
7392 @end defmac
7394 @defmac AC_ISC_POSIX
7395 @acindex{ISC_POSIX}
7396 @ovindex LIBS
7397 For @sc{interactive} Systems Corporation Unix, add @option{-lcposix} to output
7398 variable @code{LIBS} if necessary for Posix facilities.  Call this
7399 after @code{AC_PROG_CC} and before any other macros that use Posix
7400 interfaces.
7402 This macro is obsolescent, as @sc{interactive} Unix is obsolete, and Sun
7403 dropped support for it on 2006-07-23.  New programs need not use this
7404 macro.
7405 @end defmac
7407 @defmac AC_MINIX
7408 @acindex{MINIX}
7409 @cvindex _MINIX
7410 @cvindex _POSIX_SOURCE
7411 @cvindex _POSIX_1_SOURCE
7412 If on Minix, define @code{_MINIX} and @code{_POSIX_SOURCE} and define
7413 @code{_POSIX_1_SOURCE} to be 2.  This allows the use of Posix
7414 facilities.  Should be called before any macros that run the C compiler.
7415 @end defmac
7417 @defmac AC_USE_SYSTEM_EXTENSIONS
7418 @acindex{USE_SYSTEM_EXTENSIONS}
7419 @cvindex _ALL_SOURCE
7420 @cvindex _GNU_SOURCE
7421 @cvindex _MINIX
7422 @cvindex _POSIX_1_SOURCE
7423 @cvindex _POSIX_PTHREAD_SEMANTICS
7424 @cvindex _POSIX_SOURCE
7425 @cvindex _TANDEM_SOURCE
7426 @cvindex __EXTENSIONS__
7427 If possible, enable extensions to Posix on hosts that normally disable
7428 the extensions, typically due to standards-conformance namespace issues.
7429 This may involve defining @code{__EXTENSIONS__} and
7430 @code{_POSIX_PTHREAD_SEMANTICS}, which are macros used by Solaris.
7431 It also defines @code{_TANDEM_SOURCE} for the @acronym{HP} NonStop platform.
7432 This macro also has the combined effects of @code{AC_GNU_SOURCE},
7433 @code{AC_AIX}, and @code{AC_MINIX}.
7434 @end defmac
7437 @node Erlang Libraries
7438 @section Erlang Libraries
7439 @cindex Erlang, Library, checking
7441 The following macros check for an installation of Erlang/OTP, and for the
7442 presence of certain Erlang libraries.  All those macros require the
7443 configuration of an Erlang interpreter and an Erlang compiler
7444 (@pxref{Erlang Compiler and Interpreter}).
7446 @defmac AC_ERLANG_SUBST_ROOT_DIR
7447 @acindex{ERLANG_SUBST_ROOT_DIR}
7448 @ovindex ERLANG_ROOT_DIR
7450 Set the output variable @code{ERLANG_ROOT_DIR} to the path to the base directory
7451 in which Erlang/OTP is installed (as returned by Erlang's @code{code:root_dir/0}
7452 function).  The result of this test is cached if caching is enabled when running
7453 @command{configure}.
7454 @end defmac
7456 @defmac AC_ERLANG_SUBST_LIB_DIR
7457 @acindex{ERLANG_SUBST_LIB_DIR}
7458 @ovindex ERLANG_LIB_DIR
7460 Set the output variable @code{ERLANG_LIB_DIR} to the path of the library
7461 directory of Erlang/OTP (as returned by Erlang's
7462 @code{code:lib_dir/0} function), which subdirectories each contain an installed
7463 Erlang/OTP library.  The result of this test is cached if caching is enabled
7464 when running @command{configure}.
7465 @end defmac
7467 @defmac AC_ERLANG_CHECK_LIB (@var{library}, @ovar{action-if-found}, @ovar{action-if-not-found})
7468 @acindex{ERLANG_CHECK_LIB}
7469 @ovindex ERLANG_LIB_DIR_@var{library}
7470 @ovindex ERLANG_LIB_VER_@var{library}
7472 Test whether the Erlang/OTP library @var{library} is installed by
7473 calling Erlang's @code{code:lib_dir/1} function.  The result of this
7474 test is cached if caching is enabled when running @command{configure}.
7475 @var{action-if-found} is a list of shell commands to run if the library
7476 is installed; @var{action-if-not-found} is a list of shell commands to
7477 run if it is not.  Additionally, if the library is installed, the output
7478 variable @samp{ERLANG_LIB_DIR_@var{library}} is set to the path to the
7479 library installation directory, and the output variable
7480 @samp{ERLANG_LIB_VER_@var{library}} is set to the version number that is
7481 part of the subdirectory name, if it is in the standard form
7482 (@code{@var{library}-@var{version}}).  If the directory name does not
7483 have a version part, @samp{ERLANG_LIB_VER_@var{library}} is set to the
7484 empty string.  If the library is not installed,
7485 @samp{ERLANG_LIB_DIR_@var{library}} and
7486 @samp{ERLANG_LIB_VER_@var{library}} are set to @code{"not found"}.  For
7487 example, to check if library @code{stdlib} is installed:
7489 @example
7490 AC_ERLANG_CHECK_LIB([stdlib],
7491   [echo "stdlib version \"$ERLANG_LIB_VER_stdlib\""
7492    echo "is installed in \"$ERLANG_LIB_DIR_stdlib\""],
7493   [AC_MSG_ERROR([stdlib was not found!])])
7494 @end example
7495 @end defmac
7497 In addition to the above macros, which test installed Erlang libraries, the
7498 following macros determine the paths to the directories into which newly built
7499 Erlang libraries are to be installed:
7501 @defmac AC_ERLANG_SUBST_INSTALL_LIB_DIR
7502 @acindex{ERLANG_SUBST_INSTALL_LIB_DIR}
7503 @ovindex ERLANG_INSTALL_LIB_DIR
7505 Set the @code{ERLANG_INSTALL_LIB_DIR} output variable to the directory into
7506 which every built Erlang library should be installed in a separate subdirectory.
7507 If this variable is not set in the environment when @command{configure} runs,
7508 its default value is @code{$ERLANG_LIB_DIR}, which value is set by the
7509 @code{AC_ERLANG_SUBST_LIB_DIR} macro.
7510 @end defmac
7512 @defmac AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR (@var{library}, @var{version})
7513 @acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR}
7514 @ovindex ERLANG_INSTALL_LIB_DIR_@var{library}
7516 Set the @samp{ERLANG_INSTALL_LIB_DIR_@var{library}} output variable to the
7517 directory into which the built Erlang library @var{library} version
7518 @var{version} should be installed.  If this variable is not set in the
7519 environment when @command{configure} runs, its default value is
7520 @samp{$ERLANG_INSTALL_LIB_DIR/@var{library}-@var{version}}, the value of the
7521 @code{ERLANG_INSTALL_LIB_DIR} variable being set by the
7522 @code{AC_ERLANG_SUBST_INSTALL_LIB_DIR} macro.
7523 @end defmac
7529 @c ========================================================= Writing Tests
7531 @node Writing Tests
7532 @chapter Writing Tests
7534 If the existing feature tests don't do something you need, you have to
7535 write new ones.  These macros are the building blocks.  They provide
7536 ways for other macros to check whether various kinds of features are
7537 available and report the results.
7539 This chapter contains some suggestions and some of the reasons why the
7540 existing tests are written the way they are.  You can also learn a lot
7541 about how to write Autoconf tests by looking at the existing ones.  If
7542 something goes wrong in one or more of the Autoconf tests, this
7543 information can help you understand the assumptions behind them, which
7544 might help you figure out how to best solve the problem.
7546 These macros check the output of the compiler system of the current
7547 language (@pxref{Language Choice}).  They do not cache the results of
7548 their tests for future use (@pxref{Caching Results}), because they don't
7549 know enough about the information they are checking for to generate a
7550 cache variable name.  They also do not print any messages, for the same
7551 reason.  The checks for particular kinds of features call these macros
7552 and do cache their results and print messages about what they're
7553 checking for.
7555 When you write a feature test that could be applicable to more than one
7556 software package, the best thing to do is encapsulate it in a new macro.
7557 @xref{Writing Autoconf Macros}, for how to do that.
7559 @menu
7560 * Language Choice::             Selecting which language to use for testing
7561 * Writing Test Programs::       Forging source files for compilers
7562 * Running the Preprocessor::    Detecting preprocessor symbols
7563 * Running the Compiler::        Detecting language or header features
7564 * Running the Linker::          Detecting library features
7565 * Runtime::                     Testing for runtime features
7566 * Systemology::                 A zoology of operating systems
7567 * Multiple Cases::              Tests for several possible values
7568 @end menu
7570 @node Language Choice
7571 @section Language Choice
7572 @cindex Language
7574 Autoconf-generated @command{configure} scripts check for the C compiler and
7575 its features by default.  Packages that use other programming languages
7576 (maybe more than one, e.g., C and C++) need to test features of the
7577 compilers for the respective languages.  The following macros determine
7578 which programming language is used in the subsequent tests in
7579 @file{configure.ac}.
7581 @defmac AC_LANG (@var{language})
7582 Do compilation tests using the compiler, preprocessor, and file
7583 extensions for the specified @var{language}.
7585 Supported languages are:
7587 @table @samp
7588 @item C
7589 Do compilation tests using @code{CC} and @code{CPP} and use extension
7590 @file{.c} for test programs.  Use compilation flags: @code{CPPFLAGS} with
7591 @code{CPP}, and both @code{CPPFLAGS} and @code{CFLAGS} with @code{CC}.
7593 @item C++
7594 Do compilation tests using @code{CXX} and @code{CXXCPP} and use
7595 extension @file{.C} for test programs.  Use compilation flags:
7596 @code{CPPFLAGS} with @code{CXXCPP}, and both @code{CPPFLAGS} and
7597 @code{CXXFLAGS} with @code{CXX}.
7599 @item Fortran 77
7600 Do compilation tests using @code{F77} and use extension @file{.f} for
7601 test programs.  Use compilation flags: @code{FFLAGS}.
7603 @item Fortran
7604 Do compilation tests using @code{FC} and use extension @file{.f} (or
7605 whatever has been set by @code{AC_FC_SRCEXT}) for test programs.  Use
7606 compilation flags: @code{FCFLAGS}.
7608 @item Erlang
7609 @ovindex ERLC
7610 @ovindex ERL
7611 @ovindex ERLCFLAGS
7612 Compile and execute tests using @code{ERLC} and @code{ERL} and use extension
7613 @file{.erl} for test Erlang modules.  Use compilation flags: @code{ERLCFLAGS}.
7615 @item Objective C
7616 Do compilation tests using @code{OBJC} and @code{OBJCPP} and use
7617 extension @file{.m} for test programs.  Use compilation flags:
7618 @code{CPPFLAGS} with @code{OBJCPP}, and both @code{CPPFLAGS} and
7619 @code{OBJCFLAGS} with @code{OBJC}.
7620 @end table
7621 @end defmac
7623 @defmac AC_LANG_PUSH (@var{language})
7624 @acindex{LANG_PUSH}
7625 Remember the current language (as set by @code{AC_LANG}) on a stack, and
7626 then select the @var{language}.  Use this macro and @code{AC_LANG_POP}
7627 in macros that need to temporarily switch to a particular language.
7628 @end defmac
7630 @defmac AC_LANG_POP (@ovar{language})
7631 @acindex{LANG_POP}
7632 Select the language that is saved on the top of the stack, as set by
7633 @code{AC_LANG_PUSH}, and remove it from the stack.
7635 If given, @var{language} specifies the language we just @emph{quit}.  It
7636 is a good idea to specify it when it's known (which should be the
7637 case@dots{}), since Autoconf detects inconsistencies.
7639 @example
7640 AC_LANG_PUSH([Fortran 77])
7641 # Perform some tests on Fortran 77.
7642 # @dots{}
7643 AC_LANG_POP([Fortran 77])
7644 @end example
7645 @end defmac
7647 @defmac AC_LANG_ASSERT (@var{language})
7648 @acindex{LANG_ASSERT} Check statically that the current language is
7649 @var{language}.  You should use this in your language specific macros
7650 to avoid that they be called with an inappropriate language.
7652 This macro runs only at @command{autoconf} time, and incurs no cost at
7653 @command{configure} time.  Sadly enough and because Autoconf is a two
7654 layer language @footnote{Because M4 is not aware of Sh code,
7655 especially conditionals, some optimizations that look nice statically
7656 may produce incorrect results at runtime.}, the macros
7657 @code{AC_LANG_PUSH} and @code{AC_LANG_POP} cannot be ``optimizing'',
7658 therefore as much as possible you ought to avoid using them to wrap
7659 your code, rather, require from the user to run the macro with a
7660 correct current language, and check it with @code{AC_LANG_ASSERT}.
7661 And anyway, that may help the user understand she is running a Fortran
7662 macro while expecting a result about her Fortran 77 compiler@dots{}
7663 @end defmac
7666 @defmac AC_REQUIRE_CPP
7667 @acindex{REQUIRE_CPP}
7668 Ensure that whichever preprocessor would currently be used for tests has
7669 been found.  Calls @code{AC_REQUIRE} (@pxref{Prerequisite Macros}) with an
7670 argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP},
7671 depending on which language is current.
7672 @end defmac
7675 @node Writing Test Programs
7676 @section Writing Test Programs
7678 Autoconf tests follow a common scheme: feed some program with some
7679 input, and most of the time, feed a compiler with some source file.
7680 This section is dedicated to these source samples.
7682 @menu
7683 * Guidelines::                  General rules for writing test programs
7684 * Test Functions::              Avoiding pitfalls in test programs
7685 * Generating Sources::          Source program boilerplate
7686 @end menu
7688 @node Guidelines
7689 @subsection Guidelines for Test Programs
7691 The most important rule to follow when writing testing samples is:
7693 @center @emph{Look for realism.}
7695 This motto means that testing samples must be written with the same
7696 strictness as real programs are written.  In particular, you should
7697 avoid ``shortcuts'' and simplifications.
7699 Don't just play with the preprocessor if you want to prepare a
7700 compilation.  For instance, using @command{cpp} to check whether a header is
7701 functional might let your @command{configure} accept a header which
7702 causes some @emph{compiler} error.  Do not hesitate to check a header with
7703 other headers included before, especially required headers.
7705 Make sure the symbols you use are properly defined, i.e., refrain for
7706 simply declaring a function yourself instead of including the proper
7707 header.
7709 Test programs should not write to standard output.  They
7710 should exit with status 0 if the test succeeds, and with status 1
7711 otherwise, so that success
7712 can be distinguished easily from a core dump or other failure;
7713 segmentation violations and other failures produce a nonzero exit
7714 status.  Unless you arrange for @code{exit} to be declared, test
7715 programs should @code{return}, not @code{exit}, from @code{main},
7716 because on many systems @code{exit} is not declared by default.
7718 Test programs can use @code{#if} or @code{#ifdef} to check the values of
7719 preprocessor macros defined by tests that have already run.  For
7720 example, if you call @code{AC_HEADER_STDBOOL}, then later on in
7721 @file{configure.ac} you can have a test program that includes
7722 @file{stdbool.h} conditionally:
7724 @example
7725 @group
7726 #ifdef HAVE_STDBOOL_H
7727 # include <stdbool.h>
7728 #endif
7729 @end group
7730 @end example
7732 Both @code{#if HAVE_STDBOOL_H} and @code{#ifdef HAVE_STDBOOL_H} will
7733 work with any standard C compiler.  Some developers prefer @code{#if}
7734 because it is easier to read, while others prefer @code{#ifdef} because
7735 it avoids diagnostics with picky compilers like @acronym{GCC} with the
7736 @option{-Wundef} option.
7738 If a test program needs to use or create a data file, give it a name
7739 that starts with @file{conftest}, such as @file{conftest.data}.  The
7740 @command{configure} script cleans up by running @samp{rm -f -r conftest*}
7741 after running test programs and if the script is interrupted.
7743 @node Test Functions
7744 @subsection Test Functions
7746 These days it's safe to assume support for function prototypes
7747 (introduced in C89).
7749 Functions that test programs declare should also be conditionalized for
7750 C++, which requires @samp{extern "C"} prototypes.  Make sure to not
7751 include any header files containing clashing prototypes.
7753 @example
7754 #ifdef __cplusplus
7755 extern "C"
7756 #endif
7757 void *valloc (size_t);
7758 @end example
7760 If a test program calls a function with invalid parameters (just to see
7761 whether it exists), organize the program to ensure that it never invokes
7762 that function.  You can do this by calling it in another function that is
7763 never invoked.  You can't do it by putting it after a call to
7764 @code{exit}, because @acronym{GCC} version 2 knows that @code{exit}
7765 never returns
7766 and optimizes out any code that follows it in the same block.
7768 If you include any header files, be sure to call the functions
7769 relevant to them with the correct number of arguments, even if they are
7770 just 0, to avoid compilation errors due to prototypes.  @acronym{GCC}
7771 version 2
7772 has internal prototypes for several functions that it automatically
7773 inlines; for example, @code{memcpy}.  To avoid errors when checking for
7774 them, either pass them the correct number of arguments or redeclare them
7775 with a different return type (such as @code{char}).
7778 @node Generating Sources
7779 @subsection Generating Sources
7781 Autoconf provides a set of macros that can be used to generate test
7782 source files.  They are written to be language generic, i.e., they
7783 actually depend on the current language (@pxref{Language Choice}) to
7784 ``format'' the output properly.
7787 @defmac AC_LANG_CONFTEST (@var{source})
7788 @acindex{LANG_CONFTEST}
7789 Save the @var{source} text in the current test source file:
7790 @file{conftest.@var{extension}} where the @var{extension} depends on the
7791 current language.
7793 Note that the @var{source} is evaluated exactly once, like regular
7794 Autoconf macro arguments, and therefore (i) you may pass a macro
7795 invocation, (ii) if not, be sure to double quote if needed.
7796 @end defmac
7798 @defmac AC_LANG_SOURCE (@var{source})
7799 @acindex{LANG_SOURCE}
7800 Expands into the @var{source}, with the definition of
7801 all the @code{AC_DEFINE} performed so far.
7802 @end defmac
7804 For instance executing (observe the double quotation!):
7806 @example
7807 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7808 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
7809   [Greetings string.])
7810 AC_LANG(C)
7811 AC_LANG_CONFTEST(
7812    [AC_LANG_SOURCE([[const char hw[] = "Hello, World\n";]])])
7813 gcc -E -dD -o - conftest.c
7814 @end example
7816 @noindent
7817 results in:
7819 @example
7820 @dots{}
7821 # 1 "conftest.c"
7823 #define PACKAGE_NAME "Hello"
7824 #define PACKAGE_TARNAME "hello"
7825 #define PACKAGE_VERSION "1.0"
7826 #define PACKAGE_STRING "Hello 1.0"
7827 #define PACKAGE_BUGREPORT "bug-hello@@example.org"
7828 #define HELLO_WORLD "Hello, World\n"
7830 const char hw[] = "Hello, World\n";
7831 @end example
7833 When the test language is Fortran or Erlang, the @code{AC_DEFINE} definitions
7834 are not automatically translated into constants in the source code by this
7835 macro.
7837 @defmac AC_LANG_PROGRAM (@var{prologue}, @var{body})
7838 @acindex{LANG_PROGRAM}
7839 Expands into a source file which consists of the @var{prologue}, and
7840 then @var{body} as body of the main function (e.g., @code{main} in
7841 C).  Since it uses @code{AC_LANG_SOURCE}, the features of the latter are
7842 available.
7843 @end defmac
7845 For instance:
7847 @example
7848 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7849 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
7850   [Greetings string.])
7851 AC_LANG_CONFTEST(
7852 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
7853                  [[fputs (hw, stdout);]])])
7854 gcc -E -dD -o - conftest.c
7855 @end example
7857 @noindent
7858 results in:
7860 @example
7861 @dots{}
7862 # 1 "conftest.c"
7864 #define PACKAGE_NAME "Hello"
7865 #define PACKAGE_TARNAME "hello"
7866 #define PACKAGE_VERSION "1.0"
7867 #define PACKAGE_STRING "Hello 1.0"
7868 #define PACKAGE_BUGREPORT "bug-hello@@example.org"
7869 #define HELLO_WORLD "Hello, World\n"
7871 const char hw[] = "Hello, World\n";
7873 main ()
7875 fputs (hw, stdout);
7876   ;
7877   return 0;
7879 @end example
7881 In Erlang tests, the created source file is that of an Erlang module called
7882 @code{conftest} (@file{conftest.erl}).  This module defines and exports at least
7883 one @code{start/0} function, which is called to perform the test.  The
7884 @var{prologue} is optional code that is inserted between the module header and
7885 the @code{start/0} function definition.  @var{body} is the body of the
7886 @code{start/0} function without the final period (@pxref{Runtime}, about
7887 constraints on this function's behavior).
7889 For instance:
7891 @example
7892 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7893 AC_LANG(Erlang)
7894 AC_LANG_CONFTEST(
7895 [AC_LANG_PROGRAM([[-define(HELLO_WORLD, "Hello, world!").]],
7896                  [[io:format("~s~n", [?HELLO_WORLD])]])])
7897 cat conftest.erl
7898 @end example
7900 @noindent
7901 results in:
7903 @example
7904 -module(conftest).
7905 -export([start/0]).
7906 -define(HELLO_WORLD, "Hello, world!").
7907 start() ->
7908 io:format("~s~n", [?HELLO_WORLD])
7910 @end example
7912 @defmac AC_LANG_CALL (@var{prologue}, @var{function})
7913 @acindex{LANG_CALL}
7914 Expands into a source file which consists of the @var{prologue}, and
7915 then a call to the @var{function} as body of the main function (e.g.,
7916 @code{main} in C).  Since it uses @code{AC_LANG_PROGRAM}, the feature
7917 of the latter are available.
7919 This function will probably be replaced in the future by a version
7920 which would enable specifying the arguments.  The use of this macro is
7921 not encouraged, as it violates strongly the typing system.
7923 This macro cannot be used for Erlang tests.
7924 @end defmac
7926 @defmac AC_LANG_FUNC_LINK_TRY (@var{function})
7927 @acindex{LANG_FUNC_LINK_TRY}
7928 Expands into a source file which uses the @var{function} in the body of
7929 the main function (e.g., @code{main} in C).  Since it uses
7930 @code{AC_LANG_PROGRAM}, the features of the latter are available.
7932 As @code{AC_LANG_CALL}, this macro is documented only for completeness.
7933 It is considered to be severely broken, and in the future will be
7934 removed in favor of actual function calls (with properly typed
7935 arguments).
7937 This macro cannot be used for Erlang tests.
7938 @end defmac
7940 @node Running the Preprocessor
7941 @section Running the Preprocessor
7943 Sometimes one might need to run the preprocessor on some source file.
7944 @emph{Usually it is a bad idea}, as you typically need to @emph{compile}
7945 your project, not merely run the preprocessor on it; therefore you
7946 certainly want to run the compiler, not the preprocessor.  Resist the
7947 temptation of following the easiest path.
7949 Nevertheless, if you need to run the preprocessor, then use
7950 @code{AC_PREPROC_IFELSE}.
7952 The macros described in this section cannot be used for tests in Erlang or
7953 Fortran, since those languages require no preprocessor.
7955 @defmac AC_PREPROC_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
7956 @acindex{PREPROC_IFELSE}
7957 Run the preprocessor of the current language (@pxref{Language Choice})
7958 on the @var{input}, run the shell commands @var{action-if-true} on
7959 success, @var{action-if-false} otherwise.  The @var{input} can be made
7960 by @code{AC_LANG_PROGRAM} and friends.
7962 This macro uses @code{CPPFLAGS}, but not @code{CFLAGS}, because
7963 @option{-g}, @option{-O}, etc.@: are not valid options to many C
7964 preprocessors.
7966 It is customary to report unexpected failures with
7967 @code{AC_MSG_FAILURE}.
7968 @end defmac
7970 For instance:
7972 @example
7973 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7974 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
7975   [Greetings string.])
7976 AC_PREPROC_IFELSE(
7977    [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
7978                     [[fputs (hw, stdout);]])],
7979    [AC_MSG_RESULT([OK])],
7980    [AC_MSG_FAILURE([unexpected preprocessor failure])])
7981 @end example
7983 @noindent
7984 results in:
7986 @example
7987 checking for gcc... gcc
7988 checking for C compiler default output file name... a.out
7989 checking whether the C compiler works... yes
7990 checking whether we are cross compiling... no
7991 checking for suffix of executables...
7992 checking for suffix of object files... o
7993 checking whether we are using the GNU C compiler... yes
7994 checking whether gcc accepts -g... yes
7995 checking for gcc option to accept ISO C89... none needed
7996 checking how to run the C preprocessor... gcc -E
7998 @end example
8000 @sp 1
8002 The macro @code{AC_TRY_CPP} (@pxref{Obsolete Macros}) used to play the
8003 role of @code{AC_PREPROC_IFELSE}, but double quotes its argument, making
8004 it impossible to use it to elaborate sources.  You are encouraged to
8005 get rid of your old use of the macro @code{AC_TRY_CPP} in favor of
8006 @code{AC_PREPROC_IFELSE}, but, in the first place, are you sure you need
8007 to run the @emph{preprocessor} and not the compiler?
8009 @defmac AC_EGREP_HEADER (@var{pattern}, @var{header-file}, @var{action-if-found}, @ovar{action-if-not-found})
8010 @acindex{EGREP_HEADER}
8011 If the output of running the preprocessor on the system header file
8012 @var{header-file} matches the extended regular expression
8013 @var{pattern}, execute shell commands @var{action-if-found}, otherwise
8014 execute @var{action-if-not-found}.
8015 @end defmac
8017 @defmac AC_EGREP_CPP (@var{pattern}, @var{program}, @ovar{action-if-found}, @ovar{action-if-not-found})
8018 @acindex{EGREP_CPP}
8019 @var{program} is the text of a C or C++ program, on which shell
8020 variable, back quote, and backslash substitutions are performed.  If the
8021 output of running the preprocessor on @var{program} matches the
8022 extended regular expression @var{pattern}, execute shell commands
8023 @var{action-if-found}, otherwise execute @var{action-if-not-found}.
8024 @end defmac
8028 @node Running the Compiler
8029 @section Running the Compiler
8031 To check for a syntax feature of the current language's (@pxref{Language
8032 Choice}) compiler, such as whether it recognizes a certain keyword, or
8033 simply to try some library feature, use @code{AC_COMPILE_IFELSE} to try
8034 to compile a small program that uses that feature.
8036 @defmac AC_COMPILE_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
8037 @acindex{COMPILE_IFELSE}
8038 Run the compiler and compilation flags of the current language
8039 (@pxref{Language Choice}) on the @var{input}, run the shell commands
8040 @var{action-if-true} on success, @var{action-if-false} otherwise.  The
8041 @var{input} can be made by @code{AC_LANG_PROGRAM} and friends.
8043 It is customary to report unexpected failures with
8044 @code{AC_MSG_FAILURE}.  This macro does not try to link; use
8045 @code{AC_LINK_IFELSE} if you need to do that (@pxref{Running the
8046 Linker}).
8047 @end defmac
8049 @ovindex ERL
8050 For tests in Erlang, the @var{input} must be the source code of a module named
8051 @code{conftest}.  @code{AC_COMPILE_IFELSE} generates a @file{conftest.beam}
8052 file that can be interpreted by the Erlang virtual machine (@code{ERL}).  It is
8053 recommended to use @code{AC_LANG_PROGRAM} to specify the test program, to ensure
8054 that the Erlang module has the right name.
8056 @node Running the Linker
8057 @section Running the Linker
8059 To check for a library, a function, or a global variable, Autoconf
8060 @command{configure} scripts try to compile and link a small program that
8061 uses it.  This is unlike Metaconfig, which by default uses @code{nm} or
8062 @code{ar} on the C library to try to figure out which functions are
8063 available.  Trying to link with the function is usually a more reliable
8064 approach because it avoids dealing with the variations in the options
8065 and output formats of @code{nm} and @code{ar} and in the location of the
8066 standard libraries.  It also allows configuring for cross-compilation or
8067 checking a function's runtime behavior if needed.  On the other hand,
8068 it can be slower than scanning the libraries once, but accuracy is more
8069 important than speed.
8071 @code{AC_LINK_IFELSE} is used to compile test programs to test for
8072 functions and global variables.  It is also used by @code{AC_CHECK_LIB}
8073 to check for libraries (@pxref{Libraries}), by adding the library being
8074 checked for to @code{LIBS} temporarily and trying to link a small
8075 program.
8078 @defmac AC_LINK_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
8079 @acindex{LINK_IFELSE}
8080 Run the compiler (and compilation flags) and the linker of the current
8081 language (@pxref{Language Choice}) on the @var{input}, run the shell
8082 commands @var{action-if-true} on success, @var{action-if-false}
8083 otherwise.  The @var{input} can be made by @code{AC_LANG_PROGRAM} and
8084 friends.
8086 @code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
8087 current compilation flags.
8089 It is customary to report unexpected failures with
8090 @code{AC_MSG_FAILURE}.  This macro does not try to execute the program;
8091 use @code{AC_RUN_IFELSE} if you need to do that (@pxref{Runtime}).
8092 @end defmac
8094 The @code{AC_LINK_IFELSE} macro cannot be used for Erlang tests, since Erlang
8095 programs are interpreted and do not require linking.
8099 @node Runtime
8100 @section Checking Runtime Behavior
8102 Sometimes you need to find out how a system performs at runtime, such
8103 as whether a given function has a certain capability or bug.  If you
8104 can, make such checks when your program runs instead of when it is
8105 configured.  You can check for things like the machine's endianness when
8106 your program initializes itself.
8108 If you really need to test for a runtime behavior while configuring,
8109 you can write a test program to determine the result, and compile and
8110 run it using @code{AC_RUN_IFELSE}.  Avoid running test programs if
8111 possible, because this prevents people from configuring your package for
8112 cross-compiling.
8114 @defmac AC_RUN_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-cross-compiling})
8115 @acindex{RUN_IFELSE}
8116 If @var{program} compiles and links successfully and returns an exit
8117 status of 0 when executed, run shell commands @var{action-if-true}.
8118 Otherwise, run shell commands @var{action-if-false}.
8120 The @var{input} can be made by @code{AC_LANG_PROGRAM} and friends.
8121 @code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
8122 compilation flags of the current language (@pxref{Language Choice}).
8124 If the compiler being used does not produce executables that run on the
8125 system where @command{configure} is being run, then the test program is
8126 not run.  If the optional shell commands @var{action-if-cross-compiling}
8127 are given, they are run instead.  Otherwise, @command{configure} prints
8128 an error message and exits.
8130 In the @var{action-if-false} section, the failing exit status is
8131 available in the shell variable @samp{$?}.  This exit status might be
8132 that of a failed compilation, or it might be that of a failed program
8133 execution.
8135 It is customary to report unexpected failures with
8136 @code{AC_MSG_FAILURE}.
8137 @end defmac
8139 Try to provide a pessimistic default value to use when cross-compiling
8140 makes runtime tests impossible.  You do this by passing the optional
8141 last argument to @code{AC_RUN_IFELSE}.  @command{autoconf} prints a
8142 warning message when creating @command{configure} each time it
8143 encounters a call to @code{AC_RUN_IFELSE} with no
8144 @var{action-if-cross-compiling} argument given.  You may ignore the
8145 warning, though users cannot configure your package for
8146 cross-compiling.  A few of the macros distributed with Autoconf produce
8147 this warning message.
8149 To configure for cross-compiling you can also choose a value for those
8150 parameters based on the canonical system name (@pxref{Manual
8151 Configuration}).  Alternatively, set up a test results cache file with
8152 the correct values for the host system (@pxref{Caching Results}).
8154 @ovindex cross_compiling
8155 To provide a default for calls of @code{AC_RUN_IFELSE} that are embedded
8156 in other macros, including a few of the ones that come with Autoconf,
8157 you can test whether the shell variable @code{cross_compiling} is set to
8158 @samp{yes}, and then use an alternate method to get the results instead
8159 of calling the macros.
8161 A C or C++ runtime test should be portable.
8162 @xref{Portable C and C++}.
8164 Erlang tests must exit themselves the Erlang VM by calling the @code{halt/1}
8165 function: the given status code is used to determine the success of the test
8166 (status is @code{0}) or its failure (status is different than @code{0}), as
8167 explained above.  It must be noted that data output through the standard output
8168 (e.g., using @code{io:format/2}) may be truncated when halting the VM.
8169 Therefore, if a test must output configuration information, it is recommended
8170 to create and to output data into the temporary file named @file{conftest.out},
8171 using the functions of module @code{file}.  The @code{conftest.out} file is
8172 automatically deleted by the @code{AC_RUN_IFELSE} macro.  For instance, a
8173 simplified implementation of Autoconf's @code{AC_ERLANG_SUBST_LIB_DIR} macro is:
8175 @example
8176 AC_INIT([LibdirTest], [1.0], [bug-libdirtest@@example.org])
8177 AC_ERLANG_NEED_ERL
8178 AC_LANG(Erlang)
8179 AC_RUN_IFELSE(
8180   [AC_LANG_PROGRAM([], [dnl
8181     file:write_file("conftest.out", code:lib_dir()),
8182     halt(0)])],
8183   [echo "code:lib_dir() returned: `cat conftest.out`"],
8184   [AC_MSG_FAILURE([test Erlang program execution failed])])
8185 @end example
8188 @node Systemology
8189 @section Systemology
8190 @cindex Systemology
8192 This section aims at presenting some systems and pointers to
8193 documentation.  It may help you addressing particular problems reported
8194 by users.
8196 @uref{http://www.opengroup.org/susv3, Posix-conforming systems} are
8197 derived from the @uref{http://www.bell-labs.com/history/unix/, Unix
8198 operating system}.
8200 The @uref{http://bhami.com/rosetta.html, Rosetta Stone for Unix}
8201 contains a table correlating the features of various Posix-conforming
8202 systems.  @uref{http://www.levenez.com/unix/, Unix History} is a
8203 simplified diagram of how many Unix systems were derived from each
8204 other.
8206 @uref{http://heirloom.sourceforge.net/, The Heirloom Project}
8207 provides some variants of traditional implementations of Unix utilities.
8209 @table @asis
8210 @item Darwin
8211 @cindex Darwin
8212 Darwin is also known as Mac OS X@.  Beware that the file system @emph{can} be
8213 case-preserving, but case insensitive.  This can cause nasty problems,
8214 since for instance the installation attempt for a package having an
8215 @file{INSTALL} file can result in @samp{make install} report that
8216 nothing was to be done!
8218 That's all dependent on whether the file system is a UFS (case
8219 sensitive) or HFS+ (case preserving).  By default Apple wants you to
8220 install the OS on HFS+.  Unfortunately, there are some pieces of
8221 software which really need to be built on UFS@.  We may want to rebuild
8222 Darwin to have both UFS and HFS+ available (and put the /local/build
8223 tree on the UFS).
8225 @item @acronym{QNX} 4.25
8226 @cindex @acronym{QNX} 4.25
8227 @c FIXME: Please, if you feel like writing something more precise,
8228 @c it'd be great.  In particular, I can't understand the difference with
8229 @c QNX Neutrino.
8230 @acronym{QNX} is a realtime operating system running on Intel architecture
8231 meant to be scalable from the small embedded systems to the hundred
8232 processor super-computer.  It claims to be Posix certified.  More
8233 information is available on the
8234 @uref{http://www.qnx.com/, @acronym{QNX} home page}.
8236 @item Tru64
8237 @cindex Tru64
8238 @uref{http://h30097.www3.hp.com/@/docs/,
8239 Documentation of several versions of Tru64} is available in different
8240 formats.
8242 @item Unix version 7
8243 @cindex Unix version 7
8244 @cindex V7
8245 Officially this was called the ``Seventh Edition'' of ``the @sc{unix}
8246 time-sharing system'' but we use the more-common name ``Unix version 7''.
8247 Documentation is available in the
8248 @uref{http://plan9.bell-labs.com/@/7thEdMan/, Unix Seventh Edition Manual}.
8249 Previous versions of Unix are called ``Unix version 6'', etc., but
8250 they were not as widely used.
8251 @end table
8254 @node Multiple Cases
8255 @section Multiple Cases
8257 Some operations are accomplished in several possible ways, depending on
8258 the OS variant.  Checking for them essentially requires a ``case
8259 statement''.  Autoconf does not directly provide one; however, it is
8260 easy to simulate by using a shell variable to keep track of whether a
8261 way to perform the operation has been found yet.
8263 Here is an example that uses the shell variable @code{fstype} to keep
8264 track of whether the remaining cases need to be checked.
8266 @example
8267 @group
8268 AC_MSG_CHECKING([how to get file system type])
8269 fstype=no
8270 # The order of these tests is important.
8271 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statvfs.h>
8272 #include <sys/fstyp.h>]])],
8273                   [AC_DEFINE([FSTYPE_STATVFS], [1],
8274                      [Define if statvfs exists.])
8275                    fstype=SVR4])
8276 if test $fstype = no; then
8277   AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
8278 #include <sys/fstyp.h>]])],
8279                   [AC_DEFINE([FSTYPE_USG_STATFS], [1],
8280                      [Define if USG statfs.])
8281                    fstype=SVR3])
8283 if test $fstype = no; then
8284   AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
8285 #include <sys/vmount.h>]])]),
8286                   [AC_DEFINE([FSTYPE_AIX_STATFS], [1],
8287                      [Define if AIX statfs.])
8288                    fstype=AIX])
8290 # (more cases omitted here)
8291 AC_MSG_RESULT([$fstype])
8292 @end group
8293 @end example
8295 @c ====================================================== Results of Tests.
8297 @node Results
8298 @chapter Results of Tests
8300 Once @command{configure} has determined whether a feature exists, what can
8301 it do to record that information?  There are four sorts of things it can
8302 do: define a C preprocessor symbol, set a variable in the output files,
8303 save the result in a cache file for future @command{configure} runs, and
8304 print a message letting the user know the result of the test.
8306 @menu
8307 * Defining Symbols::            Defining C preprocessor symbols
8308 * Setting Output Variables::    Replacing variables in output files
8309 * Special Chars in Variables::  Characters to beware of in variables
8310 * Caching Results::             Speeding up subsequent @command{configure} runs
8311 * Printing Messages::           Notifying @command{configure} users
8312 @end menu
8314 @node Defining Symbols
8315 @section Defining C Preprocessor Symbols
8317 A common action to take in response to a feature test is to define a C
8318 preprocessor symbol indicating the results of the test.  That is done by
8319 calling @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}.
8321 By default, @code{AC_OUTPUT} places the symbols defined by these macros
8322 into the output variable @code{DEFS}, which contains an option
8323 @option{-D@var{symbol}=@var{value}} for each symbol defined.  Unlike in
8324 Autoconf version 1, there is no variable @code{DEFS} defined while
8325 @command{configure} is running.  To check whether Autoconf macros have
8326 already defined a certain C preprocessor symbol, test the value of the
8327 appropriate cache variable, as in this example:
8329 @example
8330 AC_CHECK_FUNC([vprintf], [AC_DEFINE([HAVE_VPRINTF], [1],
8331                           [Define if vprintf exists.])])
8332 if test "$ac_cv_func_vprintf" != yes; then
8333   AC_CHECK_FUNC([_doprnt], [AC_DEFINE([HAVE_DOPRNT], [1],
8334                             [Define if _doprnt exists.])])
8336 @end example
8338 If @code{AC_CONFIG_HEADERS} has been called, then instead of creating
8339 @code{DEFS}, @code{AC_OUTPUT} creates a header file by substituting the
8340 correct values into @code{#define} statements in a template file.
8341 @xref{Configuration Headers}, for more information about this kind of
8342 output.
8344 @defmac AC_DEFINE (@var{variable}, @var{value}, @ovar{description})
8345 @defmacx AC_DEFINE (@var{variable})
8346 @acindex{DEFINE}
8347 Define @var{variable} to @var{value} (verbatim), by defining a C
8348 preprocessor macro for @var{variable}.  @var{variable} should be a C
8349 identifier, optionally suffixed by a parenthesized argument list to
8350 define a C preprocessor macro with arguments.  The macro argument list,
8351 if present, should be a comma-separated list of C identifiers, possibly
8352 terminated by an ellipsis @samp{...} if C99 syntax is employed.
8353 @var{variable} should not contain comments, white space, trigraphs,
8354 backslash-newlines, universal character names, or non-@acronym{ASCII}
8355 characters.
8357 @var{value} should not contain literal newlines, and if you are not
8358 using @code{AC_CONFIG_HEADERS} it should not contain any @samp{#}
8359 characters, as @command{make} tends to eat them.  To use a shell variable,
8360 use @code{AC_DEFINE_UNQUOTED} instead.
8361 @var{description} is only useful if you are using
8362 @code{AC_CONFIG_HEADERS}.  In this case, @var{description} is put into
8363 the generated @file{config.h.in} as the comment before the macro define.
8364 The following example defines the C preprocessor variable
8365 @code{EQUATION} to be the string constant @samp{"$a > $b"}:
8367 @example
8368 AC_DEFINE([EQUATION], ["$a > $b"],
8369   [Equation string.])
8370 @end example
8372 If neither @var{value} nor @var{description} are given, then
8373 @var{value} defaults to 1 instead of to the empty string.  This is for
8374 backwards compatibility with older versions of Autoconf, but this usage
8375 is obsolescent and may be withdrawn in future versions of Autoconf.
8377 If the @var{variable} is a literal string, it is passed to
8378 @code{m4_pattern_allow} (@pxref{Forbidden Patterns}).
8380 If multiple @code{AC_DEFINE} statements are executed for the same
8381 @var{variable} name (not counting any parenthesized argument list),
8382 the last one wins.
8383 @end defmac
8385 @defmac AC_DEFINE_UNQUOTED (@var{variable}, @var{value}, @ovar{description})
8386 @defmacx AC_DEFINE_UNQUOTED (@var{variable})
8387 @acindex{DEFINE_UNQUOTED}
8388 Like @code{AC_DEFINE}, but three shell expansions are
8389 performed---once---on @var{variable} and @var{value}: variable expansion
8390 (@samp{$}), command substitution (@samp{`}), and backslash escaping
8391 (@samp{\}).  Single and double quote characters in the value have no
8392 special meaning.  Use this macro instead of @code{AC_DEFINE} when
8393 @var{variable} or @var{value} is a shell variable.  Examples:
8395 @example
8396 AC_DEFINE_UNQUOTED([config_machfile], ["$machfile"],
8397   [Configuration machine file.])
8398 AC_DEFINE_UNQUOTED([GETGROUPS_T], [$ac_cv_type_getgroups],
8399   [getgroups return type.])
8400 AC_DEFINE_UNQUOTED([$ac_tr_hdr], [1],
8401   [Translated header name.])
8402 @end example
8403 @end defmac
8405 Due to a syntactical bizarreness of the Bourne shell, do not use
8406 semicolons to separate @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}
8407 calls from other macro calls or shell code; that can cause syntax errors
8408 in the resulting @command{configure} script.  Use either blanks or
8409 newlines.  That is, do this:
8411 @example
8412 AC_CHECK_HEADER([elf.h],
8413   [AC_DEFINE([SVR4], [1], [System V Release 4]) LIBS="-lelf $LIBS"])
8414 @end example
8416 @noindent
8417 or this:
8419 @example
8420 AC_CHECK_HEADER([elf.h],
8421   [AC_DEFINE([SVR4], [1], [System V Release 4])
8422    LIBS="-lelf $LIBS"])
8423 @end example
8425 @noindent
8426 instead of this:
8428 @example
8429 AC_CHECK_HEADER([elf.h],
8430   [AC_DEFINE([SVR4], [1], [System V Release 4]); LIBS="-lelf $LIBS"])
8431 @end example
8433 @node Setting Output Variables
8434 @section Setting Output Variables
8435 @cindex Output variables
8437 Another way to record the results of tests is to set @dfn{output
8438 variables}, which are shell variables whose values are substituted into
8439 files that @command{configure} outputs.  The two macros below create new
8440 output variables.  @xref{Preset Output Variables}, for a list of output
8441 variables that are always available.
8443 @defmac AC_SUBST (@var{variable}, @ovar{value})
8444 @acindex{SUBST}
8445 Create an output variable from a shell variable.  Make @code{AC_OUTPUT}
8446 substitute the variable @var{variable} into output files (typically one
8447 or more makefiles).  This means that @code{AC_OUTPUT}
8448 replaces instances of @samp{@@@var{variable}@@} in input files with the
8449 value that the shell variable @var{variable} has when @code{AC_OUTPUT}
8450 is called.  The value can contain any non-@code{NUL} character, including
8451 newline.
8452 Variable occurrences should not overlap: e.g., an input file should
8453 not contain @samp{@@@var{var1}@@@var{var2}@@} if @var{var1} and @var{var2}
8454 are variable names.
8455 The substituted value is not rescanned for more output variables;
8456 occurrences of @samp{@@@var{variable}@@} in the value are inserted
8457 literally into the output file.  (The algorithm uses the special marker
8458 @code{|#_!!_#|} internally, so neither the substituted value nor the
8459 output file may contain @code{|#_!!_#|}.)
8461 If @var{value} is given, in addition assign it to @var{variable}.
8463 The string @var{variable} is passed to @code{m4_pattern_allow}
8464 (@pxref{Forbidden Patterns}).
8465 @end defmac
8467 @defmac AC_SUBST_FILE (@var{variable})
8468 @acindex{SUBST_FILE}
8469 Another way to create an output variable from a shell variable.  Make
8470 @code{AC_OUTPUT} insert (without substitutions) the contents of the file
8471 named by shell variable @var{variable} into output files.  This means
8472 that @code{AC_OUTPUT} replaces instances of
8473 @samp{@@@var{variable}@@} in output files (such as @file{Makefile.in})
8474 with the contents of the file that the shell variable @var{variable}
8475 names when @code{AC_OUTPUT} is called.  Set the variable to
8476 @file{/dev/null} for cases that do not have a file to insert.
8477 This substitution occurs only when the @samp{@@@var{variable}@@} is on a
8478 line by itself, optionally surrounded by spaces and tabs.  The
8479 substitution replaces the whole line, including the spaces, tabs, and
8480 the terminating newline.
8482 This macro is useful for inserting makefile fragments containing
8483 special dependencies or other @code{make} directives for particular host
8484 or target types into makefiles.  For example, @file{configure.ac}
8485 could contain:
8487 @example
8488 AC_SUBST_FILE([host_frag])
8489 host_frag=$srcdir/conf/sun4.mh
8490 @end example
8492 @noindent
8493 and then a @file{Makefile.in} could contain:
8495 @example
8496 @@host_frag@@
8497 @end example
8499 The string @var{variable} is passed to @code{m4_pattern_allow}
8500 (@pxref{Forbidden Patterns}).
8501 @end defmac
8503 @cindex Precious Variable
8504 @cindex Variable, Precious
8505 Running @command{configure} in varying environments can be extremely
8506 dangerous.  If for instance the user runs @samp{CC=bizarre-cc
8507 ./configure}, then the cache, @file{config.h}, and many other output
8508 files depend upon @command{bizarre-cc} being the C compiler.  If
8509 for some reason the user runs @command{./configure} again, or if it is
8510 run via @samp{./config.status --recheck}, (@xref{Automatic Remaking},
8511 and @pxref{config.status Invocation}), then the configuration can be
8512 inconsistent, composed of results depending upon two different
8513 compilers.
8515 Environment variables that affect this situation, such as @samp{CC}
8516 above, are called @dfn{precious variables}, and can be declared as such
8517 by @code{AC_ARG_VAR}.
8519 @defmac AC_ARG_VAR (@var{variable}, @var{description})
8520 @acindex{ARG_VAR}
8521 Declare @var{variable} is a precious variable, and include its
8522 @var{description} in the variable section of @samp{./configure --help}.
8524 Being precious means that
8525 @itemize @minus
8526 @item
8527 @var{variable} is substituted via @code{AC_SUBST}.
8529 @item
8530 The value of @var{variable} when @command{configure} was launched is
8531 saved in the cache, including if it was not specified on the command
8532 line but via the environment.  Indeed, while @command{configure} can
8533 notice the definition of @code{CC} in @samp{./configure CC=bizarre-cc},
8534 it is impossible to notice it in @samp{CC=bizarre-cc ./configure},
8535 which, unfortunately, is what most users do.
8537 We emphasize that it is the @emph{initial} value of @var{variable} which
8538 is saved, not that found during the execution of @command{configure}.
8539 Indeed, specifying @samp{./configure FOO=foo} and letting
8540 @samp{./configure} guess that @code{FOO} is @code{foo} can be two
8541 different things.
8543 @item
8544 @var{variable} is checked for consistency between two
8545 @command{configure} runs.  For instance:
8547 @example
8548 $ @kbd{./configure --silent --config-cache}
8549 $ @kbd{CC=cc ./configure --silent --config-cache}
8550 configure: error: `CC' was not set in the previous run
8551 configure: error: changes in the environment can compromise \
8552 the build
8553 configure: error: run `make distclean' and/or \
8554 `rm config.cache' and start over
8555 @end example
8557 @noindent
8558 and similarly if the variable is unset, or if its content is changed.
8561 @item
8562 @var{variable} is kept during automatic reconfiguration
8563 (@pxref{config.status Invocation}) as if it had been passed as a command
8564 line argument, including when no cache is used:
8566 @example
8567 $ @kbd{CC=/usr/bin/cc ./configure undeclared_var=raboof --silent}
8568 $ @kbd{./config.status --recheck}
8569 running CONFIG_SHELL=/bin/sh /bin/sh ./configure undeclared_var=raboof \
8570   CC=/usr/bin/cc  --no-create --no-recursion
8571 @end example
8572 @end itemize
8573 @end defmac
8575 @node Special Chars in Variables
8576 @section Special Characters in Output Variables
8577 @cindex Output variables, special characters in
8579 Many output variables are intended to be evaluated both by
8580 @command{make} and by the shell.  Some characters are expanded
8581 differently in these two contexts, so to avoid confusion these
8582 variables' values should not contain any of the following characters:
8584 @example
8585 " # $ & ' ( ) * ; < > ? [ \ ^ ` |
8586 @end example
8588 Also, these variables' values should neither contain newlines, nor start
8589 with @samp{~}, nor contain white space or @samp{:} immediately followed
8590 by @samp{~}.  The values can contain nonempty sequences of white space
8591 characters like tabs and spaces, but each such sequence might
8592 arbitrarily be replaced by a single space during substitution.
8594 These restrictions apply both to the values that @command{configure}
8595 computes, and to the values set directly by the user.  For example, the
8596 following invocations of @command{configure} are problematic, since they
8597 attempt to use special characters within @code{CPPFLAGS} and white space
8598 within @code{$(srcdir)}:
8600 @example
8601 CPPFLAGS='-DOUCH="&\"#$*?"' '../My Source/ouch-1.0/configure'
8603 '../My Source/ouch-1.0/configure' CPPFLAGS='-DOUCH="&\"#$*?"'
8604 @end example
8606 @node Caching Results
8607 @section Caching Results
8608 @cindex Cache
8610 To avoid checking for the same features repeatedly in various
8611 @command{configure} scripts (or in repeated runs of one script),
8612 @command{configure} can optionally save the results of many checks in a
8613 @dfn{cache file} (@pxref{Cache Files}).  If a @command{configure} script
8614 runs with caching enabled and finds a cache file, it reads the results
8615 of previous runs from the cache and avoids rerunning those checks.  As a
8616 result, @command{configure} can then run much faster than if it had to
8617 perform all of the checks every time.
8619 @defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it})
8620 @acindex{CACHE_VAL}
8621 Ensure that the results of the check identified by @var{cache-id} are
8622 available.  If the results of the check were in the cache file that was
8623 read, and @command{configure} was not given the @option{--quiet} or
8624 @option{--silent} option, print a message saying that the result was
8625 cached; otherwise, run the shell commands @var{commands-to-set-it}.  If
8626 the shell commands are run to determine the value, the value is
8627 saved in the cache file just before @command{configure} creates its output
8628 files.  @xref{Cache Variable Names}, for how to choose the name of the
8629 @var{cache-id} variable.
8631 The @var{commands-to-set-it} @emph{must have no side effects} except for
8632 setting the variable @var{cache-id}, see below.
8633 @end defmac
8635 @defmac AC_CACHE_CHECK (@var{message}, @var{cache-id}, @var{commands-to-set-it})
8636 @acindex{CACHE_CHECK}
8637 A wrapper for @code{AC_CACHE_VAL} that takes care of printing the
8638 messages.  This macro provides a convenient shorthand for the most
8639 common way to use these macros.  It calls @code{AC_MSG_CHECKING} for
8640 @var{message}, then @code{AC_CACHE_VAL} with the @var{cache-id} and
8641 @var{commands} arguments, and @code{AC_MSG_RESULT} with @var{cache-id}.
8643 The @var{commands-to-set-it} @emph{must have no side effects} except for
8644 setting the variable @var{cache-id}, see below.
8645 @end defmac
8647 It is common to find buggy macros using @code{AC_CACHE_VAL} or
8648 @code{AC_CACHE_CHECK}, because people are tempted to call
8649 @code{AC_DEFINE} in the @var{commands-to-set-it}.  Instead, the code that
8650 @emph{follows} the call to @code{AC_CACHE_VAL} should call
8651 @code{AC_DEFINE}, by examining the value of the cache variable.  For
8652 instance, the following macro is broken:
8654 @example
8655 @group
8656 AC_DEFUN([AC_SHELL_TRUE],
8657 [AC_CACHE_CHECK([whether true(1) works], [my_cv_shell_true_works],
8658                 [my_cv_shell_true_works=no
8659                  (true) 2>/dev/null && my_cv_shell_true_works=yes
8660                  if test "$my_cv_shell_true_works" = yes; then
8661                    AC_DEFINE([TRUE_WORKS], [1],
8662                              [Define if `true(1)' works properly.])
8663                  fi])
8665 @end group
8666 @end example
8668 @noindent
8669 This fails if the cache is enabled: the second time this macro is run,
8670 @code{TRUE_WORKS} @emph{will not be defined}.  The proper implementation
8673 @example
8674 @group
8675 AC_DEFUN([AC_SHELL_TRUE],
8676 [AC_CACHE_CHECK([whether true(1) works], [my_cv_shell_true_works],
8677                 [my_cv_shell_true_works=no
8678                  (true) 2>/dev/null && my_cv_shell_true_works=yes])
8679  if test "$my_cv_shell_true_works" = yes; then
8680    AC_DEFINE([TRUE_WORKS], [1],
8681              [Define if `true(1)' works properly.])
8682  fi
8684 @end group
8685 @end example
8687 Also, @var{commands-to-set-it} should not print any messages, for
8688 example with @code{AC_MSG_CHECKING}; do that before calling
8689 @code{AC_CACHE_VAL}, so the messages are printed regardless of whether
8690 the results of the check are retrieved from the cache or determined by
8691 running the shell commands.
8693 @menu
8694 * Cache Variable Names::        Shell variables used in caches
8695 * Cache Files::                 Files @command{configure} uses for caching
8696 * Cache Checkpointing::         Loading and saving the cache file
8697 @end menu
8699 @node Cache Variable Names
8700 @subsection Cache Variable Names
8701 @cindex Cache variable
8703 The names of cache variables should have the following format:
8705 @example
8706 @var{package-prefix}_cv_@var{value-type}_@var{specific-value}_@ovar{additional-options}
8707 @end example
8709 @noindent
8710 for example, @samp{ac_cv_header_stat_broken} or
8711 @samp{ac_cv_prog_gcc_traditional}.  The parts of the variable name are:
8713 @table @asis
8714 @item @var{package-prefix}
8715 An abbreviation for your package or organization; the same prefix you
8716 begin local Autoconf macros with, except lowercase by convention.
8717 For cache values used by the distributed Autoconf macros, this value is
8718 @samp{ac}.
8720 @item @code{_cv_}
8721 Indicates that this shell variable is a cache value.  This string
8722 @emph{must} be present in the variable name, including the leading
8723 underscore.
8725 @item @var{value-type}
8726 A convention for classifying cache values, to produce a rational naming
8727 system.  The values used in Autoconf are listed in @ref{Macro Names}.
8729 @item @var{specific-value}
8730 Which member of the class of cache values this test applies to.
8731 For example, which function (@samp{alloca}), program (@samp{gcc}), or
8732 output variable (@samp{INSTALL}).
8734 @item @var{additional-options}
8735 Any particular behavior of the specific member that this test applies to.
8736 For example, @samp{broken} or @samp{set}.  This part of the name may
8737 be omitted if it does not apply.
8738 @end table
8740 The values assigned to cache variables may not contain newlines.
8741 Usually, their values are Boolean (@samp{yes} or @samp{no}) or the
8742 names of files or functions; so this is not an important restriction.
8744 @node Cache Files
8745 @subsection Cache Files
8747 A cache file is a shell script that caches the results of configure
8748 tests run on one system so they can be shared between configure scripts
8749 and configure runs.  It is not useful on other systems.  If its contents
8750 are invalid for some reason, the user may delete or edit it.
8752 By default, @command{configure} uses no cache file,
8753 to avoid problems caused by accidental
8754 use of stale cache files.
8756 To enable caching, @command{configure} accepts @option{--config-cache} (or
8757 @option{-C}) to cache results in the file @file{config.cache}.
8758 Alternatively, @option{--cache-file=@var{file}} specifies that
8759 @var{file} be the cache file.  The cache file is created if it does not
8760 exist already.  When @command{configure} calls @command{configure} scripts in
8761 subdirectories, it uses the @option{--cache-file} argument so that they
8762 share the same cache.  @xref{Subdirectories}, for information on
8763 configuring subdirectories with the @code{AC_CONFIG_SUBDIRS} macro.
8765 @file{config.status} only pays attention to the cache file if it is
8766 given the @option{--recheck} option, which makes it rerun
8767 @command{configure}.
8769 It is wrong to try to distribute cache files for particular system types.
8770 There is too much room for error in doing that, and too much
8771 administrative overhead in maintaining them.  For any features that
8772 can't be guessed automatically, use the standard method of the canonical
8773 system type and linking files (@pxref{Manual Configuration}).
8775 The site initialization script can specify a site-wide cache file to
8776 use, instead of the usual per-program cache.  In this case, the cache
8777 file gradually accumulates information whenever someone runs a new
8778 @command{configure} script.  (Running @command{configure} merges the new cache
8779 results with the existing cache file.)  This may cause problems,
8780 however, if the system configuration (e.g., the installed libraries or
8781 compilers) changes and the stale cache file is not deleted.
8783 @node Cache Checkpointing
8784 @subsection Cache Checkpointing
8786 If your configure script, or a macro called from @file{configure.ac}, happens
8787 to abort the configure process, it may be useful to checkpoint the cache
8788 a few times at key points using @code{AC_CACHE_SAVE}.  Doing so
8789 reduces the amount of time it takes to rerun the configure script with
8790 (hopefully) the error that caused the previous abort corrected.
8792 @c FIXME: Do we really want to document this guy?
8793 @defmac AC_CACHE_LOAD
8794 @acindex{CACHE_LOAD}
8795 Loads values from existing cache file, or creates a new cache file if a
8796 cache file is not found.  Called automatically from @code{AC_INIT}.
8797 @end defmac
8799 @defmac AC_CACHE_SAVE
8800 @acindex{CACHE_SAVE}
8801 Flushes all cached values to the cache file.  Called automatically from
8802 @code{AC_OUTPUT}, but it can be quite useful to call
8803 @code{AC_CACHE_SAVE} at key points in @file{configure.ac}.
8804 @end defmac
8806 For instance:
8808 @example
8809 @r{ @dots{} AC_INIT, etc. @dots{}}
8810 @group
8811 # Checks for programs.
8812 AC_PROG_CC
8813 AC_PROG_AWK
8814 @r{ @dots{} more program checks @dots{}}
8815 AC_CACHE_SAVE
8816 @end group
8818 @group
8819 # Checks for libraries.
8820 AC_CHECK_LIB([nsl], [gethostbyname])
8821 AC_CHECK_LIB([socket], [connect])
8822 @r{ @dots{} more lib checks @dots{}}
8823 AC_CACHE_SAVE
8824 @end group
8826 @group
8827 # Might abort@dots{}
8828 AM_PATH_GTK([1.0.2], [], [AC_MSG_ERROR([GTK not in path])])
8829 AM_PATH_GTKMM([0.9.5], [], [AC_MSG_ERROR([GTK not in path])])
8830 @end group
8831 @r{ @dots{} AC_OUTPUT, etc. @dots{}}
8832 @end example
8834 @node Printing Messages
8835 @section Printing Messages
8836 @cindex Messages, from @command{configure}
8838 @command{configure} scripts need to give users running them several kinds
8839 of information.  The following macros print messages in ways appropriate
8840 for each kind.  The arguments to all of them get enclosed in shell
8841 double quotes, so the shell performs variable and back-quote
8842 substitution on them.
8844 These macros are all wrappers around the @command{echo} shell command.
8845 They direct output to the appropriate file descriptor (@pxref{File
8846 Descriptor Macros}).
8847 @command{configure} scripts should rarely need to run @command{echo} directly
8848 to print messages for the user.  Using these macros makes it easy to
8849 change how and when each kind of message is printed; such changes need
8850 only be made to the macro definitions and all the callers change
8851 automatically.
8853 To diagnose static issues, i.e., when @command{autoconf} is run, see
8854 @ref{Reporting Messages}.
8856 @defmac AC_MSG_CHECKING (@var{feature-description})
8857 @acindex{MSG_CHECKING}
8858 Notify the user that @command{configure} is checking for a particular
8859 feature.  This macro prints a message that starts with @samp{checking }
8860 and ends with @samp{...} and no newline.  It must be followed by a call
8861 to @code{AC_MSG_RESULT} to print the result of the check and the
8862 newline.  The @var{feature-description} should be something like
8863 @samp{whether the Fortran compiler accepts C++ comments} or @samp{for
8864 c89}.
8866 This macro prints nothing if @command{configure} is run with the
8867 @option{--quiet} or @option{--silent} option.
8868 @end defmac
8870 @defmac AC_MSG_RESULT (@var{result-description})
8871 @acindex{MSG_RESULT}
8872 Notify the user of the results of a check.  @var{result-description} is
8873 almost always the value of the cache variable for the check, typically
8874 @samp{yes}, @samp{no}, or a file name.  This macro should follow a call
8875 to @code{AC_MSG_CHECKING}, and the @var{result-description} should be
8876 the completion of the message printed by the call to
8877 @code{AC_MSG_CHECKING}.
8879 This macro prints nothing if @command{configure} is run with the
8880 @option{--quiet} or @option{--silent} option.
8881 @end defmac
8883 @defmac AC_MSG_NOTICE (@var{message})
8884 @acindex{MSG_NOTICE}
8885 Deliver the @var{message} to the user.  It is useful mainly to print a
8886 general description of the overall purpose of a group of feature checks,
8887 e.g.,
8889 @example
8890 AC_MSG_NOTICE([checking if stack overflow is detectable])
8891 @end example
8893 This macro prints nothing if @command{configure} is run with the
8894 @option{--quiet} or @option{--silent} option.
8895 @end defmac
8897 @defmac AC_MSG_ERROR (@var{error-description}, @ovar{exit-status})
8898 @acindex{MSG_ERROR}
8899 Notify the user of an error that prevents @command{configure} from
8900 completing.  This macro prints an error message to the standard error
8901 output and exits @command{configure} with @var{exit-status} (1 by default).
8902 @var{error-description} should be something like @samp{invalid value
8903 $HOME for \$HOME}.
8905 The @var{error-description} should start with a lower-case letter, and
8906 ``cannot'' is preferred to ``can't''.
8907 @end defmac
8909 @defmac AC_MSG_FAILURE (@var{error-description}, @ovar{exit-status})
8910 @acindex{MSG_FAILURE}
8911 This @code{AC_MSG_ERROR} wrapper notifies the user of an error that
8912 prevents @command{configure} from completing @emph{and} that additional
8913 details are provided in @file{config.log}.  This is typically used when
8914 abnormal results are found during a compilation.
8915 @end defmac
8917 @defmac AC_MSG_WARN (@var{problem-description})
8918 @acindex{MSG_WARN}
8919 Notify the @command{configure} user of a possible problem.  This macro
8920 prints the message to the standard error output; @command{configure}
8921 continues running afterward, so macros that call @code{AC_MSG_WARN} should
8922 provide a default (back-up) behavior for the situations they warn about.
8923 @var{problem-description} should be something like @samp{ln -s seems to
8924 make hard links}.
8925 @end defmac
8929 @c ====================================================== Programming in M4.
8931 @node Programming in M4
8932 @chapter Programming in M4
8933 @cindex M4
8935 Autoconf is written on top of two layers: @dfn{M4sugar}, which provides
8936 convenient macros for pure M4 programming, and @dfn{M4sh}, which
8937 provides macros dedicated to shell script generation.
8939 As of this version of Autoconf, these two layers are still experimental,
8940 and their interface might change in the future.  As a matter of fact,
8941 @emph{anything that is not documented must not be used}.
8943 @menu
8944 * M4 Quotation::                Protecting macros from unwanted expansion
8945 * Using autom4te::              The Autoconf executables backbone
8946 * Programming in M4sugar::      Convenient pure M4 macros
8947 * Programming in M4sh::         Common shell Constructs
8948 * File Descriptor Macros::      File descriptor macros for input and output
8949 @end menu
8951 @node M4 Quotation
8952 @section M4 Quotation
8953 @cindex M4 quotation
8954 @cindex quotation
8956 @c FIXME: Grmph, yet another quoting myth: quotation has *never*
8957 @c prevented `expansion' of $1.  Unless it refers to the expansion
8958 @c of the value of $1?  Anyway, we need a rewrite here@enddots{}
8960 The most common problem with existing macros is an improper quotation.
8961 This section, which users of Autoconf can skip, but which macro writers
8962 @emph{must} read, first justifies the quotation scheme that was chosen
8963 for Autoconf and then ends with a rule of thumb.  Understanding the
8964 former helps one to follow the latter.
8966 @menu
8967 * Active Characters::           Characters that change the behavior of M4
8968 * One Macro Call::              Quotation and one macro call
8969 * Quotation and Nested Macros::  Macros calling macros
8970 * Changequote is Evil::         Worse than INTERCAL: M4 + changequote
8971 * Quadrigraphs::                Another way to escape special characters
8972 * Quotation Rule Of Thumb::     One parenthesis, one quote
8973 @end menu
8975 @node Active Characters
8976 @subsection Active Characters
8978 To fully understand where proper quotation is important, you first need
8979 to know what the special characters are in Autoconf: @samp{#} introduces
8980 a comment inside which no macro expansion is performed, @samp{,}
8981 separates arguments, @samp{[} and @samp{]} are the quotes themselves,
8982 and finally @samp{(} and @samp{)} (which M4 tries to match by
8983 pairs).
8985 In order to understand the delicate case of macro calls, we first have
8986 to present some obvious failures.  Below they are ``obvious-ified'',
8987 but when you find them in real life, they are usually in disguise.
8989 Comments, introduced by a hash and running up to the newline, are opaque
8990 tokens to the top level: active characters are turned off, and there is
8991 no macro expansion:
8993 @example
8994 # define([def], ine)
8995 @result{}# define([def], ine)
8996 @end example
8998 Each time there can be a macro expansion, there is a quotation
8999 expansion, i.e., one level of quotes is stripped:
9001 @example
9002 int tab[10];
9003 @result{}int tab10;
9004 [int tab[10];]
9005 @result{}int tab[10];
9006 @end example
9008 Without this in mind, the reader might try hopelessly to use her macro
9009 @code{array}:
9011 @example
9012 define([array], [int tab[10];])
9013 array
9014 @result{}int tab10;
9015 [array]
9016 @result{}array
9017 @end example
9019 @noindent
9020 How can you correctly output the intended results@footnote{Using
9021 @code{defn}.}?
9024 @node One Macro Call
9025 @subsection One Macro Call
9027 Let's proceed on the interaction between active characters and macros
9028 with this small macro, which just returns its first argument:
9030 @example
9031 define([car], [$1])
9032 @end example
9034 @noindent
9035 The two pairs of quotes above are not part of the arguments of
9036 @code{define}; rather, they are understood by the top level when it
9037 tries to find the arguments of @code{define}.  Therefore, assuming
9038 @code{car} is not already defined, it is equivalent to write:
9040 @example
9041 define(car, $1)
9042 @end example
9044 @noindent
9045 But, while it is acceptable for a @file{configure.ac} to avoid unnecessary
9046 quotes, it is bad practice for Autoconf macros which must both be more
9047 robust and also advocate perfect style.
9049 At the top level, there are only two possibilities: either you
9050 quote or you don't:
9052 @example
9053 car(foo, bar, baz)
9054 @result{}foo
9055 [car(foo, bar, baz)]
9056 @result{}car(foo, bar, baz)
9057 @end example
9059 Let's pay attention to the special characters:
9061 @example
9062 car(#)
9063 @error{}EOF in argument list
9064 @end example
9066 The closing parenthesis is hidden in the comment; with a hypothetical
9067 quoting, the top level understood it this way:
9069 @example
9070 car([#)]
9071 @end example
9073 @noindent
9074 Proper quotation, of course, fixes the problem:
9076 @example
9077 car([#])
9078 @result{}#
9079 @end example
9081 Here are more examples:
9083 @example
9084 car(foo, bar)
9085 @result{}foo
9086 car([foo, bar])
9087 @result{}foo, bar
9088 car((foo, bar))
9089 @result{}(foo, bar)
9090 car([(foo], [bar)])
9091 @result{}(foo
9092 define([a], [b])
9093 @result{}
9094 car(a)
9095 @result{}b
9096 car([a])
9097 @result{}b
9098 car([[a]])
9099 @result{}a
9100 car([[[a]]])
9101 @result{}[a]
9102 @end example
9104 With this in mind, we can explore the cases where macros invoke
9105 macros@enddots{}
9108 @node Quotation and Nested Macros
9109 @subsection Quotation and Nested Macros
9111 The examples below use the following macros:
9113 @example
9114 define([car], [$1])
9115 define([active], [ACT, IVE])
9116 define([array], [int tab[10]])
9117 @end example
9119 Each additional embedded macro call introduces other possible
9120 interesting quotations:
9122 @example
9123 car(active)
9124 @result{}ACT
9125 car([active])
9126 @result{}ACT, IVE
9127 car([[active]])
9128 @result{}active
9129 @end example
9131 In the first case, the top level looks for the arguments of @code{car},
9132 and finds @samp{active}.  Because M4 evaluates its arguments
9133 before applying the macro, @samp{active} is expanded, which results in:
9135 @example
9136 car(ACT, IVE)
9137 @result{}ACT
9138 @end example
9140 @noindent
9141 In the second case, the top level gives @samp{active} as first and only
9142 argument of @code{car}, which results in:
9144 @example
9145 active
9146 @result{}ACT, IVE
9147 @end example
9149 @noindent
9150 i.e., the argument is evaluated @emph{after} the macro that invokes it.
9151 In the third case, @code{car} receives @samp{[active]}, which results in:
9153 @example
9154 [active]
9155 @result{}active
9156 @end example
9158 @noindent
9159 exactly as we already saw above.
9161 The example above, applied to a more realistic example, gives:
9163 @example
9164 car(int tab[10];)
9165 @result{}int tab10;
9166 car([int tab[10];])
9167 @result{}int tab10;
9168 car([[int tab[10];]])
9169 @result{}int tab[10];
9170 @end example
9172 @noindent
9173 Huh?  The first case is easily understood, but why is the second wrong,
9174 and the third right?  To understand that, you must know that after
9175 M4 expands a macro, the resulting text is immediately subjected
9176 to macro expansion and quote removal.  This means that the quote removal
9177 occurs twice---first before the argument is passed to the @code{car}
9178 macro, and second after the @code{car} macro expands to the first
9179 argument.
9181 As the author of the Autoconf macro @code{car}, you then consider it to
9182 be incorrect that your users have to double-quote the arguments of
9183 @code{car}, so you ``fix'' your macro.  Let's call it @code{qar} for
9184 quoted car:
9186 @example
9187 define([qar], [[$1]])
9188 @end example
9190 @noindent
9191 and check that @code{qar} is properly fixed:
9193 @example
9194 qar([int tab[10];])
9195 @result{}int tab[10];
9196 @end example
9198 @noindent
9199 Ahhh!  That's much better.
9201 But note what you've done: now that the arguments are literal strings,
9202 if the user wants to use the results of expansions as arguments, she has
9203 to use an @emph{unquoted} macro call:
9205 @example
9206 qar(active)
9207 @result{}ACT
9208 @end example
9210 @noindent
9211 where she wanted to reproduce what she used to do with @code{car}:
9213 @example
9214 car([active])
9215 @result{}ACT, IVE
9216 @end example
9218 @noindent
9219 Worse yet: she wants to use a macro that produces a set of @code{cpp}
9220 macros:
9222 @example
9223 define([my_includes], [#include <stdio.h>])
9224 car([my_includes])
9225 @result{}#include <stdio.h>
9226 qar(my_includes)
9227 @error{}EOF in argument list
9228 @end example
9230 This macro, @code{qar}, because it double quotes its arguments, forces
9231 its users to leave their macro calls unquoted, which is dangerous.
9232 Commas and other active symbols are interpreted by M4 before
9233 they are given to the macro, often not in the way the users expect.
9234 Also, because @code{qar} behaves differently from the other macros,
9235 it's an exception that should be avoided in Autoconf.
9237 @node Changequote is Evil
9238 @subsection @code{changequote} is Evil
9239 @cindex @code{changequote}
9241 The temptation is often high to bypass proper quotation, in particular
9242 when it's late at night.  Then, many experienced Autoconf hackers
9243 finally surrender to the dark side of the force and use the ultimate
9244 weapon: @code{changequote}.
9246 The M4 builtin @code{changequote} belongs to a set of primitives that
9247 allow one to adjust the syntax of the language to adjust it to one's
9248 needs.  For instance, by default M4 uses @samp{`} and @samp{'} as
9249 quotes, but in the context of shell programming (and actually of most
9250 programming languages), that's about the worst choice one can make:
9251 because of strings and back-quoted expressions in shell code (such as
9252 @samp{'this'} and @samp{`that`}), because of literal characters in usual
9253 programming languages (as in @samp{'0'}), there are many unbalanced
9254 @samp{`} and @samp{'}.  Proper M4 quotation then becomes a nightmare, if
9255 not impossible.  In order to make M4 useful in such a context, its
9256 designers have equipped it with @code{changequote}, which makes it
9257 possible to choose another pair of quotes.  M4sugar, M4sh, Autoconf, and
9258 Autotest all have chosen to use @samp{[} and @samp{]}.  Not especially
9259 because they are unlikely characters, but @emph{because they are
9260 characters unlikely to be unbalanced}.
9262 There are other magic primitives, such as @code{changecom} to specify
9263 what syntactic forms are comments (it is common to see
9264 @samp{changecom(<!--, -->)} when M4 is used to produce HTML pages),
9265 @code{changeword} and @code{changesyntax} to change other syntactic
9266 details (such as the character to denote the @var{n}th argument, @samp{$} by
9267 default, the parenthesis around arguments, etc.).
9269 These primitives are really meant to make M4 more useful for specific
9270 domains: they should be considered like command line options:
9271 @option{--quotes}, @option{--comments}, @option{--words}, and
9272 @option{--syntax}.  Nevertheless, they are implemented as M4 builtins, as
9273 it makes M4 libraries self contained (no need for additional options).
9275 There lies the problem@enddots{}
9277 @sp 1
9279 The problem is that it is then tempting to use them in the middle of an
9280 M4 script, as opposed to its initialization.  This, if not carefully
9281 thought out, can lead to disastrous effects: @emph{you are changing the
9282 language in the middle of the execution}.  Changing and restoring the
9283 syntax is often not enough: if you happened to invoke macros in between,
9284 these macros are lost, as the current syntax is probably not
9285 the one they were implemented with.
9287 @c FIXME: I've been looking for a short, real case example, but I
9288 @c lost them all :(
9291 @node Quadrigraphs
9292 @subsection Quadrigraphs
9293 @cindex quadrigraphs
9294 @cindex @samp{@@S|@@}
9295 @cindex @samp{@@&t@@}
9296 @c Info cannot handle `:' in index entries.
9297 @c @cindex @samp{@@<:@@}
9298 @c @cindex @samp{@@:>@@}
9299 @c @cindex @samp{@@%:@@}
9301 When writing an Autoconf macro you may occasionally need to generate
9302 special characters that are difficult to express with the standard
9303 Autoconf quoting rules.  For example, you may need to output the regular
9304 expression @samp{[^[]}, which matches any character other than @samp{[}.
9305 This expression contains unbalanced brackets so it cannot be put easily
9306 into an M4 macro.
9308 You can work around this problem by using one of the following
9309 @dfn{quadrigraphs}:
9311 @table @samp
9312 @item @@<:@@
9313 @samp{[}
9314 @item @@:>@@
9315 @samp{]}
9316 @item @@S|@@
9317 @samp{$}
9318 @item @@%:@@
9319 @samp{#}
9320 @item @@&t@@
9321 Expands to nothing.
9322 @end table
9324 Quadrigraphs are replaced at a late stage of the translation process,
9325 after @command{m4} is run, so they do not get in the way of M4 quoting.
9326 For example, the string @samp{^@@<:@@}, independently of its quotation,
9327 appears as @samp{^[} in the output.
9329 The empty quadrigraph can be used:
9331 @itemize @minus
9332 @item to mark trailing spaces explicitly
9334 Trailing spaces are smashed by @command{autom4te}.  This is a feature.
9336 @item to produce other quadrigraphs
9338 For instance @samp{@@<@@&t@@:@@} produces @samp{@@<:@@}.
9340 @item to escape @emph{occurrences} of forbidden patterns
9342 For instance you might want to mention @code{AC_FOO} in a comment, while
9343 still being sure that @command{autom4te} still catches unexpanded
9344 @samp{AC_*}.  Then write @samp{AC@@&t@@_FOO}.
9345 @end itemize
9347 The name @samp{@@&t@@} was suggested by Paul Eggert:
9349 @quotation
9350 I should give some credit to the @samp{@@&t@@} pun.  The @samp{&} is my
9351 own invention, but the @samp{t} came from the source code of the
9352 @sc{algol68c} compiler, written by Steve Bourne (of Bourne shell fame),
9353 and which used @samp{mt} to denote the empty string.  In C, it would
9354 have looked like something like:
9356 @example
9357 char const mt[] = "";
9358 @end example
9360 @noindent
9361 but of course the source code was written in Algol 68.
9363 I don't know where he got @samp{mt} from: it could have been his own
9364 invention, and I suppose it could have been a common pun around the
9365 Cambridge University computer lab at the time.
9366 @end quotation
9368 @node Quotation Rule Of Thumb
9369 @subsection Quotation Rule Of Thumb
9371 To conclude, the quotation rule of thumb is:
9373 @center @emph{One pair of quotes per pair of parentheses.}
9375 Never over-quote, never under-quote, in particular in the definition of
9376 macros.  In the few places where the macros need to use brackets
9377 (usually in C program text or regular expressions), properly quote
9378 @emph{the arguments}!
9380 It is common to read Autoconf programs with snippets like:
9382 @example
9383 AC_TRY_LINK(
9384 changequote(<<, >>)dnl
9385 <<#include <time.h>
9386 #ifndef tzname /* For SGI.  */
9387 extern char *tzname[]; /* RS6000 and others reject char **tzname.  */
9388 #endif>>,
9389 changequote([, ])dnl
9390 [atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)
9391 @end example
9393 @noindent
9394 which is incredibly useless since @code{AC_TRY_LINK} is @emph{already}
9395 double quoting, so you just need:
9397 @example
9398 AC_TRY_LINK(
9399 [#include <time.h>
9400 #ifndef tzname /* For SGI.  */
9401 extern char *tzname[]; /* RS6000 and others reject char **tzname.  */
9402 #endif],
9403             [atoi (*tzname);],
9404             [ac_cv_var_tzname=yes],
9405             [ac_cv_var_tzname=no])
9406 @end example
9408 @noindent
9409 The M4-fluent reader might note that these two examples are rigorously
9410 equivalent, since M4 swallows both the @samp{changequote(<<, >>)}
9411 and @samp{<<} @samp{>>} when it @dfn{collects} the arguments: these
9412 quotes are not part of the arguments!
9414 Simplified, the example above is just doing this:
9416 @example
9417 changequote(<<, >>)dnl
9418 <<[]>>
9419 changequote([, ])dnl
9420 @end example
9422 @noindent
9423 instead of simply:
9425 @example
9426 [[]]
9427 @end example
9429 With macros that do not double quote their arguments (which is the
9430 rule), double-quote the (risky) literals:
9432 @example
9433 AC_LINK_IFELSE([AC_LANG_PROGRAM(
9434 [[#include <time.h>
9435 #ifndef tzname /* For SGI.  */
9436 extern char *tzname[]; /* RS6000 and others reject char **tzname.  */
9437 #endif]],
9438                                 [atoi (*tzname);])],
9439                [ac_cv_var_tzname=yes],
9440                [ac_cv_var_tzname=no])
9441 @end example
9443 Please note that the macro @code{AC_TRY_LINK} is obsolete, so you really
9444 should be using @code{AC_LINK_IFELSE} instead.
9446 @xref{Quadrigraphs}, for what to do if you run into a hopeless case
9447 where quoting does not suffice.
9449 When you create a @command{configure} script using newly written macros,
9450 examine it carefully to check whether you need to add more quotes in
9451 your macros.  If one or more words have disappeared in the M4
9452 output, you need more quotes.  When in doubt, quote.
9454 However, it's also possible to put on too many layers of quotes.  If
9455 this happens, the resulting @command{configure} script may contain
9456 unexpanded macros.  The @command{autoconf} program checks for this problem
9457 by looking for the string @samp{AC_} in @file{configure}.  However, this
9458 heuristic does not work in general: for example, it does not catch
9459 overquoting in @code{AC_DEFINE} descriptions.
9462 @c ---------------------------------------- Using autom4te
9464 @node Using autom4te
9465 @section Using @command{autom4te}
9467 The Autoconf suite, including M4sugar, M4sh, and Autotest, in addition
9468 to Autoconf per se, heavily rely on M4.  All these different uses
9469 revealed common needs factored into a layer over M4:
9470 @command{autom4te}@footnote{
9472 Yet another great name from Lars J. Aas.
9476 @command{autom4te} is a preprocessor that is like @command{m4}.
9477 It supports M4 extensions designed for use in tools like Autoconf.
9479 @menu
9480 * autom4te Invocation::         A @acronym{GNU} M4 wrapper
9481 * Customizing autom4te::        Customizing the Autoconf package
9482 @end menu
9484 @node autom4te Invocation
9485 @subsection Invoking @command{autom4te}
9487 The command line arguments are modeled after M4's:
9489 @example
9490 autom4te @var{options} @var{files}
9491 @end example
9493 @noindent
9494 @evindex M4
9495 where the @var{files} are directly passed to @command{m4}.  By default,
9496 @acronym{GNU} M4 is found during configuration, but the environment
9497 variable
9498 @env{M4} can be set to tell @command{autom4te} where to look.  In addition
9499 to the regular expansion, it handles the replacement of the quadrigraphs
9500 (@pxref{Quadrigraphs}), and of @samp{__oline__}, the current line in the
9501 output.  It supports an extended syntax for the @var{files}:
9503 @table @file
9504 @item @var{file}.m4f
9505 This file is an M4 frozen file.  Note that @emph{all the previous files
9506 are ignored}.  See the option @option{--melt} for the rationale.
9508 @item @var{file}?
9509 If found in the library path, the @var{file} is included for expansion,
9510 otherwise it is ignored instead of triggering a failure.
9511 @end table
9513 @sp 1
9515 Of course, it supports the Autoconf common subset of options:
9517 @table @option
9518 @item --help
9519 @itemx -h
9520 Print a summary of the command line options and exit.
9522 @item --version
9523 @itemx -V
9524 Print the version number of Autoconf and exit.
9526 @item --verbose
9527 @itemx -v
9528 Report processing steps.
9530 @item --debug
9531 @itemx -d
9532 Don't remove the temporary files and be even more verbose.
9534 @item --include=@var{dir}
9535 @itemx -I @var{dir}
9536 Also look for input files in @var{dir}.  Multiple invocations
9537 accumulate.
9539 @item --output=@var{file}
9540 @itemx -o @var{file}
9541 Save output (script or trace) to @var{file}.  The file @option{-} stands
9542 for the standard output.
9543 @end table
9545 @sp 1
9547 As an extension of @command{m4}, it includes the following options:
9549 @table @option
9550 @item --warnings=@var{category}
9551 @itemx -W @var{category}
9552 @evindex WARNINGS
9553 @c FIXME: Point to the M4sugar macros, not Autoconf's.
9554 Report the warnings related to @var{category} (which can actually be a
9555 comma separated list).  @xref{Reporting Messages}, macro
9556 @code{AC_DIAGNOSE}, for a comprehensive list of categories.  Special
9557 values include:
9559 @table @samp
9560 @item all
9561 report all the warnings
9563 @item none
9564 report none
9566 @item error
9567 treats warnings as errors
9569 @item no-@var{category}
9570 disable warnings falling into @var{category}
9571 @end table
9573 Warnings about @samp{syntax} are enabled by default, and the environment
9574 variable @env{WARNINGS}, a comma separated list of categories, is
9575 honored.  @samp{autom4te -W @var{category}} actually
9576 behaves as if you had run:
9578 @example
9579 autom4te --warnings=syntax,$WARNINGS,@var{category}
9580 @end example
9582 @noindent
9583 For example, if you want to disable defaults and @env{WARNINGS}
9584 of @command{autom4te}, but enable the warnings about obsolete
9585 constructs, you would use @option{-W none,obsolete}.
9587 @cindex Back trace
9588 @cindex Macro invocation stack
9589 @command{autom4te} displays a back trace for errors, but not for
9590 warnings; if you want them, just pass @option{-W error}.
9592 @item --melt
9593 @itemx -M
9594 Do not use frozen files.  Any argument @code{@var{file}.m4f} is
9595 replaced by @code{@var{file}.m4}.  This helps tracing the macros which
9596 are executed only when the files are frozen, typically
9597 @code{m4_define}.  For instance, running:
9599 @example
9600 autom4te --melt 1.m4 2.m4f 3.m4 4.m4f input.m4
9601 @end example
9603 @noindent
9604 is roughly equivalent to running:
9606 @example
9607 m4 1.m4 2.m4 3.m4 4.m4 input.m4
9608 @end example
9610 @noindent
9611 while
9613 @example
9614 autom4te 1.m4 2.m4f 3.m4 4.m4f input.m4
9615 @end example
9617 @noindent
9618 is equivalent to:
9620 @example
9621 m4 --reload-state=4.m4f input.m4
9622 @end example
9624 @item --freeze
9625 @itemx -f
9626 Produce a frozen state file.  @command{autom4te} freezing is stricter
9627 than M4's: it must produce no warnings, and no output other than empty
9628 lines (a line with white space is @emph{not} empty) and comments
9629 (starting with @samp{#}).  Unlike @command{m4}'s similarly-named option,
9630 this option takes no argument:
9632 @example
9633 autom4te 1.m4 2.m4 3.m4 --freeze --output=3.m4f
9634 @end example
9636 @noindent
9637 corresponds to
9639 @example
9640 m4 1.m4 2.m4 3.m4 --freeze-state=3.m4f
9641 @end example
9643 @item --mode=@var{octal-mode}
9644 @itemx -m @var{octal-mode}
9645 Set the mode of the non-traces output to @var{octal-mode}; by default
9646 @samp{0666}.
9647 @end table
9649 @sp 1
9651 @cindex @file{autom4te.cache}
9652 As another additional feature over @command{m4}, @command{autom4te}
9653 caches its results.  @acronym{GNU} M4 is able to produce a regular
9654 output and traces at the same time.  Traces are heavily used in the
9655 @acronym{GNU} Build System: @command{autoheader} uses them to build
9656 @file{config.h.in}, @command{autoreconf} to determine what
9657 @acronym{GNU} Build System components are used, @command{automake} to
9658 ``parse'' @file{configure.ac} etc.  To avoid recomputation,
9659 traces are cached while performing regular expansion,
9660 and conversely.  This cache is (actually, the caches are) stored in
9661 the directory @file{autom4te.cache}.  @emph{It can safely be removed}
9662 at any moment (especially if for some reason @command{autom4te}
9663 considers it is trashed).
9665 @table @option
9666 @item --cache=@var{directory}
9667 @itemx -C @var{directory}
9668 Specify the name of the directory where the result should be cached.
9669 Passing an empty value disables caching.  Be sure to pass a relative
9670 file name, as for the time being, global caches are not supported.
9672 @item --no-cache
9673 Don't cache the results.
9675 @item --force
9676 @itemx -f
9677 If a cache is used, consider it obsolete (but update it anyway).
9678 @end table
9680 @sp 1
9682 Because traces are so important to the @acronym{GNU} Build System,
9683 @command{autom4te} provides high level tracing features as compared to
9684 M4, and helps exploiting the cache:
9686 @table @option
9687 @item --trace=@var{macro}[:@var{format}]
9688 @itemx -t @var{macro}[:@var{format}]
9689 Trace the invocations of @var{macro} according to the @var{format}.
9690 Multiple @option{--trace} arguments can be used to list several macros.
9691 Multiple @option{--trace} arguments for a single macro are not
9692 cumulative; instead, you should just make @var{format} as long as
9693 needed.
9695 The @var{format} is a regular string, with newlines if desired, and
9696 several special escape codes.  It defaults to @samp{$f:$l:$n:$%}.  It can
9697 use the following special escapes:
9699 @table @samp
9700 @item $$
9701 The character @samp{$}.
9703 @item $f
9704 The file name from which @var{macro} is called.
9706 @item $l
9707 The line number from which @var{macro} is called.
9709 @item $d
9710 The depth of the @var{macro} call.  This is an M4 technical detail that
9711 you probably don't want to know about.
9713 @item $n
9714 The name of the @var{macro}.
9716 @item $@var{num}
9717 The @var{num}th argument of the call to @var{macro}.
9719 @item $@@
9720 @itemx $@var{sep}@@
9721 @itemx $@{@var{separator}@}@@
9722 All the arguments passed to @var{macro}, separated by the character
9723 @var{sep} or the string @var{separator} (@samp{,} by default).  Each
9724 argument is quoted, i.e., enclosed in a pair of square brackets.
9726 @item $*
9727 @itemx $@var{sep}*
9728 @itemx $@{@var{separator}@}*
9729 As above, but the arguments are not quoted.
9731 @item $%
9732 @itemx $@var{sep}%
9733 @itemx $@{@var{separator}@}%
9734 As above, but the arguments are not quoted, all new line characters in
9735 the arguments are smashed, and the default separator is @samp{:}.
9737 The escape @samp{$%} produces single-line trace outputs (unless you put
9738 newlines in the @samp{separator}), while @samp{$@@} and @samp{$*} do
9739 not.
9740 @end table
9742 @xref{autoconf Invocation}, for examples of trace uses.
9744 @item --preselect=@var{macro}
9745 @itemx -p @var{macro}
9746 Cache the traces of @var{macro}, but do not enable traces.  This is
9747 especially important to save CPU cycles in the future.  For instance,
9748 when invoked, @command{autoconf} preselects all the macros that
9749 @command{autoheader}, @command{automake}, @command{autoreconf}, etc.,
9750 trace, so that running @command{m4} is not needed to trace them: the
9751 cache suffices.  This results in a huge speed-up.
9752 @end table
9754 @sp 1
9756 @cindex Autom4te Library
9757 Finally, @command{autom4te} introduces the concept of @dfn{Autom4te
9758 libraries}.  They consists in a powerful yet extremely simple feature:
9759 sets of combined command line arguments:
9761 @table @option
9762 @item --language=@var{language}
9763 @itemx -l @var{language}
9764 Use the @var{language} Autom4te library.  Current languages include:
9766 @table @code
9767 @item M4sugar
9768 create M4sugar output.
9770 @item M4sh
9771 create M4sh executable shell scripts.
9773 @item Autotest
9774 create Autotest executable test suites.
9776 @item Autoconf-without-aclocal-m4
9777 create Autoconf executable configure scripts without
9778 reading @file{aclocal.m4}.
9780 @item Autoconf
9781 create Autoconf executable configure scripts.  This language inherits
9782 all the characteristics of @code{Autoconf-without-aclocal-m4} and
9783 additionally reads @file{aclocal.m4}.
9784 @end table
9786 @item --prepend-include=@var{dir}
9787 @item -B @var{dir}
9788 Prepend directory @var{dir} to the search path.  This is used to include
9789 the language-specific files before any third-party macros.
9791 @end table
9793 @cindex @file{autom4te.cfg}
9794 As an example, if Autoconf is installed in its default location,
9795 @file{/usr/local}, the command @samp{autom4te -l m4sugar foo.m4} is
9796 strictly equivalent to the command:
9798 @example
9799 autom4te --prepend-include /usr/local/share/autoconf \
9800   m4sugar/m4sugar.m4f --warnings syntax foo.m4
9801 @end example
9803 @noindent
9804 Recursive expansion applies here: the command @samp{autom4te -l m4sh foo.m4}
9805 is the same as @samp{autom4te --language M4sugar m4sugar/m4sh.m4f
9806 foo.m4}, i.e.:
9808 @example
9809 autom4te --prepend-include /usr/local/share/autoconf \
9810   m4sugar/m4sugar.m4f m4sugar/m4sh.m4f --mode 777 foo.m4
9811 @end example
9813 @noindent
9814 The definition of the languages is stored in @file{autom4te.cfg}.
9816 @node Customizing autom4te
9817 @subsection Customizing @command{autom4te}
9819 One can customize @command{autom4te} via @file{~/.autom4te.cfg} (i.e.,
9820 as found in the user home directory), and @file{./.autom4te.cfg} (i.e.,
9821 as found in the directory from which @command{autom4te} is run).  The
9822 order is first reading @file{autom4te.cfg}, then @file{~/.autom4te.cfg},
9823 then @file{./.autom4te.cfg}, and finally the command line arguments.
9825 In these text files, comments are introduced with @code{#}, and empty
9826 lines are ignored.  Customization is performed on a per-language basis,
9827 wrapped in between a @samp{begin-language: "@var{language}"},
9828 @samp{end-language: "@var{language}"} pair.
9830 Customizing a language stands for appending options (@pxref{autom4te
9831 Invocation}) to the current definition of the language.  Options, and
9832 more generally arguments, are introduced by @samp{args:
9833 @var{arguments}}.  You may use the traditional shell syntax to quote the
9834 @var{arguments}.
9836 As an example, to disable Autoconf caches (@file{autom4te.cache})
9837 globally, include the following lines in @file{~/.autom4te.cfg}:
9839 @verbatim
9840 ## ------------------ ##
9841 ## User Preferences.  ##
9842 ## ------------------ ##
9844 begin-language: "Autoconf-without-aclocal-m4"
9845 args: --no-cache
9846 end-language: "Autoconf-without-aclocal-m4"
9847 @end verbatim
9850 @node Programming in M4sugar
9851 @section Programming in M4sugar
9853 @cindex M4sugar
9854 M4 by itself provides only a small, but sufficient, set of all-purpose
9855 macros.  M4sugar introduces additional generic macros.  Its name was
9856 coined by Lars J. Aas: ``Readability And Greater Understanding Stands 4
9857 M4sugar''.
9859 @menu
9860 * Redefined M4 Macros::         M4 builtins changed in M4sugar
9861 * Looping constructs::          Iteration in M4
9862 * Evaluation Macros::           More quotation and evaluation control
9863 * Text processing Macros::      String manipulation in M4
9864 * Forbidden Patterns::          Catching unexpanded macros
9865 @end menu
9867 @node Redefined M4 Macros
9868 @subsection Redefined M4 Macros
9870 @msindex{builtin}
9871 @msindex{decr}
9872 @msindex{define}
9873 @msindex{dumpdef}
9874 @msindex{errprint}
9875 @msindex{esyscmd}
9876 @msindex{eval}
9877 @msindex{format}
9878 @msindex{ifdef}
9879 @msindex{incr}
9880 @msindex{index}
9881 @msindex{indir}
9882 @msindex{len}
9883 @msindex{pushdef}
9884 @msindex{shift}
9885 @msindex{substr}
9886 @msindex{syscmd}
9887 @msindex{sysval}
9888 @msindex{translit}
9889 @msindex{undefine}
9890 With a few exceptions, all the M4 native macros are moved in the
9891 @samp{m4_} pseudo-namespace, e.g., M4sugar renames @code{define} as
9892 @code{m4_define} etc.
9894 Some M4 macros are redefined, and are slightly incompatible with their
9895 native equivalent.
9897 @defmac dnl
9898 @msindex{dnl}
9899 This macro kept its original name: no @code{m4_dnl} is defined.
9900 @end defmac
9902 @defmac m4_defn (@var{macro})
9903 @msindex{defn}
9904 Unlike the M4 builtin, this macro fails if @var{macro} is not
9905 defined.  See @code{m4_undefine}.
9906 @end defmac
9908 @defmac m4_exit (@var{exit-status})
9909 @msindex{exit}
9910 This macro corresponds to @code{m4exit}.
9911 @end defmac
9913 @defmac m4_if (@var{comment})
9914 @defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @ovar{not-equal})
9915 @defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @dots{})
9916 @msindex{if}
9917 This macro corresponds to @code{ifelse}.
9918 @end defmac
9920 @defmac m4_include (@var{file})
9921 @defmacx m4_sinclude (@var{file})
9922 @msindex{include}
9923 @msindex{sinclude}
9924 Like the M4 builtins, but warn against multiple inclusions of @var{file}.
9925 @end defmac
9927 @defmac m4_bpatsubst (@var{string}, @var{regexp}, @ovar{replacement})
9928 @msindex{bpatsubst}
9929 This macro corresponds to @code{patsubst}.  The name @code{m4_patsubst}
9930 is kept for future versions of M4sh, on top of @acronym{GNU} M4 which will
9931 provide extended regular expression syntax via @code{epatsubst}.
9932 @end defmac
9934 @defmac m4_popdef (@var{macro})
9935 @msindex{popdef}
9936 Unlike the M4 builtin, this macro fails if @var{macro} is not
9937 defined.  See @code{m4_undefine}.
9938 @end defmac
9940 @defmac m4_bregexp (@var{string}, @var{regexp}, @ovar{replacement})
9941 @msindex{bregexp}
9942 This macro corresponds to @code{regexp}.  The name @code{m4_regexp}
9943 is kept for future versions of M4sh, on top of @acronym{GNU} M4 which will
9944 provide extended regular expression syntax via @code{eregexp}.
9945 @end defmac
9947 @defmac m4_wrap (@var{text})
9948 @msindex{wrap}
9949 This macro corresponds to @code{m4wrap}.
9951 Posix requires arguments of multiple @code{m4wrap} calls to be
9952 reprocessed at @acronym{EOF} in the same order as the original calls.
9953 @acronym{GNU} M4 versions through 1.4.x, however, reprocess them in
9954 reverse order.  Your code should not depend on the order.
9956 Also, Posix requires @code{m4wrap} to ignore its second and succeeding
9957 arguments, but @acronym{GNU} M4 versions through 1.4.x concatenate the
9958 arguments with intervening spaces.  Your code should not pass more than
9959 one argument.
9961 You are encouraged to end @var{text} with @samp{[]}, to avoid unexpected
9962 token pasting between consecutive invocations of @code{m4_wrap}, as in:
9964 @example
9965 m4_define([foo], [bar])
9966 m4_define([foofoo], [OUCH])
9967 m4_wrap([foo])
9968 m4_wrap([foo])
9969 @result{}OUCH
9970 @end example
9971 @end defmac
9973 @defmac m4_undefine (@var{macro})
9974 @msindex{undefine}
9975 Unlike the M4 builtin, this macro fails if @var{macro} is not
9976 defined.  Use
9978 @example
9979 m4_ifdef([@var{macro}], [m4_undefine([@var{macro}])])
9980 @end example
9982 @noindent
9983 to recover the behavior of the builtin.
9984 @end defmac
9986 @defmac m4_maketemp (@var{template})
9987 @defmacx m4_mkstemp (@var{template})
9988 @msindex{maketemp}
9989 @msindex{mkstemp}
9990 Posix requires @code{maketemp} to replace the trailing @samp{X}
9991 characters in @var{template} with the process id, without regards to the
9992 existence of a file by that name, but this a security hole.  When this
9993 was pointed out to the Posix folks, they agreed to invent a new macro
9994 @code{mkstemp} that always creates a uniquely named file, but not all
9995 versions of @acronym{GNU} M4 support the new macro.  In M4sugar,
9996 @code{m4_maketemp} and @code{m4_mkstemp} are synonyms for each other,
9997 and both have the secure semantics regardless of which macro the
9998 underlying M4 provides.
9999 @end defmac
10002 @node Looping constructs
10003 @subsection Looping constructs
10005 The following macros implement loops in M4.
10007 @defmac m4_for (@var{var}, @var{first}, @var{last}, @ovar{step}, @var{expression})
10008 @msindex{for}
10009 Loop over the numeric values between @var{first} and @var{last}
10010 including bounds by increments of @var{step}.  For each iteration,
10011 expand @var{expression} with the numeric value assigned to @var{var}.
10012 If @var{step} is omitted, it defaults to @samp{1} or @samp{-1} depending
10013 on the order of the limits.  If given, @var{step} has to match this
10014 order.
10015 @end defmac
10017 @defmac m4_foreach (@var{var}, @var{list}, @var{expression})
10018 @msindex{foreach}
10019 Loop over the comma-separated M4 list @var{list}, assigning each value
10020 to @var{var}, and expand @var{expression}.  The following example
10021 outputs two lines:
10023 @example
10024 m4_foreach([myvar], [[foo], [bar, baz]],
10025            [echo myvar
10028 @end example
10029 @end defmac
10031 @defmac m4_foreach_w (@var{var}, @var{list}, @var{expression})
10032 @msindex{foreach_w}
10033 Loop over the white-space-separated list @var{list}, assigning each value
10034 to @var{var}, and expand @var{expression}.
10036 The deprecated macro @code{AC_FOREACH} is an alias of
10037 @code{m4_foreach_w}.
10038 @end defmac
10042 @node Evaluation Macros
10043 @subsection Evaluation Macros
10045 The following macros give some control over the order of the evaluation
10046 by adding or removing levels of quotes.  They are meant for hard-core M4
10047 programmers.
10049 @defmac m4_dquote (@var{arg1}, @dots{})
10050 @msindex{dquote}
10051 Return the arguments as a quoted list of quoted arguments.
10052 @end defmac
10054 @defmac m4_quote (@var{arg1}, @dots{})
10055 @msindex{quote}
10056 Return the arguments as a single entity, i.e., wrap them into a pair of
10057 quotes.
10058 @end defmac
10060 The following example aims at emphasizing the difference between (i), not
10061 using these macros, (ii), using @code{m4_quote}, and (iii), using
10062 @code{m4_dquote}.
10064 @example
10065 $ @kbd{cat example.m4}
10066 # Overquote, so that quotes are visible.
10067 m4_define([show], [$[]1 = [$1], $[]@@ = [$@@]])
10068 m4_define([mkargs], [1, 2, 3])
10069 m4_define([arg1], [[$1]])
10070 m4_divert(0)dnl
10071 show(a, b)
10072 show(m4_quote(a, b))
10073 show(m4_dquote(a, b))
10074 arg1(mkargs)
10075 arg1([mkargs])
10076 arg1(m4_defn([mkargs]))
10077 arg1(m4_quote(mkargs))
10078 arg1(m4_dquote(mkargs))
10079 $ @kbd{autom4te -l m4sugar example.m4}
10080 $1 = a, $@@ = [a],[b]
10081 $1 = a,b, $@@ = [a,b]
10082 $1 = [a],[b], $@@ = [[a],[b]]
10084 mkargs
10085 1, 2, 3
10086 1,2,3
10087 [1],[2],[3]
10088 @end example
10092 @node Text processing Macros
10093 @subsection Text processing Macros
10095 The following macros may be used to manipulate strings in M4.
10096 They are not intended for casual use.
10098 @defmac m4_re_escape (@var{string})
10099 @msindex{re_escape}
10100 Backslash-escape all characters in @var{string} that are active in
10101 regexps.
10102 @end defmac
10104 @defmac m4_tolower (@var{string})
10105 @defmacx m4_toupper (@var{string})
10106 @msindex{tolower}
10107 @msindex{toupper}
10108 Return @var{string} with letters converted to upper or lower case,
10109 respectively.
10110 @end defmac
10112 @defmac m4_split (@var{string}, @ovar{regexp})
10113 @msindex{split}
10114 Split @var{string} into an M4 list of elements quoted by @samp{[} and
10115 @samp{]}, while keeping white space at the beginning and at the end.
10116 If @var{regexp} is given, use it instead of @samp{[\t ]+} for splitting.
10117 If @var{string} is empty, the result is an empty list.
10118 @end defmac
10120 @defmac m4_normalize (@var{string})
10121 @msindex{normalize}
10122 Remove leading and trailing spaces and tabs, sequences of
10123 backslash-then-newline, and replace multiple spaces and tabs with a
10124 single space.
10125 @end defmac
10127 @defmac m4_append (@var{macro-name}, @var{string}, @ovar{separator})
10128 @defmacx m4_append_uniq (@var{macro-name}, @var{string}, @ovar{separator})
10129 @msindex{append}
10130 @msindex{append_uniq}
10131 Redefine @var{macro-name} to its former contents with @var{separator}
10132 and @var{string} added at the end.  If @var{macro-name} was undefined
10133 before (but not if it was defined but empty), then no @var{separator} is
10134 added.  @code{m4_append} can be used to grow strings, and
10135 @code{m4_append_uniq} to grow strings without duplicating substrings.
10136 @end defmac
10140 @node Forbidden Patterns
10141 @subsection Forbidden Patterns
10142 @cindex Forbidden patterns
10143 @cindex Patterns, forbidden
10145 M4sugar provides a means to define suspicious patterns, patterns
10146 describing tokens which should not be found in the output.  For
10147 instance, if an Autoconf @file{configure} script includes tokens such as
10148 @samp{AC_DEFINE}, or @samp{dnl}, then most probably something went
10149 wrong (typically a macro was not evaluated because of overquotation).
10151 M4sugar forbids all the tokens matching @samp{^m4_} and @samp{^dnl$}.
10153 @defmac m4_pattern_forbid (@var{pattern})
10154 @msindex{pattern_forbid}
10155 Declare that no token matching @var{pattern} must be found in the output.
10156 Comments are not checked; this can be a problem if, for instance, you
10157 have some macro left unexpanded after an @samp{#include}.  No consensus
10158 is currently found in the Autoconf community, as some people consider it
10159 should be valid to name macros in comments (which doesn't make sense to
10160 the author of this documentation, as @samp{#}-comments should document
10161 the output, not the input, documented by @samp{dnl} comments).
10162 @end defmac
10164 Of course, you might encounter exceptions to these generic rules, for
10165 instance you might have to refer to @samp{$m4_flags}.
10167 @defmac m4_pattern_allow (@var{pattern})
10168 @msindex{pattern_allow}
10169 Any token matching @var{pattern} is allowed, including if it matches an
10170 @code{m4_pattern_forbid} pattern.
10171 @end defmac
10173 @node Programming in M4sh
10174 @section Programming in M4sh
10176 @c FIXME: Eventually will become a chapter, as it is not related to
10177 @c programming in M4 per se.
10179 M4sh, pronounced ``mash'', is aiming at producing portable Bourne shell
10180 scripts.  This name was coined by Lars J. Aas, who notes that,
10181 according to the Webster's Revised Unabridged Dictionary (1913):
10183 @quotation
10184 Mash \Mash\, n.  [Akin to G. meisch, maisch, meische, maische, mash,
10185 wash, and prob.@: to AS. miscian to mix.  See ``Mix''.]
10187 @enumerate 1
10188 @item
10189 A mass of mixed ingredients reduced to a soft pulpy state by beating or
10190 pressure@enddots{}
10192 @item
10193 A mixture of meal or bran and water fed to animals.
10195 @item
10196 A mess; trouble.  [Obs.] --Beau.@: & Fl.
10197 @end enumerate
10198 @end quotation
10201 For the time being, it is not mature enough to be widely used.
10203 M4sh provides portable alternatives for some common shell constructs
10204 that unfortunately are not portable in practice.
10206 @c Deprecated, to be replaced by a better API
10207 @ignore
10208 @defmac AS_BASENAME (@var{file-name})
10209 @asindex{BASENAME}
10210 Output the non-directory portion of @var{file-name}.  For example,
10211 if @code{$file} is @samp{/one/two/three}, the command
10212 @code{base=`AS_BASENAME(["$file"])`} sets @code{base} to @samp{three}.
10213 @end defmac
10214 @end ignore
10216 @defmac AS_BOURNE_COMPATIBLE
10217 @asindex{BOURNE_COMPATIBLE}
10218 Set up the shell to be more compatible with the Bourne shell as
10219 standardized by Posix, if possible.  This may involve setting
10220 environment variables, or setting options, or similar
10221 implementation-specific actions.
10222 @end defmac
10224 @defmac AS_CASE (@var{word}, @ovar{pattern1}, @ovar{if-matched1}, @dots{}, @ovar{default})
10225 @asindex{CASE}
10226 Expand into a shell @samp{case} statement, where @var{word} is matched
10227 against one or more patterns.  @var{if-matched} is run if the
10228 corresponding pattern matched @var{word}, else @var{default} is run.
10229 @end defmac
10231 @defmac AS_DIRNAME (@var{file-name})
10232 @asindex{DIRNAME}
10233 Output the directory portion of @var{file-name}.  For example,
10234 if @code{$file} is @samp{/one/two/three}, the command
10235 @code{dir=`AS_DIRNAME(["$file"])`} sets @code{dir} to @samp{/one/two}.
10236 @end defmac
10238 @defmac AS_IF (@var{test1}, @ovar{run-if-true1}, @dots{}, @ovar{run-if-false})
10239 @asindex{IF}
10240 Run shell code @var{test1}.  If @var{test1} exits with a zero status then
10241 run shell code @var{run-if-true1}, else examine further tests.  If no test
10242 exits with a zero status, run shell code @var{run-if-false}, with
10243 simplifications if either @var{run-if-true1} or @var{run-if-false1}
10244 is empty.  For example,
10246 @example
10247 AS_IF([test "$foo" = yes], [HANDLE_FOO([yes])],
10248       [test "$foo" != no], [HANDLE_FOO([maybe])],
10249       [echo foo not specified])
10250 @end example
10252 @noindent
10253 ensures any required macros of @code{HANDLE_FOO}
10254 are expanded before the first test.
10255 @end defmac
10257 @defmac AS_MKDIR_P (@var{file-name})
10258 @asindex{MKDIR_P}
10259 Make the directory @var{file-name}, including intervening directories
10260 as necessary.  This is equivalent to @samp{mkdir -p @var{file-name}},
10261 except that it is portable to older versions of @command{mkdir} that
10262 lack support for the @option{-p} option.  Also, @code{AS_MKDIR_P}
10263 succeeds if @var{file-name} is a symbolic link to an existing directory,
10264 even though Posix is unclear whether @samp{mkdir -p} should
10265 succeed in that case.  If creation of @var{file-name} fails, exit the
10266 script.
10268 Also see the @code{AC_PROG_MKDIR_P} macro (@pxref{Particular Programs}).
10269 @end defmac
10271 @defmac AS_SHELL_SANITIZE
10272 @asindex{SHELL_SANITIZE}
10273 Initialize the shell suitably for @code{configure} scripts.  This has
10274 the effect of @code{AS_BOURNE_COMPATIBLE}, and sets some other
10275 environment variables for predictable results from configuration tests.
10276 For example, it sets @env{LC_ALL} to change to the default C locale.
10277 @xref{Special Shell Variables}.
10278 @end defmac
10280 @defmac AS_TR_CPP (@var{expression})
10281 @asindex{TR_CPP}
10282 Transform @var{expression} into a valid right-hand side for a C @code{#define}.
10283 For example:
10285 @example
10286 # This outputs "#define HAVE_CHAR_P 1".
10287 type="char *"
10288 echo "#define AS_TR_CPP([HAVE_$type]) 1"
10289 @end example
10290 @end defmac
10292 @defmac AS_TR_SH (@var{expression})
10293 @asindex{TR_SH}
10294 Transform @var{expression} into a valid shell variable name.  For example:
10296 @example
10297 # This outputs "Have it!".
10298 header="sys/some file.h"
10299 AS_TR_SH([HAVE_$header])=yes
10300 if test "$HAVE_sys_some_file_h" = yes; then echo "Have it!"; fi
10301 @end example
10302 @end defmac
10304 @defmac AS_SET_CATFILE (@var{var}, @var{dir}, @var{file})
10305 @asindex{SET_CATFILE}
10306 Set the shell variable @var{var} to @var{dir}/@var{file}, but
10307 optimizing the common cases (@var{dir} or @var{file} is @samp{.},
10308 @var{file} is absolute, etc.).
10309 @end defmac
10312 @node File Descriptor Macros
10313 @section File Descriptor Macros
10314 @cindex input
10315 @cindex standard input
10316 @cindex file descriptors
10317 @cindex descriptors
10318 @cindex low-level output
10319 @cindex output, low-level
10321 The following macros define file descriptors used to output messages
10322 (or input values) from @file{configure} scripts.
10323 For example:
10325 @example
10326 echo "$wombats found" >&AS_MESSAGE_LOG_FD
10327 echo 'Enter desired kangaroo count:' >&AS_MESSAGE_FD
10328 read kangaroos <&AS_ORIGINAL_STDIN_FD`
10329 @end example
10331 @noindent
10332 However doing so is seldom needed, because Autoconf provides higher
10333 level macros as described below.
10335 @defmac AS_MESSAGE_FD
10336 @asindex{MESSAGE_FD}
10337 The file descriptor for @samp{checking for...}  messages and results.
10338 Normally this directs messages to the standard output, however when
10339 @command{configure} is run with the @option{-q} option, messages sent to
10340 @code{AS_MESSAGE_FD} are discarded.
10342 If you want to display some messages, consider using one of the printing
10343 macros (@pxref{Printing Messages}) instead.  Copies of messages output
10344 via these macros are also recorded in @file{config.log}.
10345 @end defmac
10347 @defmac AS_MESSAGE_LOG_FD
10348 @asindex{MESSAGE_LOG_FD}
10350 The file descriptor for messages logged to @file{config.log}.  Macros
10351 that run tools, like @code{AC_COMPILE_IFELSE} (@pxref{Running the
10352 Compiler}), redirect all output to this descriptor.  You may want to do
10353 so if you develop such a low-level macro.
10354 @end defmac
10356 @defmac AS_ORIGINAL_STDIN_FD
10357 @asindex{ORIGINAL_STDIN_FD}
10358 The file descriptor for the original standard input.
10360 When @command{configure} runs, it may accidentally execute an
10361 interactive command that has the same name as the non-interactive meant
10362 to be used or checked.  If the standard input was the terminal, such
10363 interactive programs would cause @command{configure} to stop, pending
10364 some user input.  Therefore @command{configure} redirects its standard
10365 input from @file{/dev/null} during its initialization.  This is not
10366 normally a problem, since @command{configure} normally does not need
10367 user input.
10369 In the extreme case where your @file{configure} script really needs to
10370 obtain some values from the original standard input, you can read them
10371 explicitly from @code{AS_ORIGINAL_STDIN_FD}.
10372 @end defmac
10375 @c =================================================== Writing Autoconf Macros.
10377 @node Writing Autoconf Macros
10378 @chapter Writing Autoconf Macros
10380 When you write a feature test that could be applicable to more than one
10381 software package, the best thing to do is encapsulate it in a new macro.
10382 Here are some instructions and guidelines for writing Autoconf macros.
10384 @menu
10385 * Macro Definitions::           Basic format of an Autoconf macro
10386 * Macro Names::                 What to call your new macros
10387 * Reporting Messages::          Notifying @command{autoconf} users
10388 * Dependencies Between Macros::  What to do when macros depend on other macros
10389 * Obsoleting Macros::           Warning about old ways of doing things
10390 * Coding Style::                Writing Autoconf macros @`a la Autoconf
10391 @end menu
10393 @node Macro Definitions
10394 @section Macro Definitions
10396 @acindex{DEFUN}
10397 Autoconf macros are defined using the @code{AC_DEFUN} macro, which is
10398 similar to the M4 builtin @code{m4_define} macro.  In addition to
10399 defining a macro, @code{AC_DEFUN} adds to it some code that is used to
10400 constrain the order in which macros are called (@pxref{Prerequisite
10401 Macros}).
10403 An Autoconf macro definition looks like this:
10405 @example
10406 AC_DEFUN(@var{macro-name}, @var{macro-body})
10407 @end example
10409 You can refer to any arguments passed to the macro as @samp{$1},
10410 @samp{$2}, etc.  @xref{Definitions, , How to define new macros, m4.info,
10411 @acronym{GNU} M4}, for more complete information on writing M4 macros.
10413 Be sure to properly quote both the @var{macro-body} @emph{and} the
10414 @var{macro-name} to avoid any problems if the macro happens to have
10415 been previously defined.
10417 Each macro should have a header comment that gives its prototype, and a
10418 brief description.  When arguments have default values, display them in
10419 the prototype.  For example:
10421 @example
10422 # AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1])
10423 # --------------------------------------
10424 m4_define([AC_MSG_ERROR],
10425   [@{ AS_MESSAGE([error: $1], [2])
10426      exit m4_default([$2], [1]); @}])
10427 @end example
10429 Comments about the macro should be left in the header comment.  Most
10430 other comments make their way into @file{configure}, so just keep
10431 using @samp{#} to introduce comments.
10433 @cindex @code{dnl}
10434 If you have some special comments about pure M4 code, comments
10435 that make no sense in @file{configure} and in the header comment, then
10436 use the builtin @code{dnl}: it causes M4 to discard the text
10437 through the next newline.
10439 Keep in mind that @code{dnl} is rarely needed to introduce comments;
10440 @code{dnl} is more useful to get rid of the newlines following macros
10441 that produce no output, such as @code{AC_REQUIRE}.
10444 @node Macro Names
10445 @section Macro Names
10447 All of the Autoconf macros have all-uppercase names starting with
10448 @samp{AC_} to prevent them from accidentally conflicting with other
10449 text.  All shell variables that they use for internal purposes have
10450 mostly-lowercase names starting with @samp{ac_}.  To ensure that your
10451 macros don't conflict with present or future Autoconf macros, you should
10452 prefix your own macro names and any shell variables they use with some
10453 other sequence.  Possibilities include your initials, or an abbreviation
10454 for the name of your organization or software package.
10456 Most of the Autoconf macros' names follow a structured naming convention
10457 that indicates the kind of feature check by the name.  The macro names
10458 consist of several words, separated by underscores, going from most
10459 general to most specific.  The names of their cache variables use the
10460 same convention (@pxref{Cache Variable Names}, for more information on
10461 them).
10463 The first word of the name after @samp{AC_} usually tells the category
10464 of the feature being tested.  Here are the categories used in Autoconf for
10465 specific test macros, the kind of macro that you are more likely to
10466 write.  They are also used for cache variables, in all-lowercase.  Use
10467 them where applicable; where they're not, invent your own categories.
10469 @table @code
10470 @item C
10471 C language builtin features.
10472 @item DECL
10473 Declarations of C variables in header files.
10474 @item FUNC
10475 Functions in libraries.
10476 @item GROUP
10477 Posix group owners of files.
10478 @item HEADER
10479 Header files.
10480 @item LIB
10481 C libraries.
10482 @item PROG
10483 The base names of programs.
10484 @item MEMBER
10485 Members of aggregates.
10486 @item SYS
10487 Operating system features.
10488 @item TYPE
10489 C builtin or declared types.
10490 @item VAR
10491 C variables in libraries.
10492 @end table
10494 After the category comes the name of the particular feature being
10495 tested.  Any further words in the macro name indicate particular aspects
10496 of the feature.  For example, @code{AC_PROG_CC_STDC} checks whether the
10497 C compiler supports @acronym{ISO} Standard C.
10499 An internal macro should have a name that starts with an underscore;
10500 Autoconf internals should therefore start with @samp{_AC_}.
10501 Additionally, a macro that is an internal subroutine of another macro
10502 should have a name that starts with an underscore and the name of that
10503 other macro, followed by one or more words saying what the internal
10504 macro does.  For example, @code{AC_PATH_X} has internal macros
10505 @code{_AC_PATH_X_XMKMF} and @code{_AC_PATH_X_DIRECT}.
10507 @node Reporting Messages
10508 @section Reporting Messages
10509 @cindex Messages, from @command{autoconf}
10511 When macros statically diagnose abnormal situations, benign or fatal,
10512 they should report them using these macros.  For dynamic issues, i.e.,
10513 when @command{configure} is run, see @ref{Printing Messages}.
10515 @defmac AC_DIAGNOSE (@var{category}, @var{message})
10516 @acindex{DIAGNOSE}
10517 Report @var{message} as a warning (or as an error if requested by the
10518 user) if warnings of the @var{category} are turned on.  You are
10519 encouraged to use standard categories, which currently include:
10521 @table @samp
10522 @item all
10523 messages that don't fall into one of the following categories.  Use of an
10524 empty @var{category} is equivalent.
10526 @item cross
10527 related to cross compilation issues.
10529 @item obsolete
10530 use of an obsolete construct.
10532 @item syntax
10533 dubious syntactic constructs, incorrectly ordered macro calls.
10534 @end table
10535 @end defmac
10537 @defmac AC_WARNING (@var{message})
10538 @acindex{WARNING}
10539 Equivalent to @samp{AC_DIAGNOSE([syntax], @var{message})}, but you are
10540 strongly encouraged to use a finer grained category.
10541 @end defmac
10543 @defmac AC_FATAL (@var{message})
10544 @acindex{FATAL}
10545 Report a severe error @var{message}, and have @command{autoconf} die.
10546 @end defmac
10548 When the user runs @samp{autoconf -W error}, warnings from
10549 @code{AC_DIAGNOSE} and @code{AC_WARNING} are reported as error, see
10550 @ref{autoconf Invocation}.
10552 @node Dependencies Between Macros
10553 @section Dependencies Between Macros
10554 @cindex Dependencies between macros
10556 Some Autoconf macros depend on other macros having been called first in
10557 order to work correctly.  Autoconf provides a way to ensure that certain
10558 macros are called if needed and a way to warn the user if macros are
10559 called in an order that might cause incorrect operation.
10561 @menu
10562 * Prerequisite Macros::         Ensuring required information
10563 * Suggested Ordering::          Warning about possible ordering problems
10564 * One-Shot Macros::             Ensuring a macro is called only once
10565 @end menu
10567 @node Prerequisite Macros
10568 @subsection Prerequisite Macros
10569 @cindex Prerequisite macros
10570 @cindex Macros, prerequisites
10572 A macro that you write might need to use values that have previously
10573 been computed by other macros.  For example, @code{AC_DECL_YYTEXT}
10574 examines the output of @code{flex} or @code{lex}, so it depends on
10575 @code{AC_PROG_LEX} having been called first to set the shell variable
10576 @code{LEX}.
10578 Rather than forcing the user of the macros to keep track of the
10579 dependencies between them, you can use the @code{AC_REQUIRE} macro to do
10580 it automatically.  @code{AC_REQUIRE} can ensure that a macro is only
10581 called if it is needed, and only called once.
10583 @defmac AC_REQUIRE (@var{macro-name})
10584 @acindex{REQUIRE}
10585 If the M4 macro @var{macro-name} has not already been called, call it
10586 (without any arguments).  Make sure to quote @var{macro-name} with
10587 square brackets.  @var{macro-name} must have been defined using
10588 @code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
10589 that it has been called.
10591 @code{AC_REQUIRE} must be used inside a macro defined by @code{AC_DEFUN}; it
10592 must not be called from the top level.
10593 @end defmac
10595 @code{AC_REQUIRE} is often misunderstood.  It really implements
10596 dependencies between macros in the sense that if one macro depends upon
10597 another, the latter is expanded @emph{before} the body of the
10598 former.  To be more precise, the required macro is expanded before
10599 the outermost defined macro in the current expansion stack.
10600 In particular, @samp{AC_REQUIRE([FOO])} is not replaced with the body of
10601 @code{FOO}.  For instance, this definition of macros:
10603 @example
10604 @group
10605 AC_DEFUN([TRAVOLTA],
10606 [test "$body_temperature_in_celsius" -gt "38" &&
10607   dance_floor=occupied])
10608 AC_DEFUN([NEWTON_JOHN],
10609 [test "$hair_style" = "curly" &&
10610   dance_floor=occupied])
10611 @end group
10613 @group
10614 AC_DEFUN([RESERVE_DANCE_FLOOR],
10615 [if date | grep '^Sat.*pm' >/dev/null 2>&1; then
10616   AC_REQUIRE([TRAVOLTA])
10617   AC_REQUIRE([NEWTON_JOHN])
10618 fi])
10619 @end group
10620 @end example
10622 @noindent
10623 with this @file{configure.ac}
10625 @example
10626 AC_INIT([Dance Manager], [1.0], [bug-dance@@example.org])
10627 RESERVE_DANCE_FLOOR
10628 if test "$dance_floor" = occupied; then
10629   AC_MSG_ERROR([cannot pick up here, let's move])
10631 @end example
10633 @noindent
10634 does not leave you with a better chance to meet a kindred soul at
10635 other times than Saturday night since it expands into:
10637 @example
10638 @group
10639 test "$body_temperature_in_Celsius" -gt "38" &&
10640   dance_floor=occupied
10641 test "$hair_style" = "curly" &&
10642   dance_floor=occupied
10644 if date | grep '^Sat.*pm' >/dev/null 2>&1; then
10648 @end group
10649 @end example
10651 This behavior was chosen on purpose: (i) it prevents messages in
10652 required macros from interrupting the messages in the requiring macros;
10653 (ii) it avoids bad surprises when shell conditionals are used, as in:
10655 @example
10656 @group
10657 if @dots{}; then
10658   AC_REQUIRE([SOME_CHECK])
10660 @dots{}
10661 SOME_CHECK
10662 @end group
10663 @end example
10665 The helper macros @code{AS_IF} and @code{AS_CASE} may be used to
10666 enforce expansion of required macros outside of shell conditional
10667 constructs.  You are furthermore encouraged to put all @code{AC_REQUIRE} calls
10668 at the beginning of a macro.  You can use @code{dnl} to avoid the empty
10669 lines they leave.
10671 @node Suggested Ordering
10672 @subsection Suggested Ordering
10673 @cindex Macros, ordering
10674 @cindex Ordering macros
10676 Some macros should be run before another macro if both are called, but
10677 neither @emph{requires} that the other be called.  For example, a macro
10678 that changes the behavior of the C compiler should be called before any
10679 macros that run the C compiler.  Many of these dependencies are noted in
10680 the documentation.
10682 Autoconf provides the @code{AC_BEFORE} macro to warn users when macros
10683 with this kind of dependency appear out of order in a
10684 @file{configure.ac} file.  The warning occurs when creating
10685 @command{configure} from @file{configure.ac}, not when running
10686 @command{configure}.
10688 For example, @code{AC_PROG_CPP} checks whether the C compiler
10689 can run the C preprocessor when given the @option{-E} option.  It should
10690 therefore be called after any macros that change which C compiler is
10691 being used, such as @code{AC_PROG_CC}.  So @code{AC_PROG_CC} contains:
10693 @example
10694 AC_BEFORE([$0], [AC_PROG_CPP])dnl
10695 @end example
10697 @noindent
10698 This warns the user if a call to @code{AC_PROG_CPP} has already occurred
10699 when @code{AC_PROG_CC} is called.
10701 @defmac AC_BEFORE (@var{this-macro-name}, @var{called-macro-name})
10702 @acindex{BEFORE}
10703 Make M4 print a warning message to the standard error output if
10704 @var{called-macro-name} has already been called.  @var{this-macro-name}
10705 should be the name of the macro that is calling @code{AC_BEFORE}.  The
10706 macro @var{called-macro-name} must have been defined using
10707 @code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
10708 that it has been called.
10709 @end defmac
10711 @node One-Shot Macros
10712 @subsection One-Shot Macros
10713 @cindex One-shot macros
10714 @cindex Macros, called once
10716 Some macros should be called only once, either because calling them
10717 multiple time is unsafe, or because it is bad style.  For instance
10718 Autoconf ensures that @code{AC_CANONICAL_BUILD} and cousins
10719 (@pxref{Canonicalizing}) are evaluated only once, because it makes no
10720 sense to run these expensive checks more than once.  Such one-shot
10721 macros can be defined using @code{AC_DEFUN_ONCE}.
10723 @defmac AC_DEFUN_ONCE (@var{macro-name}, @var{macro-body})
10724 @acindex{DEFUN_ONCE}
10726 Declare macro @var{macro-name} like @code{AC_DEFUN} would (@pxref{Macro
10727 Definitions}), and emit a warning any time the macro is called more than
10728 once.
10729 @end defmac
10731 Obviously it is not sensible to evaluate a macro defined by
10732 @code{AC_DEFUN_ONCE} in a macro defined by @code{AC_DEFUN}.
10733 Most of the time you want to use @code{AC_REQUIRE} (@pxref{Prerequisite
10734 Macros}).
10736 @node Obsoleting Macros
10737 @section Obsoleting Macros
10738 @cindex Obsoleting macros
10739 @cindex Macros, obsoleting
10741 Configuration and portability technology has evolved over the years.
10742 Often better ways of solving a particular problem are developed, or
10743 ad-hoc approaches are systematized.  This process has occurred in many
10744 parts of Autoconf.  One result is that some of the macros are now
10745 considered @dfn{obsolete}; they still work, but are no longer considered
10746 the best thing to do, hence they should be replaced with more modern
10747 macros.  Ideally, @command{autoupdate} should replace the old macro calls
10748 with their modern implementation.
10750 Autoconf provides a simple means to obsolete a macro.
10752 @defmac AU_DEFUN (@var{old-macro}, @var{implementation}, @ovar{message})
10753 @auindex{DEFUN}
10754 Define @var{old-macro} as @var{implementation}.  The only difference
10755 with @code{AC_DEFUN} is that the user is warned that
10756 @var{old-macro} is now obsolete.
10758 If she then uses @command{autoupdate}, the call to @var{old-macro} is
10759 replaced by the modern @var{implementation}.  @var{message} should
10760 include information on what to do after running @command{autoupdate};
10761 @command{autoupdate} prints it as a warning, and includes it
10762 in the updated @file{configure.ac} file.
10764 The details of this macro are hairy: if @command{autoconf} encounters an
10765 @code{AU_DEFUN}ed macro, all macros inside its second argument are expanded
10766 as usual.  However, when @command{autoupdate} is run, only M4 and M4sugar
10767 macros are expanded here, while all other macros are disabled and
10768 appear literally in the updated @file{configure.ac}.
10769 @end defmac
10771 @defmac AU_ALIAS (@var{old-name}, @var{new-name})
10772 @auindex{ALIAS}
10773 Used if the @var{old-name} is to be replaced by a call to @var{new-macro}
10774 with the same parameters.  This happens for example if the macro was renamed.
10775 @end defmac
10777 @node Coding Style
10778 @section Coding Style
10779 @cindex Coding style
10781 The Autoconf macros follow a strict coding style.  You are encouraged to
10782 follow this style, especially if you intend to distribute your macro,
10783 either by contributing it to Autoconf itself, or via other means.
10785 The first requirement is to pay great attention to the quotation.  For
10786 more details, see @ref{Autoconf Language}, and @ref{M4 Quotation}.
10788 Do not try to invent new interfaces.  It is likely that there is a macro
10789 in Autoconf that resembles the macro you are defining: try to stick to
10790 this existing interface (order of arguments, default values, etc.).  We
10791 @emph{are} conscious that some of these interfaces are not perfect;
10792 nevertheless, when harmless, homogeneity should be preferred over
10793 creativity.
10795 Be careful about clashes both between M4 symbols and between shell
10796 variables.
10798 If you stick to the suggested M4 naming scheme (@pxref{Macro Names}),
10799 you are unlikely to generate conflicts.  Nevertheless, when you need to
10800 set a special value, @emph{avoid using a regular macro name}; rather,
10801 use an ``impossible'' name.  For instance, up to version 2.13, the macro
10802 @code{AC_SUBST} used to remember what @var{symbol} macros were already defined
10803 by setting @code{AC_SUBST_@var{symbol}}, which is a regular macro name.
10804 But since there is a macro named @code{AC_SUBST_FILE}, it was just
10805 impossible to @samp{AC_SUBST(FILE)}!  In this case,
10806 @code{AC_SUBST(@var{symbol})} or @code{_AC_SUBST(@var{symbol})} should
10807 have been used (yes, with the parentheses).
10808 @c or better yet, high-level macros such as @code{m4_expand_once}
10810 No Autoconf macro should ever enter the user-variable name space; i.e.,
10811 except for the variables that are the actual result of running the
10812 macro, all shell variables should start with @code{ac_}.  In
10813 addition, small macros or any macro that is likely to be embedded in
10814 other macros should be careful not to use obvious names.
10816 @cindex @code{dnl}
10817 Do not use @code{dnl} to introduce comments: most of the comments you
10818 are likely to write are either header comments which are not output
10819 anyway, or comments that should make their way into @file{configure}.
10820 There are exceptional cases where you do want to comment special M4
10821 constructs, in which case @code{dnl} is right, but keep in mind that it
10822 is unlikely.
10824 M4 ignores the leading blanks and newlines before each argument.
10825 Use this feature to
10826 indent in such a way that arguments are (more or less) aligned with the
10827 opening parenthesis of the macro being called.  For instance, instead of
10829 @example
10830 AC_CACHE_CHECK(for EMX OS/2 environment,
10831 ac_cv_emxos2,
10832 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])],
10833 [ac_cv_emxos2=yes], [ac_cv_emxos2=no])])
10834 @end example
10836 @noindent
10837 write
10839 @example
10840 AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
10841 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
10842                    [ac_cv_emxos2=yes],
10843                    [ac_cv_emxos2=no])])
10844 @end example
10846 @noindent
10847 or even
10849 @example
10850 AC_CACHE_CHECK([for EMX OS/2 environment],
10851                [ac_cv_emxos2],
10852                [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([],
10853                                                    [return __EMX__;])],
10854                                   [ac_cv_emxos2=yes],
10855                                   [ac_cv_emxos2=no])])
10856 @end example
10858 When using @code{AC_RUN_IFELSE} or any macro that cannot work when
10859 cross-compiling, provide a pessimistic value (typically @samp{no}).
10861 Feel free to use various tricks to prevent auxiliary tools, such as
10862 syntax-highlighting editors, from behaving improperly.  For instance,
10863 instead of:
10865 @example
10866 m4_bpatsubst([$1], [$"])
10867 @end example
10869 @noindent
10872 @example
10873 m4_bpatsubst([$1], [$""])
10874 @end example
10876 @noindent
10877 so that Emacsen do not open an endless ``string'' at the first quote.
10878 For the same reasons, avoid:
10880 @example
10881 test $[#] != 0
10882 @end example
10884 @noindent
10885 and use:
10887 @example
10888 test $[@@%:@@] != 0
10889 @end example
10891 @noindent
10892 Otherwise, the closing bracket would be hidden inside a @samp{#}-comment,
10893 breaking the bracket-matching highlighting from Emacsen.  Note the
10894 preferred style to escape from M4: @samp{$[1]}, @samp{$[@@]}, etc.  Do
10895 not escape when it is unnecessary.  Common examples of useless quotation
10896 are @samp{[$]$1} (write @samp{$$1}), @samp{[$]var} (use @samp{$var}),
10897 etc.  If you add portability issues to the picture, you'll prefer
10898 @samp{$@{1+"$[@@]"@}} to @samp{"[$]@@"}, and you'll prefer do something
10899 better than hacking Autoconf @code{:-)}.
10901 When using @command{sed}, don't use @option{-e} except for indenting
10902 purposes.  With the @code{s} and @code{y} commands, the preferred
10903 separator is @samp{/} unless @samp{/} itself might appear in the pattern
10904 or replacement, in which case you should use @samp{|}, or optionally
10905 @samp{,} if you know the pattern and replacement cannot contain a file
10906 name.  If none of these characters will do, choose a printable character
10907 that cannot appear in the pattern or replacement.  Characters from the
10908 set @samp{"#$&'()*;<=>?`|~} are good choices if the pattern or
10909 replacement might contain a file name, since they have special meaning
10910 to the shell and are less likely to occur in file names.
10912 @xref{Macro Definitions}, for details on how to define a macro.  If a
10913 macro doesn't use @code{AC_REQUIRE}, is expected to never be the object
10914 of an @code{AC_REQUIRE} directive, and macros required by other macros
10915 inside arguments do not need to be expanded before this macro, then
10916 use @code{m4_define}.  In case of doubt, use @code{AC_DEFUN}.
10917 All the @code{AC_REQUIRE} statements should be at the beginning of the
10918 macro, and each statement should be followed by @code{dnl}.
10920 You should not rely on the number of arguments: instead of checking
10921 whether an argument is missing, test that it is not empty.  It provides
10922 both a simpler and a more predictable interface to the user, and saves
10923 room for further arguments.
10925 Unless the macro is short, try to leave the closing @samp{])} at the
10926 beginning of a line, followed by a comment that repeats the name of the
10927 macro being defined.  This introduces an additional newline in
10928 @command{configure}; normally, that is not a problem, but if you want to
10929 remove it you can use @samp{[]dnl} on the last line.  You can similarly
10930 use @samp{[]dnl} after a macro call to remove its newline.  @samp{[]dnl}
10931 is recommended instead of @samp{dnl} to ensure that M4 does not
10932 interpret the @samp{dnl} as being attached to the preceding text or
10933 macro output.  For example, instead of:
10935 @example
10936 AC_DEFUN([AC_PATH_X],
10937 [AC_MSG_CHECKING([for X])
10938 AC_REQUIRE_CPP()
10939 @r{# @dots{}omitted@dots{}}
10940   AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
10941 fi])
10942 @end example
10944 @noindent
10945 you would write:
10947 @example
10948 AC_DEFUN([AC_PATH_X],
10949 [AC_REQUIRE_CPP()[]dnl
10950 AC_MSG_CHECKING([for X])
10951 @r{# @dots{}omitted@dots{}}
10952   AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
10953 fi[]dnl
10954 ])# AC_PATH_X
10955 @end example
10957 If the macro is long, try to split it into logical chunks.  Typically,
10958 macros that check for a bug in a function and prepare its
10959 @code{AC_LIBOBJ} replacement should have an auxiliary macro to perform
10960 this setup.  Do not hesitate to introduce auxiliary macros to factor
10961 your code.
10963 In order to highlight the recommended coding style, here is a macro
10964 written the old way:
10966 @example
10967 dnl Check for EMX on OS/2.
10968 dnl _AC_EMXOS2
10969 AC_DEFUN(_AC_EMXOS2,
10970 [AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2,
10971 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)],
10972 ac_cv_emxos2=yes, ac_cv_emxos2=no)])
10973 test "$ac_cv_emxos2" = yes && EMXOS2=yes])
10974 @end example
10976 @noindent
10977 and the new way:
10979 @example
10980 # _AC_EMXOS2
10981 # ----------
10982 # Check for EMX on OS/2.
10983 m4_define([_AC_EMXOS2],
10984 [AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
10985 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
10986                    [ac_cv_emxos2=yes],
10987                    [ac_cv_emxos2=no])])
10988 test "$ac_cv_emxos2" = yes && EMXOS2=yes[]dnl
10989 ])# _AC_EMXOS2
10990 @end example
10995 @c ============================================= Portable Shell Programming
10997 @node Portable Shell
10998 @chapter Portable Shell Programming
10999 @cindex Portable shell programming
11001 When writing your own checks, there are some shell-script programming
11002 techniques you should avoid in order to make your code portable.  The
11003 Bourne shell and upward-compatible shells like the Korn shell and Bash
11004 have evolved over the years, but to prevent trouble, do not take
11005 advantage of features that were added after Unix version 7, circa
11006 1977 (@pxref{Systemology}).
11008 You should not use shell functions, aliases, negated character
11009 classes, or other features that are not found in all Bourne-compatible
11010 shells; restrict yourself to the lowest common denominator.  Even
11011 @code{unset} is not supported by all shells!
11013 Some ancient systems have quite
11014 small limits on the length of the @samp{#!} line; for instance, 32
11015 bytes (not including the newline) on SunOS 4.
11016 A few ancient 4.2@acronym{BSD} based systems (such as Dynix circa 1984)
11017 required a single space between the @samp{#!} and the @samp{/}.
11018 However, these ancient systems are no longer of practical concern.
11020 The set of external programs you should run in a @command{configure} script
11021 is fairly small.  @xref{Utilities in Makefiles, , Utilities in
11022 Makefiles, standards, @acronym{GNU} Coding Standards}, for the list.  This
11023 restriction allows users to start out with a fairly small set of
11024 programs and build the rest, avoiding too many interdependencies between
11025 packages.
11027 Some of these external utilities have a portable subset of features; see
11028 @ref{Limitations of Usual Tools}.
11030 There are other sources of documentation about shells.  The
11031 specification for the Posix
11032 @uref{http://www.opengroup.org/@/susv3/@/utilities/@/xcu_chap02.html, Shell
11033 Command Language}, though more generous than the restrictive shell
11034 subset described above, is fairly portable nowadays.  Also please see
11035 @uref{http://www.faqs.org/@/faqs/@/unix-faq/@/shell/, the Shell FAQs}.
11037 @menu
11038 * Shellology::                  A zoology of shells
11039 * Here-Documents::              Quirks and tricks
11040 * File Descriptors::            FDs and redirections
11041 * File System Conventions::     File names
11042 * Shell Pattern Matching::      Pattern matching
11043 * Shell Substitutions::         Variable and command expansions
11044 * Assignments::                 Varying side effects of assignments
11045 * Parentheses::                 Parentheses in shell scripts
11046 * Slashes::                     Slashes in shell scripts
11047 * Special Shell Variables::     Variables you should not change
11048 * Limitations of Builtins::     Portable use of not so portable /bin/sh
11049 * Limitations of Usual Tools::  Portable use of portable tools
11050 @end menu
11052 @node Shellology
11053 @section Shellology
11054 @cindex Shellology
11056 There are several families of shells, most prominently the Bourne family
11057 and the C shell family which are deeply incompatible.  If you want to
11058 write portable shell scripts, avoid members of the C shell family.  The
11059 @uref{http://www.faqs.org/@/faqs/@/unix-faq/@/shell/@/shell-differences/, the
11060 Shell difference FAQ} includes a small history of Posix shells, and a
11061 comparison between several of them.
11063 Below we describe some of the members of the Bourne shell family.
11065 @table @asis
11066 @item Ash
11067 @cindex Ash
11068 Ash is often used on @acronym{GNU}/Linux and @acronym{BSD}
11069 systems as a light-weight Bourne-compatible shell.  Ash 0.2 has some
11070 bugs that are fixed in the 0.3.x series, but portable shell scripts
11071 should work around them, since version 0.2 is still shipped with many
11072 @acronym{GNU}/Linux distributions.
11074 To be compatible with Ash 0.2:
11076 @itemize @minus
11077 @item
11078 don't use @samp{$?} after expanding empty or unset variables,
11079 or at the start of an @command{eval}:
11081 @example
11082 foo=
11083 false
11084 $foo
11085 echo "Do not use it: $?"
11086 false
11087 eval 'echo "Do not use it: $?"'
11088 @end example
11090 @item
11091 don't use command substitution within variable expansion:
11093 @example
11094 cat $@{FOO=`bar`@}
11095 @end example
11097 @item
11098 beware that single builtin substitutions are not performed by a
11099 subshell, hence their effect applies to the current shell!  @xref{Shell
11100 Substitutions}, item ``Command Substitution''.
11101 @end itemize
11103 @item Bash
11104 @cindex Bash
11105 To detect whether you are running Bash, test whether
11106 @code{BASH_VERSION} is set.  To require
11107 Posix compatibility, run @samp{set -o posix}.  @xref{Bash POSIX
11108 Mode, , Bash Posix Mode, bash, The @acronym{GNU} Bash Reference
11109 Manual}, for details.
11111 @item Bash 2.05 and later
11112 @cindex Bash 2.05 and later
11113 Versions 2.05 and later of Bash use a different format for the
11114 output of the @command{set} builtin, designed to make evaluating its
11115 output easier.  However, this output is not compatible with earlier
11116 versions of Bash (or with many other shells, probably).  So if
11117 you use Bash 2.05 or higher to execute @command{configure},
11118 you'll need to use Bash 2.05 for all other build tasks as well.
11120 @item Ksh
11121 @cindex Ksh
11122 @cindex Korn shell
11123 @prindex @samp{ksh}
11124 @prindex @samp{ksh88}
11125 @prindex @samp{ksh93}
11126 The Korn shell is compatible with the Bourne family and it mostly
11127 conforms to Posix.  It has two major variants commonly
11128 called @samp{ksh88} and @samp{ksh93}, named after the years of initial
11129 release.  It is usually called @command{ksh}, but is called @command{sh}
11130 on some hosts if you set your path appropriately.
11132 Solaris systems have three variants:
11133 @prindex @command{/usr/bin/ksh} on Solaris
11134 @command{/usr/bin/ksh} is @samp{ksh88}; it is
11135 standard on Solaris 2.0 and later.
11136 @prindex @command{/usr/xpg4/bin/sh} on Solaris
11137 @command{/usr/xpg4/bin/sh} is a Posix-compliant variant of
11138 @samp{ksh88}; it is standard on Solaris 9 and later.
11139 @prindex @command{/usr/dt/bin/dtksh} on Solaris
11140 @command{/usr/dt/bin/dtksh} is @samp{ksh93}.
11141 Variants that are not standard may be parts of optional
11142 packages.  There is no extra charge for these packages, but they are
11143 not part of a minimal OS install and therefore some installations may
11144 not have it.
11146 Starting with Tru64 Version 4.0, the Korn shell @command{/usr/bin/ksh}
11147 is also available as @command{/usr/bin/posix/sh}.  If the environment
11148 variable @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of
11149 the standard shell conform to Posix.
11151 @item Pdksh
11152 @prindex @samp{pdksh}
11153 A public-domain clone of the Korn shell called @command{pdksh} is widely
11154 available: it has most of the @samp{ksh88} features along with a few of
11155 its own.  It usually sets @code{KSH_VERSION}, except if invoked as
11156 @command{/bin/sh} on Open@acronym{BSD}, and similarly to Bash you can require
11157 Posix compatibility by running @samp{set -o posix}.  Unfortunately, with
11158 @command{pdksh} 5.2.14 (the latest stable version as of January 2007)
11159 Posix mode is buggy and causes @command{pdksh} to depart from Posix in
11160 at least one respect:
11162 @example
11163 $ @kbd{echo "`echo \"hello\"`"}
11164 hello
11165 $ @kbd{set -o posix}
11166 $ @kbd{echo "`echo \"hello\"`"}
11167 "hello"
11168 @end example
11170 The last line of output contains spurious quotes.  This is yet another
11171 reason why portable shell code should not contain
11172 @code{"`@dots{}\"@dots{}\"@dots{}`"} constructs (@pxref{Shell
11173 Substitutions}).
11175 @item Zsh
11176 @cindex Zsh
11177 To detect whether you are running @command{zsh}, test whether
11178 @code{ZSH_VERSION} is set.  By default @command{zsh} is @emph{not}
11179 compatible with the Bourne shell: you must execute @samp{emulate sh},
11180 and for @command{zsh} versions before 3.1.6-dev-18 you must also
11181 set @code{NULLCMD} to @samp{:}.  @xref{Compatibility, , Compatibility,
11182 zsh, The Z Shell Manual}, for details.
11184 The default Mac OS X @command{sh} was originally Zsh; it was changed to
11185 Bash in Mac OS X 10.2.
11186 @end table
11188 The following discussion between Russ Allbery and Robert Lipe is worth
11189 reading:
11191 @noindent
11192 Russ Allbery:
11194 @quotation
11195 The @acronym{GNU} assumption that @command{/bin/sh} is the one and only shell
11196 leads to a permanent deadlock.  Vendors don't want to break users'
11197 existing shell scripts, and there are some corner cases in the Bourne
11198 shell that are not completely compatible with a Posix shell.  Thus,
11199 vendors who have taken this route will @emph{never} (OK@dots{}``never say
11200 never'') replace the Bourne shell (as @command{/bin/sh}) with a
11201 Posix shell.
11202 @end quotation
11204 @noindent
11205 Robert Lipe:
11207 @quotation
11208 This is exactly the problem.  While most (at least most System V's) do
11209 have a Bourne shell that accepts shell functions most vendor
11210 @command{/bin/sh} programs are not the Posix shell.
11212 So while most modern systems do have a shell @emph{somewhere} that meets the
11213 Posix standard, the challenge is to find it.
11214 @end quotation
11216 @node Here-Documents
11217 @section Here-Documents
11218 @cindex Here-documents
11219 @cindex Shell here-documents
11221 Don't rely on @samp{\} being preserved just because it has no special
11222 meaning together with the next symbol.  In the native @command{sh}
11223 on Open@acronym{BSD} 2.7 @samp{\"} expands to @samp{"} in here-documents with
11224 unquoted delimiter.  As a general rule, if @samp{\\} expands to @samp{\}
11225 use @samp{\\} to get @samp{\}.
11227 With Open@acronym{BSD} 2.7's @command{sh}
11229 @example
11230 @group
11231 $ @kbd{cat <<EOF
11232 > \" \\
11233 > EOF}
11234 " \
11235 @end group
11236 @end example
11238 @noindent
11239 and with Bash:
11241 @example
11242 @group
11243 bash-2.04$ @kbd{cat <<EOF
11244 > \" \\
11245 > EOF}
11246 \" \
11247 @end group
11248 @end example
11250 Some shells mishandle large here-documents: for example,
11251 Solaris 10 @command{dtksh} and the UnixWare 7.1.1 Posix shell, which are
11252 derived from Korn shell version M-12/28/93d, mishandle braced variable
11253 expansion that crosses a 1024- or 4096-byte buffer boundary
11254 within a here-document.  Only the part of the variable name after the boundary
11255 is used.  For example, @code{$@{variable@}} could be replaced by the expansion
11256 of @code{$@{ble@}}.  If the end of the variable name is aligned with the block
11257 boundary, the shell reports an error, as if you used @code{$@{@}}.
11258 Instead of @code{$@{variable-default@}}, the shell may expand
11259 @code{$@{riable-default@}}, or even @code{$@{fault@}}.  This bug can often
11260 be worked around by omitting the braces: @code{$variable}.  The bug was fixed in
11261 @samp{ksh93g} (1998-04-30) but as of 2006 many operating systems were
11262 still shipping older versions with the bug.
11264 Many shells (including the Bourne shell) implement here-documents
11265 inefficiently.  In particular, some shells can be extremely inefficient when
11266 a single statement contains many here-documents.  For instance if your
11267 @file{configure.ac} includes something like:
11269 @example
11270 @group
11271 if <cross_compiling>; then
11272   assume this and that
11273 else
11274   check this
11275   check that
11276   check something else
11277   @dots{}
11278   on and on forever
11279   @dots{}
11281 @end group
11282 @end example
11284 A shell parses the whole @code{if}/@code{fi} construct, creating
11285 temporary files for each here-document in it.  Some shells create links
11286 for such here-documents on every @code{fork}, so that the clean-up code
11287 they had installed correctly removes them.  It is creating the links
11288 that can take the shell forever.
11290 Moving the tests out of the @code{if}/@code{fi}, or creating multiple
11291 @code{if}/@code{fi} constructs, would improve the performance
11292 significantly.  Anyway, this kind of construct is not exactly the
11293 typical use of Autoconf.  In fact, it's even not recommended, because M4
11294 macros can't look into shell conditionals, so we may fail to expand a
11295 macro when it was expanded before in a conditional path, and the
11296 condition turned out to be false at runtime, and we end up not
11297 executing the macro at all.
11299 @node File Descriptors
11300 @section File Descriptors
11301 @cindex Descriptors
11302 @cindex File descriptors
11303 @cindex Shell file descriptors
11305 Most shells, if not all (including Bash, Zsh, Ash), output traces on
11306 stderr, even for subshells.  This might result in undesirable content
11307 if you meant to capture the standard-error output of the inner command:
11309 @example
11310 $ @kbd{ash -x -c '(eval "echo foo >&2") 2>stderr'}
11311 $ @kbd{cat stderr}
11312 + eval echo foo >&2
11313 + echo foo
11315 $ @kbd{bash -x -c '(eval "echo foo >&2") 2>stderr'}
11316 $ @kbd{cat stderr}
11317 + eval 'echo foo >&2'
11318 ++ echo foo
11320 $ @kbd{zsh -x -c '(eval "echo foo >&2") 2>stderr'}
11321 @i{# Traces on startup files deleted here.}
11322 $ @kbd{cat stderr}
11323 +zsh:1> eval echo foo >&2
11324 +zsh:1> echo foo
11326 @end example
11328 @noindent
11329 One workaround is to grep out uninteresting lines, hoping not to remove
11330 good ones.
11332 If you intend to redirect both standard error and standard output,
11333 redirect standard output first.  This works better with @acronym{HP-UX},
11334 since its shell mishandles tracing if standard error is redirected
11335 first:
11337 @example
11338 $ @kbd{sh -x -c ': 2>err >out'}
11339 + :
11340 + 2> err $ @kbd{cat err}
11341 1> out
11342 @end example
11344 Don't try to redirect the standard error of a command substitution.  It
11345 must be done @emph{inside} the command substitution.  When running
11346 @samp{: `cd /zorglub` 2>/dev/null} expect the error message to
11347 escape, while @samp{: `cd /zorglub 2>/dev/null`} works properly.
11349 It is worth noting that Zsh (but not Ash nor Bash) makes it possible
11350 in assignments though: @samp{foo=`cd /zorglub` 2>/dev/null}.
11352 Don't redirect the same file descriptor several times, as you are doomed
11353 to failure under Ultrix.
11355 @example
11356 ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995
11357 UWS V4.4 (Rev. 11)
11358 $ @kbd{eval 'echo matter >fullness' >void}
11359 illegal io
11360 $ @kbd{eval '(echo matter >fullness)' >void}
11361 illegal io
11362 $ @kbd{(eval '(echo matter >fullness)') >void}
11363 Ambiguous output redirect.
11364 @end example
11366 @noindent
11367 In each case the expected result is of course @file{fullness} containing
11368 @samp{matter} and @file{void} being empty.
11370 Don't rely on file descriptors 0, 1, and 2 remaining closed in a
11371 subsidiary program.  If any of these descriptors is closed, the
11372 operating system may open an unspecified file for the descriptor in the
11373 new process image.  Posix says this may be done only if the subsidiary
11374 program is set-user-ID or set-group-ID, but @acronym{HP-UX} 11.23 does it even for
11375 ordinary programs.
11377 Don't rely on open file descriptors being open in child processes.  In
11378 @command{ksh}, file descriptors above 2 which are opened using
11379 @samp{exec @var{n}>file} are closed by a subsequent @samp{exec} (such as
11380 that involved in the fork-and-exec which runs a program or script).
11381 Thus, using @command{sh}, we have:
11383 @example
11384 $ @kbd{cat ./descrips}
11385 #!/bin/sh -
11386 echo hello >&5
11387 $ @kbd{exec 5>t}
11388 $ @kbd{./descrips}
11389 $ @kbd{cat t}
11391 hello
11392 @end example
11394 @noindent
11395 But using ksh:
11397 @example
11398 $ @kbd{exec 5>t}
11399 $ @kbd{./descrips}
11400 hello
11401 $ @kbd{cat t}
11403 @end example
11405 @noindent
11406 Within the process which runs the @samp{descrips} script, file
11407 descriptor 5 is closed.
11409 @acronym{DOS} variants cannot rename or remove open files, such as in
11410 @samp{mv foo bar >foo} or @samp{rm foo >foo}, even though this is
11411 perfectly portable among Posix hosts.
11413 A few ancient systems reserved some file descriptors.  By convention,
11414 file descriptor 3 was opened to @file{/dev/tty} when you logged into
11415 Eighth Edition (1985) through Tenth Edition Unix (1989).  File
11416 descriptor 4 had a special use on the Stardent/Kubota Titan (circa
11417 1990), though we don't now remember what it was.  Both these systems are
11418 obsolete, so it's now safe to treat file descriptors 3 and 4 like any
11419 other file descriptors.
11421 @node File System Conventions
11422 @section File System Conventions
11423 @cindex File system conventions
11425 Autoconf uses shell-script processing extensively, so the file names
11426 that it processes should not contain characters that are special to the
11427 shell.  Special characters include space, tab, newline, @sc{nul}, and
11428 the following:
11430 @example
11431 " # $ & ' ( ) * ; < = > ? [ \ ` |
11432 @end example
11434 Also, file names should not begin with @samp{~} or @samp{-}, and should
11435 contain neither @samp{-} immediately after @samp{/} nor @samp{~}
11436 immediately after @samp{:}.  On Posix-like platforms, directory names
11437 should not contain @samp{:}, as this runs afoul of @samp{:} used as the
11438 path separator.
11440 These restrictions apply not only to the files that you distribute, but
11441 also to the absolute file names of your source, build, and destination
11442 directories.
11444 On some Posix-like platforms, @samp{!} and @samp{^} are special too, so
11445 they should be avoided.
11447 Posix lets implementations treat leading @file{//} specially, but
11448 requires leading @file{///} and beyond to be equivalent to @file{/}.
11449 Most Unix variants treat @file{//} like @file{/}.  However, some treat
11450 @file{//} as a ``super-root'' that can provide access to files that are
11451 not otherwise reachable from @file{/}.  The super-root tradition began
11452 with Apollo Domain/OS, which died out long ago, but unfortunately Cygwin
11453 has revived it.
11455 While @command{autoconf} and friends are usually run on some Posix
11456 variety, they can be used on other systems, most notably @acronym{DOS}
11457 variants.  This impacts several assumptions regarding file names.
11459 @noindent
11460 For example, the following code:
11462 @example
11463 case $foo_dir in
11464   /*) # Absolute
11465      ;;
11466   *)
11467      foo_dir=$dots$foo_dir ;;
11468 esac
11469 @end example
11471 @noindent
11472 fails to properly detect absolute file names on those systems, because
11473 they can use a drivespec, and usually use a backslash as directory
11474 separator.  If you want to be portable to @acronym{DOS} variants (at the
11475 price of rejecting valid but oddball Posix file names like @file{a:\b}),
11476 you can check for absolute file names like this:
11478 @example
11479 case $foo_dir in
11480   [\\/]* | ?:[\\/]* ) # Absolute
11481      ;;
11482   *)
11483      foo_dir=$dots$foo_dir ;;
11484 esac
11485 @end example
11487 @noindent
11488 Make sure you quote the brackets if appropriate and keep the backslash as
11489 first character (@pxref{Limitations of Builtins}).
11491 Also, because the colon is used as part of a drivespec, these systems don't
11492 use it as path separator.  When creating or accessing paths, you can use the
11493 @code{PATH_SEPARATOR} output variable instead.  @command{configure} sets this
11494 to the appropriate value for the build system (@samp{:} or @samp{;}) when it
11495 starts up.
11497 File names need extra care as well.  While @acronym{DOS} variants
11498 that are Posixy enough to run @command{autoconf} (such as @acronym{DJGPP})
11499 are usually able to handle long file names properly, there are still
11500 limitations that can seriously break packages.  Several of these issues
11501 can be easily detected by the
11502 @uref{ftp://ftp.gnu.org/gnu/non-gnu/doschk/doschk-1.1.tar.gz, doschk}
11503 package.
11505 A short overview follows; problems are marked with @sc{sfn}/@sc{lfn} to
11506 indicate where they apply: @sc{sfn} means the issues are only relevant to
11507 plain @acronym{DOS}, not to @acronym{DOS} under Microsoft Windows
11508 variants, while @sc{lfn} identifies problems that exist even under
11509 Microsoft Windows variants.
11511 @table @asis
11512 @item No multiple dots (@sc{sfn})
11513 @acronym{DOS} cannot handle multiple dots in file names.  This is an especially
11514 important thing to remember when building a portable configure script,
11515 as @command{autoconf} uses a .in suffix for template files.
11517 This is perfectly OK on Posix variants:
11519 @example
11520 AC_CONFIG_HEADERS([config.h])
11521 AC_CONFIG_FILES([source.c foo.bar])
11522 AC_OUTPUT
11523 @end example
11525 @noindent
11526 but it causes problems on @acronym{DOS}, as it requires @samp{config.h.in},
11527 @samp{source.c.in} and @samp{foo.bar.in}.  To make your package more portable
11528 to @acronym{DOS}-based environments, you should use this instead:
11530 @example
11531 AC_CONFIG_HEADERS([config.h:config.hin])
11532 AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in])
11533 AC_OUTPUT
11534 @end example
11536 @item No leading dot (@sc{sfn})
11537 @acronym{DOS} cannot handle file names that start with a dot.  This is usually
11538 not important for @command{autoconf}.
11540 @item Case insensitivity (@sc{lfn})
11541 @acronym{DOS} is case insensitive, so you cannot, for example, have both a
11542 file called @samp{INSTALL} and a directory called @samp{install}.  This
11543 also affects @command{make}; if there's a file called @samp{INSTALL} in
11544 the directory, @samp{make install} does nothing (unless the
11545 @samp{install} target is marked as PHONY).
11547 @item The 8+3 limit (@sc{sfn})
11548 Because the @acronym{DOS} file system only stores the first 8 characters of
11549 the file name and the first 3 of the extension, those must be unique.
11550 That means that @file{foobar-part1.c}, @file{foobar-part2.c} and
11551 @file{foobar-prettybird.c} all resolve to the same file name
11552 (@file{FOOBAR-P.C}).  The same goes for @file{foo.bar} and
11553 @file{foo.bartender}.
11555 The 8+3 limit is not usually a problem under Microsoft Windows, as it
11556 uses numeric
11557 tails in the short version of file names to make them unique.  However, a
11558 registry setting can turn this behavior off.  While this makes it
11559 possible to share file trees containing long file names between @sc{sfn}
11560 and @sc{lfn} environments, it also means the above problem applies there
11561 as well.
11563 @item Invalid characters (@sc{lfn})
11564 Some characters are invalid in @acronym{DOS} file names, and should therefore
11565 be avoided.  In a @sc{lfn} environment, these are @samp{/}, @samp{\},
11566 @samp{?}, @samp{*}, @samp{:}, @samp{<}, @samp{>}, @samp{|} and @samp{"}.
11567 In a @sc{sfn} environment, other characters are also invalid.  These
11568 include @samp{+}, @samp{,}, @samp{[} and @samp{]}.
11570 @item Invalid names (@sc{lfn})
11571 Some @acronym{DOS} file names are reserved, and cause problems if you
11572 try to use files with those names.  These names include @file{CON},
11573 @file{AUX}, @file{COM1}, @file{COM2}, @file{COM3}, @file{COM4},
11574 @file{LPT1}, @file{LPT2}, @file{LPT3}, @file{NUL}, and @file{PRN}.
11575 File names are case insensitive, so even names like
11576 @file{aux/config.guess} are disallowed.
11578 @end table
11580 @node Shell Pattern Matching
11581 @section Shell Pattern Matching
11582 @cindex Shell pattern matching
11584 Nowadays portable patterns can use negated character classes like
11585 @samp{[!-aeiou]}.  The older syntax @samp{[^-aeiou]} is supported by
11586 some shells but not others; hence portable scripts should never use
11587 @samp{^} as the first character of a bracket pattern.
11589 Outside the C locale, patterns like @samp{[a-z]} are problematic since
11590 they may match characters that are not lower-case letters.
11592 @node Shell Substitutions
11593 @section Shell Substitutions
11594 @cindex Shell substitutions
11596 Contrary to a persistent urban legend, the Bourne shell does not
11597 systematically split variables and back-quoted expressions, in particular
11598 on the right-hand side of assignments and in the argument of @code{case}.
11599 For instance, the following code:
11601 @example
11602 case "$given_srcdir" in
11603 .)  top_srcdir="`echo "$dots" | sed 's,/$,,'`" ;;
11604 *)  top_srcdir="$dots$given_srcdir" ;;
11605 esac
11606 @end example
11608 @noindent
11609 is more readable when written as:
11611 @example
11612 case $given_srcdir in
11613 .)  top_srcdir=`echo "$dots" | sed 's,/$,,'` ;;
11614 *)  top_srcdir=$dots$given_srcdir ;;
11615 esac
11616 @end example
11618 @noindent
11619 and in fact it is even @emph{more} portable: in the first case of the
11620 first attempt, the computation of @code{top_srcdir} is not portable,
11621 since not all shells properly understand @code{"`@dots{}"@dots{}"@dots{}`"}.
11622 Worse yet, not all shells understand @code{"`@dots{}\"@dots{}\"@dots{}`"}
11623 the same way.  There is just no portable way to use double-quoted
11624 strings inside double-quoted back-quoted expressions (pfew!).
11626 @table @code
11627 @item $@@
11628 @cindex @samp{"$@@"}
11629 One of the most famous shell-portability issues is related to
11630 @samp{"$@@"}.  When there are no positional arguments, Posix says
11631 that @samp{"$@@"} is supposed to be equivalent to nothing, but the
11632 original Unix version 7 Bourne shell treated it as equivalent to
11633 @samp{""} instead, and this behavior survives in later implementations
11634 like Digital Unix 5.0.
11636 The traditional way to work around this portability problem is to use
11637 @samp{$@{1+"$@@"@}}.  Unfortunately this method does not work with
11638 Zsh (3.x and 4.x), which is used on Mac OS X@.  When emulating
11639 the Bourne shell, Zsh performs word splitting on @samp{$@{1+"$@@"@}}:
11641 @example
11642 zsh $ @kbd{emulate sh}
11643 zsh $ @kbd{for i in "$@@"; do echo $i; done}
11644 Hello World
11646 zsh $ @kbd{for i in $@{1+"$@@"@}; do echo $i; done}
11647 Hello
11648 World
11650 @end example
11652 @noindent
11653 Zsh handles plain @samp{"$@@"} properly, but we can't use plain
11654 @samp{"$@@"} because of the portability problems mentioned above.
11655 One workaround relies on Zsh's ``global aliases'' to convert
11656 @samp{$@{1+"$@@"@}} into @samp{"$@@"} by itself:
11658 @example
11659 test "$@{ZSH_VERSION+set@}" = set && alias -g '$@{1+"$@@"@}'='"$@@"'
11660 @end example
11662 Zsh only recognizes this alias when a shell word matches it exactly;
11663 @samp{"foo"$@{1+"$@@"@}} remains subject to word splitting.  Since this
11664 case always yields at least one shell word, use plain @samp{"$@@"}.
11666 A more conservative workaround is to avoid @samp{"$@@"} if it is
11667 possible that there may be no positional arguments.  For example,
11668 instead of:
11670 @example
11671 cat conftest.c "$@@"
11672 @end example
11674 you can use this instead:
11676 @example
11677 case $# in
11678 0) cat conftest.c;;
11679 *) cat conftest.c "$@@";;
11680 esac
11681 @end example
11683 Autoconf macros often use the @command{set} command to update
11684 @samp{$@@}, so if you are writing shell code intended for
11685 @command{configure} you should not assume that the value of @samp{$@@}
11686 persists for any length of time.
11689 @item $@{10@}
11690 @cindex positional parameters
11691 The 10th, 11th, @dots{} positional parameters can be accessed only after
11692 a @code{shift}.  The 7th Edition shell reported an error if given
11693 @code{$@{10@}}, and
11694 Solaris 10 @command{/bin/sh} still acts that way:
11696 @example
11697 $ @kbd{set 1 2 3 4 5 6 7 8 9 10}
11698 $ @kbd{echo $@{10@}}
11699 bad substitution
11700 @end example
11702 @item $@{@var{var}:-@var{value}@}
11703 @c Info cannot handle `:' in index entries.
11704 @c @cindex $@{@var{var}:-@var{value}@}
11705 Old @acronym{BSD} shells, including the Ultrix @code{sh}, don't accept the
11706 colon for any shell substitution, and complain and die.
11707 Similarly for $@{@var{var}:=@var{value}@}, $@{@var{var}:?@var{value}@}, etc.
11709 @item $@{@var{var}=@var{literal}@}
11710 @cindex $@{@var{var}=@var{literal}@}
11711 Be sure to quote:
11713 @example
11714 : $@{var='Some words'@}
11715 @end example
11717 @noindent
11718 otherwise some shells, such as on Digital Unix V 5.0, die because
11719 of a ``bad substitution''.
11721 @sp 1
11723 Solaris @command{/bin/sh} has a frightening bug in its interpretation
11724 of this.  Imagine you need set a variable to a string containing
11725 @samp{@}}.  This @samp{@}} character confuses Solaris @command{/bin/sh}
11726 when the affected variable was already set.  This bug can be exercised
11727 by running:
11729 @example
11730 $ @kbd{unset foo}
11731 $ @kbd{foo=$@{foo='@}'@}}
11732 $ @kbd{echo $foo}
11734 $ @kbd{foo=$@{foo='@}'   # no error; this hints to what the bug is}
11735 $ @kbd{echo $foo}
11737 $ @kbd{foo=$@{foo='@}'@}}
11738 $ @kbd{echo $foo}
11739 @}@}
11740  ^ ugh!
11741 @end example
11743 It seems that @samp{@}} is interpreted as matching @samp{$@{}, even
11744 though it is enclosed in single quotes.  The problem doesn't happen
11745 using double quotes.
11747 @item $@{@var{var}=@var{expanded-value}@}
11748 @cindex $@{@var{var}=@var{expanded-value}@}
11749 On Ultrix,
11750 running
11752 @example
11753 default="yu,yaa"
11754 : $@{var="$default"@}
11755 @end example
11757 @noindent
11758 sets @var{var} to @samp{M-yM-uM-,M-yM-aM-a}, i.e., the 8th bit of
11759 each char is set.  You don't observe the phenomenon using a simple
11760 @samp{echo $var} since apparently the shell resets the 8th bit when it
11761 expands $var.  Here are two means to make this shell confess its sins:
11763 @example
11764 $ @kbd{cat -v <<EOF
11765 $var
11766 EOF}
11767 @end example
11769 @noindent
11772 @example
11773 $ @kbd{set | grep '^var=' | cat -v}
11774 @end example
11776 One classic incarnation of this bug is:
11778 @example
11779 default="a b c"
11780 : $@{list="$default"@}
11781 for c in $list; do
11782   echo $c
11783 done
11784 @end example
11786 @noindent
11787 You'll get @samp{a b c} on a single line.  Why?  Because there are no
11788 spaces in @samp{$list}: there are @samp{M- }, i.e., spaces with the 8th
11789 bit set, hence no IFS splitting is performed!!!
11791 One piece of good news is that Ultrix works fine with @samp{:
11792 $@{list=$default@}}; i.e., if you @emph{don't} quote.  The bad news is
11793 then that @acronym{QNX} 4.25 then sets @var{list} to the @emph{last} item of
11794 @var{default}!
11796 The portable way out consists in using a double assignment, to switch
11797 the 8th bit twice on Ultrix:
11799 @example
11800 list=$@{list="$default"@}
11801 @end example
11803 @noindent
11804 @dots{}but beware of the @samp{@}} bug from Solaris (see above).  For safety,
11805 use:
11807 @example
11808 test "$@{var+set@}" = set || var=@var{@{value@}}
11809 @end example
11811 @item $@{#@var{var}@}
11812 @itemx $@{@var{var}%@var{word}@}
11813 @itemx $@{@var{var}%%@var{word}@}
11814 @itemx $@{@var{var}#@var{word}@}
11815 @itemx $@{@var{var}##@var{word}@}
11816 @cindex $@{#@var{var}@}
11817 @cindex $@{@var{var}%@var{word}@}
11818 @cindex $@{@var{var}%%@var{word}@}
11819 @cindex $@{@var{var}#@var{word}@}
11820 @cindex $@{@var{var}##@var{word}@}
11821 Posix requires support for these usages, but they do not work with many
11822 traditional shells, e.g., Solaris 10 @command{/bin/sh}.
11824 Also, @command{pdksh} 5.2.14 mishandles some @var{word} forms.  For
11825 example if @samp{$1} is @samp{a/b} and @samp{$2} is @samp{a}, then
11826 @samp{$@{1#$2@}} should yield @samp{/b}, but with @command{pdksh} it
11827 yields the empty string.
11830 @item `@var{commands}`
11831 @cindex `@var{commands}`
11832 @cindex Command Substitution
11833 Posix requires shells to trim all trailing newlines from command
11834 output before substituting it, so assignments like
11835 @samp{dir=`echo "$file" | tr a A`} do not work as expected if
11836 @samp{$file} ends in a newline.
11838 While in general it makes no sense, do not substitute a single builtin
11839 with side effects, because Ash 0.2, trying to optimize, does not fork a
11840 subshell to perform the command.
11842 For instance, if you wanted to check that @command{cd} is silent, do not
11843 use @samp{test -z "`cd /`"} because the following can happen:
11845 @example
11846 $ @kbd{pwd}
11847 /tmp
11848 $ @kbd{test -z "`cd /`" && pwd}
11850 @end example
11852 @noindent
11853 The result of @samp{foo=`exit 1`} is left as an exercise to the reader.
11855 The MSYS shell leaves a stray byte in the expansion of a double-quoted
11856 command substitution of a native program, if the end of the substitution
11857 is not aligned with the end of the double quote.  This may be worked
11858 around by inserting another pair of quotes:
11860 @example
11861 $ @kbd{echo "`printf 'foo\r\n'` bar" > broken}
11862 $ @kbd{echo "`printf 'foo\r\n'`"" bar" | cmp - broken}
11863 - broken differ: char 4, line 1
11864 @end example
11867 @item $(@var{commands})
11868 @cindex $(@var{commands})
11869 This construct is meant to replace @samp{`@var{commands}`},
11870 and it has most of the problems listed under @code{`@var{commands}`}.
11872 This construct can be
11873 nested while this is impossible to do portably with back quotes.
11874 Unfortunately it is not yet universally supported.  Most notably, even recent
11875 releases of Solaris don't support it:
11877 @example
11878 $ @kbd{showrev -c /bin/sh | grep version}
11879 Command version: SunOS 5.10 Generic 121005-03 Oct 2006
11880 $ @kbd{echo $(echo blah)}
11881 syntax error: `(' unexpected
11882 @end example
11884 @noindent
11885 nor does @sc{irix} 6.5's Bourne shell:
11886 @example
11887 $ @kbd{uname -a}
11888 IRIX firebird-image 6.5 07151432 IP22
11889 $ @kbd{echo $(echo blah)}
11890 $(echo blah)
11891 @end example
11893 If you do use @samp{$(@var{commands})}, make sure that the commands
11894 do not start with a parenthesis, as that would cause confusion with
11895 a different notation @samp{$((@var{expression}))} that in modern
11896 shells is an arithmetic expression not a command.  To avoid the
11897 confusion, insert a space between the two opening parentheses.
11899 Avoid @var{commands} that contain unbalanced parentheses in
11900 here-documents, comments, or case statement patterns, as many shells
11901 mishandle them.  For example, Bash 3.1, @samp{ksh88}, @command{pdksh}
11902 5.2.14, and Zsh 4.2.6 all mishandle the following valid command:
11904 @example
11905 echo $(case x in x) echo hello;; esac)
11906 @end example
11908 @item ^
11909 @cindex ^ quoting
11910 Always quote @samp{^}, otherwise traditional shells such as
11911 @command{/bin/sh} on Solaris 10 treat this like @samp{|}.
11913 @end table
11916 @node Assignments
11917 @section Assignments
11918 @cindex Shell assignments
11920 When setting several variables in a row, be aware that the order of the
11921 evaluation is undefined.  For instance @samp{foo=1 foo=2; echo $foo}
11922 gives @samp{1} with Solaris @command{/bin/sh}, but @samp{2} with Bash.
11923 You must use
11924 @samp{;} to enforce the order: @samp{foo=1; foo=2; echo $foo}.
11926 Don't rely on the following to find @file{subdir/program}:
11928 @example
11929 PATH=subdir$PATH_SEPARATOR$PATH program
11930 @end example
11932 @noindent
11933 as this does not work with Zsh 3.0.6.  Use something like this
11934 instead:
11936 @example
11937 (PATH=subdir$PATH_SEPARATOR$PATH; export PATH; exec program)
11938 @end example
11940 Don't rely on the exit status of an assignment: Ash 0.2 does not change
11941 the status and propagates that of the last statement:
11943 @example
11944 $ @kbd{false || foo=bar; echo $?}
11946 $ @kbd{false || foo=`:`; echo $?}
11948 @end example
11950 @noindent
11951 and to make things even worse, @acronym{QNX} 4.25 just sets the exit status
11952 to 0 in any case:
11954 @example
11955 $ @kbd{foo=`exit 1`; echo $?}
11957 @end example
11959 To assign default values, follow this algorithm:
11961 @enumerate
11962 @item
11963 If the default value is a literal and does not contain any closing
11964 brace, use:
11966 @example
11967 : $@{var='my literal'@}
11968 @end example
11970 @item
11971 If the default value contains no closing brace, has to be expanded, and
11972 the variable being initialized is not intended to be IFS-split
11973 (i.e., it's not a list), then use:
11975 @example
11976 : $@{var="$default"@}
11977 @end example
11979 @item
11980 If the default value contains no closing brace, has to be expanded, and
11981 the variable being initialized is intended to be IFS-split (i.e., it's a list),
11982 then use:
11984 @example
11985 var=$@{var="$default"@}
11986 @end example
11988 @item
11989 If the default value contains a closing brace, then use:
11991 @example
11992 test "$@{var+set@}" = set || var="has a '@}'"
11993 @end example
11994 @end enumerate
11996 In most cases @samp{var=$@{var="$default"@}} is fine, but in case of
11997 doubt, just use the last form.  @xref{Shell Substitutions}, items
11998 @samp{$@{@var{var}:-@var{value}@}} and @samp{$@{@var{var}=@var{value}@}}
11999 for the rationale.
12001 @node Parentheses
12002 @section Parentheses in Shell Scripts
12003 @cindex Shell parentheses
12005 Beware of two opening parentheses in a row, as many shell
12006 implementations treat them specially.  Posix requires that the command
12007 @samp{((cat))} must behave like @samp{(cat)}, but many shells, including
12008 Bash and the Korn shell, treat @samp{((cat))} as an arithmetic
12009 expression equivalent to @samp{let "cat"}, and may or may not report an
12010 error when they detect that @samp{cat} is not a number.  As another
12011 example, @samp{pdksh} 5.2.14 misparses the following code:
12013 @example
12014 if ((true) || false); then
12015   echo ok
12017 @end example
12019 @noindent
12020 To work around this problem, insert a space between the two opening
12021 parentheses.  There is a similar problem and workaround with
12022 @samp{$((}; see @ref{Shell Substitutions}.
12024 @node Slashes
12025 @section Slashes in Shell Scripts
12026 @cindex Shell slashes
12028 Unpatched Tru64 5.1 @command{sh} omits the last slash of command-line
12029 arguments that contain two trailing slashes:
12031 @example
12032 $ @kbd{echo / // /// //// .// //.}
12033 / / // /// ./ //.
12034 $ @kbd{x=//}
12035 $ @kbd{eval "echo \$x"}
12037 $ @kbd{set -x}
12038 $ @kbd{echo abc | tr -t ab //}
12039 + echo abc
12040 + tr -t ab /
12042 @end example
12044 Unpatched Tru64 4.0 @command{sh} adds a slash after @samp{"$var"} if the
12045 variable is empty and the second double-quote is followed by a word that
12046 begins and ends with slash:
12048 @example
12049 $ @kbd{sh -xc 'p=; echo "$p"/ouch/'}
12051 + echo //ouch/
12052 //ouch/
12053 @end example
12055 However, our understanding is that patches are available, so perhaps
12056 it's not worth worrying about working around these horrendous bugs.
12058 @node Special Shell Variables
12059 @section Special Shell Variables
12060 @cindex Shell variables
12061 @cindex Special shell variables
12063 Some shell variables should not be used, since they can have a deep
12064 influence on the behavior of the shell.  In order to recover a sane
12065 behavior from the shell, some variables should be unset, but
12066 @command{unset} is not portable (@pxref{Limitations of Builtins}) and a
12067 fallback value is needed.
12069 As a general rule, shell variable names containing a lower-case letter
12070 are safe; you can define and use these variables without worrying about
12071 their effect on the underlying system, and without worrying about
12072 whether the shell changes them unexpectedly.  (The exception is the
12073 shell variable @code{status}, as described below.)
12075 Here is a list of names that are known to cause trouble.  This list is
12076 not exhaustive, but you should be safe if you avoid the name
12077 @code{status} and names containing only upper-case letters and
12078 underscores.
12080 @c Alphabetical order, case insensitive, `A' before `a'.
12081 @table @code
12082 @item _
12083 Many shells reserve @samp{$_} for various purposes, e.g., the name of
12084 the last command executed.
12086 @item BIN_SH
12087 @evindex BIN_SH
12088 In Tru64, if @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of
12089 the standard shell conform to Posix.
12091 @item CDPATH
12092 @evindex CDPATH
12093 When this variable is set it specifies a list of directories to search
12094 when invoking @code{cd} with a relative file name that did not start
12095 with @samp{./} or @samp{../}.  Posix
12096 1003.1-2001 says that if a nonempty directory name from @env{CDPATH}
12097 is used successfully, @code{cd} prints the resulting absolute
12098 file name.  Unfortunately this output can break idioms like
12099 @samp{abs=`cd src && pwd`} because @code{abs} receives the name twice.
12100 Also, many shells do not conform to this part of Posix; for
12101 example, @command{zsh} prints the result only if a directory name
12102 other than @file{.} was chosen from @env{CDPATH}.
12104 In practice the shells that have this problem also support
12105 @command{unset}, so you can work around the problem as follows:
12107 @example
12108 (unset CDPATH) >/dev/null 2>&1 && unset CDPATH
12109 @end example
12111 You can also avoid output by ensuring that your directory name is
12112 absolute or anchored at @samp{./}, as in @samp{abs=`cd ./src && pwd`}.
12114 Autoconf-generated scripts automatically unset @env{CDPATH} if
12115 possible, so you need not worry about this problem in those scripts.
12117 @item DUALCASE
12118 @evindex DUALCASE
12119 In the MKS shell, case statements and file name generation are
12120 case-insensitive unless @env{DUALCASE} is nonzero.
12121 Autoconf-generated scripts export this variable when they start up.
12123 @item ENV
12124 @itemx MAIL
12125 @itemx MAILPATH
12126 @itemx PS1
12127 @itemx PS2
12128 @itemx PS4
12129 @evindex ENV
12130 @evindex MAIL
12131 @evindex MAILPATH
12132 @evindex PS1
12133 @evindex PS2
12134 @evindex PS4
12135 These variables should not matter for shell scripts, since they are
12136 supposed to affect only interactive shells.  However, at least one
12137 shell (the pre-3.0 @sc{uwin} Korn shell) gets confused about
12138 whether it is interactive, which means that (for example) a @env{PS1}
12139 with a side effect can unexpectedly modify @samp{$?}.  To work around
12140 this bug, Autoconf-generated scripts do something like this:
12142 @example
12143 (unset ENV) >/dev/null 2>&1 && unset ENV MAIL MAILPATH
12144 PS1='$ '
12145 PS2='> '
12146 PS4='+ '
12147 @end example
12149 @item FPATH
12150 The Korn shell uses @env{FPATH} to find shell functions, so avoid
12151 @env{FPATH} in portable scripts.  @env{FPATH} is consulted after
12152 @env{PATH}, but you still need to be wary of tests that use @env{PATH}
12153 to find whether a command exists, since they might report the wrong
12154 result if @env{FPATH} is also set.
12156 @item IFS
12157 @evindex IFS
12158 Long ago, shell scripts inherited @env{IFS} from the environment,
12159 but this caused many problems so modern shells ignore any environment
12160 settings for @env{IFS}.
12162 Don't set the first character of @code{IFS} to backslash.  Indeed,
12163 Bourne shells use the first character (backslash) when joining the
12164 components in @samp{"$@@"} and some shells then reinterpret (!)@: the
12165 backslash escapes, so you can end up with backspace and other strange
12166 characters.
12168 The proper value for @code{IFS} (in regular code, not when performing
12169 splits) is @samp{@key{SPC}@key{TAB}@key{RET}}.  The first character is
12170 especially important, as it is used to join the arguments in @samp{$*};
12171 however, note that traditional shells, but also bash-2.04, fail to adhere
12172 to this and join with a space anyway.
12174 @item LANG
12175 @itemx LC_ALL
12176 @itemx LC_COLLATE
12177 @itemx LC_CTYPE
12178 @itemx LC_MESSAGES
12179 @itemx LC_MONETARY
12180 @itemx LC_NUMERIC
12181 @itemx LC_TIME
12182 @evindex LANG
12183 @evindex LC_ALL
12184 @evindex LC_COLLATE
12185 @evindex LC_CTYPE
12186 @evindex LC_MESSAGES
12187 @evindex LC_MONETARY
12188 @evindex LC_NUMERIC
12189 @evindex LC_TIME
12191 Autoconf-generated scripts normally set all these variables to
12192 @samp{C} because so much configuration code assumes the C locale and
12193 Posix requires that locale environment variables be set to
12194 @samp{C} if the C locale is desired.  However, some older, nonstandard
12195 systems (notably @acronym{SCO}) break if locale environment variables
12196 are set to @samp{C}, so when running on these systems
12197 Autoconf-generated scripts unset the variables instead.
12199 @item LANGUAGE
12200 @evindex LANGUAGE
12202 @env{LANGUAGE} is not specified by Posix, but it is a @acronym{GNU}
12203 extension that overrides @env{LC_ALL} in some cases, so
12204 Autoconf-generated scripts set it too.
12206 @item LC_ADDRESS
12207 @itemx LC_IDENTIFICATION
12208 @itemx LC_MEASUREMENT
12209 @itemx LC_NAME
12210 @itemx LC_PAPER
12211 @itemx LC_TELEPHONE
12212 @evindex LC_ADDRESS
12213 @evindex LC_IDENTIFICATION
12214 @evindex LC_MEASUREMENT
12215 @evindex LC_NAME
12216 @evindex LC_PAPER
12217 @evindex LC_TELEPHONE
12219 These locale environment variables are @acronym{GNU} extensions.  They
12220 are treated like their Posix brethren (@env{LC_COLLATE},
12221 etc.)@: as described above.
12223 @item LINENO
12224 Most modern shells provide the current line number in @code{LINENO}.
12225 Its value is the line number of the beginning of the current command.
12226 Autoconf attempts to execute @command{configure} with a shell that
12227 supports @code{LINENO}.
12228 If no such shell is available, it attempts to implement @code{LINENO}
12229 with a Sed prepass that replaces each instance of the string
12230 @code{$LINENO} (not followed by an alphanumeric character) with the
12231 line's number.
12233 You should not rely on @code{LINENO} within @command{eval}, as the
12234 behavior differs in practice.  Also, the possibility of the Sed
12235 prepass means that you should not rely on @code{$LINENO} when quoted,
12236 when in here-documents, or when in long commands that cross line
12237 boundaries.  Subshells should be OK, though.  In the following
12238 example, lines 1, 6, and 9 are portable, but the other instances of
12239 @code{LINENO} are not:
12241 @example
12242 @group
12243 $ @kbd{cat lineno}
12244 echo 1. $LINENO
12245 cat <<EOF
12246 3. $LINENO
12247 4. $LINENO
12249 ( echo 6. $LINENO )
12250 eval 'echo 7. $LINENO'
12251 echo 8. '$LINENO'
12252 echo 9. $LINENO '
12253 10.' $LINENO
12254 @end group
12255 @group
12256 $ @kbd{bash-2.05 lineno}
12257 1. 1
12258 3. 2
12259 4. 2
12260 6. 6
12261 7. 1
12262 8. $LINENO
12263 9. 9
12264 10. 9
12265 @end group
12266 @group
12267 $ @kbd{zsh-3.0.6 lineno}
12268 1. 1
12269 3. 2
12270 4. 2
12271 6. 6
12272 7. 7
12273 8. $LINENO
12274 9. 9
12275 10. 9
12276 @end group
12277 @group
12278 $ @kbd{pdksh-5.2.14 lineno}
12279 1. 1
12280 3. 2
12281 4. 2
12282 6. 6
12283 7. 0
12284 8. $LINENO
12285 9. 9
12286 10. 9
12287 @end group
12288 @group
12289 $ @kbd{sed '=' <lineno |}
12290 > @kbd{  sed '}
12291 > @kbd{    N}
12292 > @kbd{    s,$,-,}
12293 > @kbd{    t loop}
12294 > @kbd{    :loop}
12295 > @kbd{    s,^\([0-9]*\)\(.*\)[$]LINENO\([^a-zA-Z0-9_]\),\1\2\1\3,}
12296 > @kbd{    t loop}
12297 > @kbd{    s,-$,,}
12298 > @kbd{    s,^[0-9]*\n,,}
12299 > @kbd{  ' |}
12300 > @kbd{  sh}
12301 1. 1
12302 3. 3
12303 4. 4
12304 6. 6
12305 7. 7
12306 8. 8
12307 9. 9
12308 10. 10
12309 @end group
12310 @end example
12312 @item NULLCMD
12313 @evindex NULLCMD
12314 When executing the command @samp{>foo}, @command{zsh} executes
12315 @samp{$NULLCMD >foo} unless it is operating in Bourne shell
12316 compatibility mode and the @command{zsh} version is newer
12317 than 3.1.6-dev-18.  If you are using an older @command{zsh}
12318 and forget to set @env{NULLCMD},
12319 your script might be suspended waiting for data on its standard input.
12321 @item PATH_SEPARATOR
12322 @evindex PATH_SEPARATOR
12323 On @acronym{DJGPP} systems, the @env{PATH_SEPARATOR} environment
12324 variable can be set to either @samp{:} or @samp{;} to control the path
12325 separator Bash uses to set up certain environment variables (such as
12326 @env{PATH}).  You can set this variable to @samp{;} if you want
12327 @command{configure} to use @samp{;} as a separator; this might be useful
12328 if you plan to use non-Posix shells to execute files.  @xref{File System
12329 Conventions}, for more information about @code{PATH_SEPARATOR}.
12331 @item PWD
12332 @evindex PWD
12333 Posix 1003.1-2001 requires that @command{cd} and
12334 @command{pwd} must update the @env{PWD} environment variable to point
12335 to the logical name of the current directory, but traditional shells
12336 do not support this.  This can cause confusion if one shell instance
12337 maintains @env{PWD} but a subsidiary and different shell does not know
12338 about @env{PWD} and executes @command{cd}; in this case @env{PWD}
12339 points to the wrong directory.  Use @samp{`pwd`} rather than
12340 @samp{$PWD}.
12342 @item RANDOM
12343 Many shells provide @code{RANDOM}, a variable that returns a different
12344 integer each time it is used.  Most of the time, its value does not
12345 change when it is not used, but on @sc{irix} 6.5 the value changes all
12346 the time.  This can be observed by using @command{set}.  It is common
12347 practice to use @code{$RANDOM} as part of a file name, but code
12348 shouldn't rely on @code{$RANDOM} expanding to a nonempty string.
12350 @item status
12351 This variable is an alias to @samp{$?} for @code{zsh} (at least 3.1.6),
12352 hence read-only.  Do not use it.
12353 @end table
12355 @node Limitations of Builtins
12356 @section Limitations of Shell Builtins
12357 @cindex Shell builtins
12358 @cindex Limitations of shell builtins
12360 No, no, we are serious: some shells do have limitations!  :)
12362 You should always keep in mind that any builtin or command may support
12363 options, and therefore differ in behavior with arguments
12364 starting with a dash.  For instance, the innocent @samp{echo "$word"}
12365 can give unexpected results when @code{word} starts with a dash.  It is
12366 often possible to avoid this problem using @samp{echo "x$word"}, taking
12367 the @samp{x} into account later in the pipe.
12369 @table @asis
12370 @item @command{.}
12371 @prindex @command{.}
12372 Use @command{.} only with regular files (use @samp{test -f}).  Bash
12373 2.03, for instance, chokes on @samp{. /dev/null}.  Also, remember that
12374 @command{.} uses @env{PATH} if its argument contains no slashes, so if
12375 you want to use @command{.} on a file @file{foo} in the current
12376 directory, you must use @samp{. ./foo}.
12378 @item @command{!}
12379 @prindex @command{!}
12380 The Unix version 7 shell did not support
12381 negating the exit status of commands with @command{!}, and this feature
12382 is still absent from some shells (e.g., Solaris @command{/bin/sh}).
12383 Shell code like this:
12385 @example
12386 if ! cmp file1 file2 >/dev/null 2>&1; then
12387   echo files differ or trouble
12389 @end example
12391 is therefore not portable in practice.  Typically it is easy to rewrite
12392 such code, e.g.:
12394 @example
12395 cmp file1 file2 >/dev/null 2>&1 ||
12396   echo files differ or trouble
12397 @end example
12399 More generally, one can always rewrite @samp{! @var{command}} as:
12401 @example
12402 if @var{command}; then (exit 1); else :; fi
12403 @end example
12405 @item @command{break}
12406 @c ------------------
12407 @prindex @command{break}
12408 The use of @samp{break 2} etc.@: is safe.
12411 @item @command{case}
12412 @c -----------------
12413 @prindex @command{case}
12414 You don't need to quote the argument; no splitting is performed.
12416 You don't need the final @samp{;;}, but you should use it.
12418 Posix requires support for @code{case} patterns with opening
12419 parentheses like this:
12421 @example
12422 case $file_name in
12423 (*.c) echo "C source code";;
12424 esac
12425 @end example
12427 @noindent
12428 but the @code{(} in this example is not portable to many Bourne
12429 shell implementations.  It can be omitted safely.
12431 Zsh handles pattern fragments derived from parameter expansions or
12432 command substitutions as though quoted:
12434 @example
12435 $ pat=\?; case aa in ?$pat) echo match;; esac
12436 $ pat=\?; case a? in ?$pat) echo match;; esac
12437 match
12438 @end example
12440 @noindent
12441 Because of a bug in its @code{fnmatch}, Bash fails to properly
12442 handle backslashes in character classes:
12444 @example
12445 bash-2.02$ @kbd{case /tmp in [/\\]*) echo OK;; esac}
12446 bash-2.02$
12447 @end example
12449 @noindent
12450 This is extremely unfortunate, since you are likely to use this code to
12451 handle Posix or @sc{ms-dos} absolute file names.  To work around this
12452 bug, always put the backslash first:
12454 @example
12455 bash-2.02$ @kbd{case '\TMP' in [\\/]*) echo OK;; esac}
12457 bash-2.02$ @kbd{case /tmp in [\\/]*) echo OK;; esac}
12459 @end example
12461 Many Bourne shells cannot handle closing brackets in character classes
12462 correctly.
12464 Some shells also have problems with backslash escaping in case you do not want
12465 to match the backslash: both a backslash and the escaped character match this
12466 pattern.  To work around this, specify the character class in a variable, so
12467 that quote removal does not apply afterwards, and the special characters don't
12468 have to be backslash-escaped:
12470 @example
12471 $ @kbd{case '\' in [\<]) echo OK;; esac}
12473 $ @kbd{scanset='[<]'; case '\' in $scanset) echo OK;; esac}
12475 @end example
12477 Even with this, Solaris @command{ksh} matches a backslash if the set
12478 contains any
12479 of the characters @samp{|}, @samp{&}, @samp{(}, or @samp{)}.
12481 Conversely, Tru64 @command{ksh} (circa 2003) erroneously always matches
12482 a closing parenthesis if not specified in a character class:
12484 @example
12485 $ @kbd{case foo in *\)*) echo fail ;; esac}
12486 fail
12487 $ @kbd{case foo in *')'*) echo fail ;; esac}
12488 fail
12489 @end example
12491 Some shells, such as Ash 0.3.8, are confused by an empty
12492 @code{case}/@code{esac}:
12494 @example
12495 ash-0.3.8 $ @kbd{case foo in esac;}
12496 @error{}Syntax error: ";" unexpected (expecting ")")
12497 @end example
12499 Many shells still do not support parenthesized cases, which is a pity
12500 for those of us using tools that rely on balanced parentheses.  For
12501 instance, Solaris @command{/bin/sh}:
12503 @example
12504 $ @kbd{case foo in (foo) echo foo;; esac}
12505 @error{}syntax error: `(' unexpected
12506 @end example
12509 @item @command{cd}
12510 @c ---------------
12511 @prindex @command{cd}
12512 Posix 1003.1-2001 requires that @command{cd} must support
12513 the @option{-L} (``logical'') and @option{-P} (``physical'') options,
12514 with @option{-L} being the default.  However, traditional shells do
12515 not support these options, and their @command{cd} command has the
12516 @option{-P} behavior.
12518 Portable scripts should assume neither option is supported, and should
12519 assume neither behavior is the default.  This can be a bit tricky,
12520 since the Posix default behavior means that, for example,
12521 @samp{ls ..} and @samp{cd ..} may refer to different directories if
12522 the current logical directory is a symbolic link.  It is safe to use
12523 @command{cd @var{dir}} if @var{dir} contains no @file{..} components.
12524 Also, Autoconf-generated scripts check for this problem when computing
12525 variables like @code{ac_top_srcdir} (@pxref{Configuration Actions}),
12526 so it is safe to @command{cd} to these variables.
12528 See @xref{Special Shell Variables}, for portability problems involving
12529 @command{cd} and the @env{CDPATH} environment variable.
12530 Also please see the discussion of the @command{pwd} command.
12533 @item @command{echo}
12534 @c -----------------
12535 @prindex @command{echo}
12536 The simple @command{echo} is probably the most surprising source of
12537 portability troubles.  It is not possible to use @samp{echo} portably
12538 unless both options and escape sequences are omitted.  New applications
12539 which are not aiming at portability should use @samp{printf} instead of
12540 @samp{echo}.
12542 Don't expect any option.  @xref{Preset Output Variables}, @code{ECHO_N}
12543 etc.@: for a means to simulate @option{-n}.
12545 Do not use backslashes in the arguments, as there is no consensus on
12546 their handling.  For @samp{echo '\n' | wc -l}, the @command{sh} of
12547 Solaris outputs 2, but Bash and Zsh (in @command{sh} emulation mode) output 1.
12548 The problem is truly @command{echo}: all the shells
12549 understand @samp{'\n'} as the string composed of a backslash and an
12550 @samp{n}.
12552 Because of these problems, do not pass a string containing arbitrary
12553 characters to @command{echo}.  For example, @samp{echo "$foo"} is safe
12554 if you know that @var{foo}'s value cannot contain backslashes and cannot
12555 start with @samp{-}, but otherwise you should use a here-document like
12556 this:
12558 @example
12559 cat <<EOF
12560 $foo
12562 @end example
12565 @item @command{eval}
12566 @c -----------------
12567 @prindex @command{eval}
12568 The @command{eval} command is useful in limited circumstances, e.g.,
12569 using commands like @samp{eval table_$key=\$value} and @samp{eval
12570 value=table_$key} to simulate a hash table when the key is known to be
12571 alphanumeric.  However, @command{eval} is tricky to use on arbitrary
12572 arguments, even when it is implemented correctly.
12574 It is obviously unwise to use @samp{eval $cmd} if the string value of
12575 @samp{cmd} was derived from an untrustworthy source.  But even if the
12576 string value is valid, @samp{eval $cmd} might not work as intended,
12577 since it causes field splitting and file name expansion to occur twice,
12578 once for the @command{eval} and once for the command itself.  It is
12579 therefore safer to use @samp{eval "$cmd"}.  For example, if @var{cmd}
12580 has the value @samp{cat test?.c}, @samp{eval $cmd} might expand to the
12581 equivalent of @samp{cat test;.c} if there happens to be a file named
12582 @file{test;.c} in the current directory; and this in turn
12583 mistakenly attempts to invoke @command{cat} on the file @file{test} and
12584 then execute the command @command{.c}.  To avoid this problem, use
12585 @samp{eval "$cmd"} rather than @samp{eval $cmd}.
12587 However, suppose that you want to output the text of the evaluated
12588 command just before executing it.  Assuming the previous example,
12589 @samp{echo "Executing: $cmd"} outputs @samp{Executing: cat test?.c}, but
12590 this output doesn't show the user that @samp{test;.c} is the actual name
12591 of the copied file.  Conversely, @samp{eval "echo Executing: $cmd"}
12592 works on this example, but it fails with @samp{cmd='cat foo >bar'},
12593 since it mistakenly replaces the contents of @file{bar} by the
12594 string @samp{cat foo}.  No simple, general, and portable solution to
12595 this problem is known.
12597 You should also be wary of common bugs in @command{eval} implementations.
12598 In some shell implementations (e.g., older @command{ash}, Open@acronym{BSD} 3.8
12599 @command{sh}, @command{pdksh} v5.2.14 99/07/13.2, and @command{zsh}
12600 4.2.5), the arguments of @samp{eval} are evaluated in a context where
12601 @samp{$?} is 0, so they exhibit behavior like this:
12603 @example
12604 $ @kbd{false; eval 'echo $?'}
12606 @end example
12608 The correct behavior here is to output a nonzero value,
12609 but portable scripts should not rely on this.
12611 You should not rely on @code{LINENO} within @command{eval}.
12612 @xref{Special Shell Variables}.
12614 @item @command{exit}
12615 @c -----------------
12616 @prindex @command{exit}
12617 The default value of @command{exit} is supposed to be @code{$?};
12618 unfortunately, some shells, such as the @acronym{DJGPP} port of Bash 2.04, just
12619 perform @samp{exit 0}.
12621 @example
12622 bash-2.04$ @kbd{foo=`exit 1` || echo fail}
12623 fail
12624 bash-2.04$ @kbd{foo=`(exit 1)` || echo fail}
12625 fail
12626 bash-2.04$ @kbd{foo=`(exit 1); exit` || echo fail}
12627 bash-2.04$
12628 @end example
12630 Using @samp{exit $?} restores the expected behavior.
12632 Some shell scripts, such as those generated by @command{autoconf}, use a
12633 trap to clean up before exiting.  If the last shell command exited with
12634 nonzero status, the trap also exits with nonzero status so that the
12635 invoker can tell that an error occurred.
12637 Unfortunately, in some shells, such as Solaris @command{/bin/sh}, an exit
12638 trap ignores the @code{exit} command's argument.  In these shells, a trap
12639 cannot determine whether it was invoked by plain @code{exit} or by
12640 @code{exit 1}.  Instead of calling @code{exit} directly, use the
12641 @code{AC_MSG_ERROR} macro that has a workaround for this problem.
12644 @item @command{export}
12645 @c -------------------
12646 @prindex @command{export}
12647 The builtin @command{export} dubs a shell variable @dfn{environment
12648 variable}.  Each update of exported variables corresponds to an update
12649 of the environment variables.  Conversely, each environment variable
12650 received by the shell when it is launched should be imported as a shell
12651 variable marked as exported.
12653 Alas, many shells, such as Solaris @command{/bin/sh},
12654 @sc{irix} 6.3, @sc{irix} 5.2,
12655 @acronym{AIX} 4.1.5, and Digital Unix 4.0, forget to
12656 @command{export} the environment variables they receive.  As a result,
12657 two variables coexist: the environment variable and the shell
12658 variable.  The following code demonstrates this failure:
12660 @example
12661 #!/bin/sh
12662 echo $FOO
12663 FOO=bar
12664 echo $FOO
12665 exec /bin/sh $0
12666 @end example
12668 @noindent
12669 when run with @samp{FOO=foo} in the environment, these shells print
12670 alternately @samp{foo} and @samp{bar}, although they should print only
12671 @samp{foo} and then a sequence of @samp{bar}s.
12673 Therefore you should @command{export} again each environment variable
12674 that you update.
12677 @item @command{false}
12678 @c ------------------
12679 @prindex @command{false}
12680 Don't expect @command{false} to exit with status 1: in native
12681 Solaris @file{/bin/false} exits with status 255.
12684 @item @command{for}
12685 @c ----------------
12686 @prindex @command{for}
12687 To loop over positional arguments, use:
12689 @example
12690 for arg
12692   echo "$arg"
12693 done
12694 @end example
12696 @noindent
12697 You may @emph{not} leave the @code{do} on the same line as @code{for},
12698 since some shells improperly grok:
12700 @example
12701 for arg; do
12702   echo "$arg"
12703 done
12704 @end example
12706 If you want to explicitly refer to the positional arguments, given the
12707 @samp{$@@} bug (@pxref{Shell Substitutions}), use:
12709 @example
12710 for arg in $@{1+"$@@"@}; do
12711   echo "$arg"
12712 done
12713 @end example
12715 @noindent
12716 But keep in mind that Zsh, even in Bourne shell emulation mode, performs
12717 word splitting on @samp{$@{1+"$@@"@}}; see @ref{Shell Substitutions},
12718 item @samp{$@@}, for more.
12721 @item @command{if}
12722 @c ---------------
12723 @prindex @command{if}
12724 Using @samp{!} is not portable.  Instead of:
12726 @example
12727 if ! cmp -s file file.new; then
12728   mv file.new file
12730 @end example
12732 @noindent
12733 use:
12735 @example
12736 if cmp -s file file.new; then :; else
12737   mv file.new file
12739 @end example
12741 There are shells that do not reset the exit status from an @command{if}:
12743 @example
12744 $ @kbd{if (exit 42); then true; fi; echo $?}
12746 @end example
12748 @noindent
12749 whereas a proper shell should have printed @samp{0}.  This is especially
12750 bad in makefiles since it produces false failures.  This is why properly
12751 written makefiles, such as Automake's, have such hairy constructs:
12753 @example
12754 if test -f "$file"; then
12755   install "$file" "$dest"
12756 else
12757   :
12759 @end example
12762 @item @command{printf}
12763 @c ------------------
12764 @prindex @command{printf}
12765 A format string starting with a @samp{-} can cause problems.
12766 Bash interprets it as an option and
12767 gives an error.  And @samp{--} to mark the end of options is not good
12768 in the Net@acronym{BSD} Almquist shell (e.g., 0.4.6) which takes that
12769 literally as the format string.  Putting the @samp{-} in a @samp{%c}
12770 or @samp{%s} is probably easiest:
12772 @example
12773 printf %s -foo
12774 @end example
12776 Bash 2.03 mishandles an escape sequence that happens to evaluate to @samp{%}:
12778 @example
12779 $ @kbd{printf '\045'}
12780 bash: printf: `%': missing format character
12781 @end example
12783 Large outputs may cause trouble.  On Solaris 2.5.1 through 10, for
12784 example, @file{/usr/bin/printf} is buggy, so when using
12785 @command{/bin/sh} the command @samp{printf %010000x 123} normally dumps
12786 core.
12789 @item @command{read}
12790 @c ------------------
12791 @prindex @command{read}
12792 Not all shells support @option{-r} (Solaris @command{/bin/sh} for example).
12795 @item @command{pwd}
12796 @c ----------------
12797 @prindex @command{pwd}
12798 With modern shells, plain @command{pwd} outputs a ``logical''
12799 directory name, some of whose components may be symbolic links.  These
12800 directory names are in contrast to ``physical'' directory names, whose
12801 components are all directories.
12803 Posix 1003.1-2001 requires that @command{pwd} must support
12804 the @option{-L} (``logical'') and @option{-P} (``physical'') options,
12805 with @option{-L} being the default.  However, traditional shells do
12806 not support these options, and their @command{pwd} command has the
12807 @option{-P} behavior.
12809 Portable scripts should assume neither option is supported, and should
12810 assume neither behavior is the default.  Also, on many hosts
12811 @samp{/bin/pwd} is equivalent to @samp{pwd -P}, but Posix
12812 does not require this behavior and portable scripts should not rely on
12815 Typically it's best to use plain @command{pwd}.  On modern hosts this
12816 outputs logical directory names, which have the following advantages:
12818 @itemize @bullet
12819 @item
12820 Logical names are what the user specified.
12821 @item
12822 Physical names may not be portable from one installation
12823 host to another due to network file system gymnastics.
12824 @item
12825 On modern hosts @samp{pwd -P} may fail due to lack of permissions to
12826 some parent directory, but plain @command{pwd} cannot fail for this
12827 reason.
12828 @end itemize
12830 Also please see the discussion of the @command{cd} command.
12833 @item @command{set}
12834 @c ----------------
12835 @prindex @command{set}
12836 With the Free@acronym{BSD} 6.0 shell, the @command{set} command (without
12837 any options) does not sort its output.
12839 The @command{set} builtin faces the usual problem with arguments starting with a
12840 dash.  Modern shells such as Bash or Zsh understand @option{--} to specify
12841 the end of the options (any argument after @option{--} is a parameter,
12842 even @samp{-x} for instance), but many traditional shells (e.g., Solaris
12843 10 @command{/bin/sh}) simply stop option
12844 processing as soon as a non-option argument is found.  Therefore, use
12845 @samp{dummy} or simply @samp{x} to end the option processing, and use
12846 @command{shift} to pop it out:
12848 @example
12849 set x $my_list; shift
12850 @end example
12852 Avoid @samp{set -}, e.g., @samp{set - $my_list}.  Posix no
12853 longer requires support for this command, and in traditional shells
12854 @samp{set - $my_list} resets the @option{-v} and @option{-x} options, which
12855 makes scripts harder to debug.
12857 Some nonstandard shells do not recognize more than one option
12858 (e.g., @samp{set -e -x} assigns @samp{-x} to the command line).  It is
12859 better to combine them:
12861 @example
12862 set -ex
12863 @end example
12865 The @acronym{BSD} shell has had several problems with the @option{-e}
12866 option, partly because @acronym{BSD} @command{make} traditionally used
12867 @option{-e} even though this was incompatible with Posix
12868 (@pxref{Failure in Make Rules}).  Older versions of the @acronym{BSD}
12869 shell (circa 1990) mishandled @samp{&&}, @samp{||}, @samp{if}, and
12870 @samp{case} when @option{-e} was in effect, causing the shell to exit
12871 unexpectedly in some cases.  This was particularly a problem with
12872 makefiles, and led to circumlocutions like @samp{sh -c 'test -f file ||
12873 touch file'}, where the seemingly-unnecessary @samp{sh -c '@dots{}'}
12874 wrapper works around the bug.
12876 Even relatively-recent versions of the @acronym{BSD} shell (e.g.,
12877 Open@acronym{BSD} 3.4) wrongly exit with @option{-e} if a command within
12878 @samp{&&} fails inside a compound statement.  For example:
12880 @example
12881 #! /bin/sh
12882 set -e
12883 foo=''
12884 test -n "$foo" && exit 1
12885 echo one
12886 if :; then
12887   test -n "$foo" && exit 1
12889 echo two
12890 @end example
12892 @noindent
12893 does not print @samp{two}.  One workaround is to use @samp{if test -n
12894 "$foo"; then exit 1; fi} rather than @samp{test -n "$foo" && exit 1}.
12895 Another possibility is to warn @acronym{BSD} users not to use @samp{sh -e}.
12898 @item @command{shift}
12899 @c ------------------
12900 @prindex @command{shift}
12901 Not only is @command{shift}ing a bad idea when there is nothing left to
12902 shift, but in addition it is not portable: the shell of @acronym{MIPS
12903 RISC/OS} 4.52 refuses to do it.
12905 Don't use @samp{shift 2} etc.; it was not in the 7th Edition Bourne shell,
12906 and it is also absent in many pre-Posix shells.
12909 @item @command{source}
12910 @c -------------------
12911 @prindex @command{source}
12912 This command is not portable, as Posix does not require it; use
12913 @command{.} instead.
12916 @item @command{test}
12917 @c -----------------
12918 @prindex @command{test}
12919 The @code{test} program is the way to perform many file and string
12920 tests.  It is often invoked by the alternate name @samp{[}, but using
12921 that name in Autoconf code is asking for trouble since it is an M4 quote
12922 character.
12924 The @option{-a}, @option{-o}, @samp{(}, and @samp{)} operands are not
12925 portable and should be avoided.  Thus, portable uses of @command{test}
12926 should never have more than four arguments, and scripts should use shell
12927 constructs like @samp{&&} and @samp{||} instead.  If you combine
12928 @samp{&&} and @samp{||} in the same statement, keep in mind that they
12929 have equal precedence, so it is often better to parenthesize even when
12930 this is redundant.  For example:
12932 @smallexample
12933 # Not portable:
12934 test "X$a" = "X$b" -a \
12935   '(' "X$c" != "X$d" -o "X$e" = "X$f" ')'
12937 # Portable:
12938 test "X$a" = "X$b" &&
12939   @{ test "X$c" != "X$d" || test "X$e" = "X$f"; @}
12940 @end smallexample
12942 @command{test} does not process options like most other commands do; for
12943 example, it does not recognize the @option{--} argument as marking the
12944 end of options.
12946 It is safe to use @samp{!} as a @command{test} operator.  For example,
12947 @samp{if test ! -d foo; @dots{}} is portable even though @samp{if ! test
12948 -d foo; @dots{}} is not.
12951 @item @command{test} (files)
12952 @c -------------------------
12953 To enable @command{configure} scripts to support cross-compilation, they
12954 shouldn't do anything that tests features of the build system instead of
12955 the host system.  But occasionally you may find it necessary to check
12956 whether some arbitrary file exists.  To do so, use @samp{test -f} or
12957 @samp{test -r}.  Do not use @samp{test -x}, because 4.3@acronym{BSD} does not
12958 have it.  Do not use @samp{test -e} either, because Solaris @command{/bin/sh}
12959 lacks it.  To test for symbolic links on systems that have them, use
12960 @samp{test -h} rather than @samp{test -L}; either form conforms to
12961 Posix 1003.1-2001, but older shells like Solaris 8
12962 @code{/bin/sh} support only @option{-h}.
12964 @item @command{test} (strings)
12965 @c ---------------------------
12966 Posix says that @samp{test "@var{string}"} succeeds if @var{string} is
12967 not null, but this usage is not portable to traditional platforms like
12968 Solaris 10 @command{/bin/sh}, which mishandle strings like @samp{!} and
12969 @samp{-n}.
12971 Posix says that @samp{test ! "@var{string}"}, @samp{test -n "@var{string}"} and
12972 @samp{test -z "@var{string}"} work with any string, but many
12973 shells (such as Solaris, @acronym{AIX} 3.2, @sc{unicos} 10.0.0.6,
12974 Digital Unix 4, etc.)@: get confused if
12975 @var{string} looks like an operator:
12977 @example
12978 $ @kbd{test -n =}
12979 test: argument expected
12980 $ @kbd{test ! -n}
12981 test: argument expected
12982 @end example
12984 Similarly, Posix says that @samp{test "@var{string1}" = "@var{string2"}}
12985 and @samp{test "@var{string1}" != "@var{string2"}} work for any pairs of
12986 strings, but in practice this is not true for troublesome strings that
12987 look like operators or parentheses, or that begin with @samp{-}.
12989 It is best to protect such strings with a leading @samp{X}, e.g.,
12990 @samp{test "X@var{string}" != X} rather than @samp{test -n
12991 "@var{string}"} or @samp{test ! "@var{string}"}.
12993 It is common to find variations of the following idiom:
12995 @example
12996 test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" &&
12997   @var{action}
12998 @end example
13000 @noindent
13001 to take an action when a token matches a given pattern.  Such constructs
13002 should be avoided by using:
13004 @example
13005 case $ac_feature in
13006   *[!-a-zA-Z0-9_]*) @var{action};;
13007 esac
13008 @end example
13010 If the pattern is a complicated regular expression that cannot be
13011 expressed as a shell pattern, use something like this instead:
13013 @example
13014 expr "X$ac_feature" : 'X.*[^-a-zA-Z0-9_]' >/dev/null &&
13015   @var{action}
13016 @end example
13018 @samp{expr "X@var{foo}" : "X@var{bar}"} is more robust than @samp{echo
13019 "X@var{foo}" | grep "^X@var{bar}"}, because it avoids problems when
13020 @samp{@var{foo}} contains backslashes.
13023 @item @command{trap}
13024 @c -----------------
13025 @prindex @command{trap}
13026 It is safe to trap at least the signals 1, 2, 13, and 15.  You can also
13027 trap 0, i.e., have the @command{trap} run when the script ends (either via an
13028 explicit @command{exit}, or the end of the script).  The trap for 0 should be
13029 installed outside of a shell function, or @acronym{AIX} 5.3 @command{/bin/sh}
13030 will invoke the trap at the end of this function.
13032 Posix says that @samp{trap - 1 2 13 15} resets the traps for the
13033 specified signals to their default values, but many common shells (e.g.,
13034 Solaris @command{/bin/sh}) misinterpret this and attempt to execute a
13035 ``command'' named @command{-} when the specified conditions arise.
13036 There is no portable workaround, except for @samp{trap - 0}, for which
13037 @samp{trap '' 0} is a portable substitute.
13039 Although Posix is not absolutely clear on this point, it is widely
13040 admitted that when entering the trap @samp{$?} should be set to the exit
13041 status of the last command run before the trap.  The ambiguity can be
13042 summarized as: ``when the trap is launched by an @command{exit}, what is
13043 the @emph{last} command run: that before @command{exit}, or
13044 @command{exit} itself?''
13046 Bash considers @command{exit} to be the last command, while Zsh and
13047 Solaris @command{/bin/sh} consider that when the trap is run it is
13048 @emph{still} in the @command{exit}, hence it is the previous exit status
13049 that the trap receives:
13051 @example
13052 $ @kbd{cat trap.sh}
13053 trap 'echo $?' 0
13054 (exit 42); exit 0
13055 $ @kbd{zsh trap.sh}
13057 $ @kbd{bash trap.sh}
13059 @end example
13061 The portable solution is then simple: when you want to @samp{exit 42},
13062 run @samp{(exit 42); exit 42}, the first @command{exit} being used to
13063 set the exit status to 42 for Zsh, and the second to trigger the trap
13064 and pass 42 as exit status for Bash.
13066 The shell in Free@acronym{BSD} 4.0 has the following bug: @samp{$?} is
13067 reset to 0 by empty lines if the code is inside @command{trap}.
13069 @example
13070 $ @kbd{trap 'false}
13072 echo $?' 0
13073 $ @kbd{exit}
13075 @end example
13077 @noindent
13078 Fortunately, this bug only affects @command{trap}.
13080 @item @command{true}
13081 @c -----------------
13082 @prindex @command{true}
13083 @c Info cannot handle `:' in index entries.
13084 @c @prindex @command{:}
13085 Don't worry: as far as we know @command{true} is portable.
13086 Nevertheless, it's not always a builtin (e.g., Bash 1.x), and the
13087 portable shell community tends to prefer using @command{:}.  This has a
13088 funny side effect: when asked whether @command{false} is more portable
13089 than @command{true} Alexandre Oliva answered:
13091 @quotation
13092 In a sense, yes, because if it doesn't exist, the shell will produce an
13093 exit status of failure, which is correct for @command{false}, but not
13094 for @command{true}.
13095 @end quotation
13098 @item @command{unset}
13099 @c ------------------
13100 @prindex @command{unset}
13101 In some nonconforming shells (e.g., Bash 2.05a), @code{unset FOO} fails
13102 when @code{FOO} is not set.  Also, Bash 2.01 mishandles @code{unset
13103 MAIL} in some cases and dumps core.
13105 A few ancient shells lack @command{unset} entirely.  Nevertheless, because
13106 it is extremely useful to disable embarrassing variables such as
13107 @code{PS1}, you can test for its existence and use
13108 it @emph{provided} you give a neutralizing value when @command{unset} is
13109 not supported:
13111 @smallexample
13112 # "|| exit" suppresses any "Segmentation fault" message.
13113 if ( (MAIL=60; unset MAIL) || exit) >/dev/null 2>&1; then
13114   unset=unset
13115 else
13116   unset=false
13118 $unset PS1 || PS1='$ '
13119 @end smallexample
13121 @noindent
13122 @xref{Special Shell Variables}, for some neutralizing values.  Also, see
13123 @ref{Limitations of Builtins}, documentation of @command{export}, for
13124 the case of environment variables.
13125 @end table
13127 @node Limitations of Usual Tools
13128 @section Limitations of Usual Tools
13129 @cindex Limitations of usual tools
13131 The small set of tools you can expect to find on any machine can still
13132 include some limitations you should be aware of.
13134 @table @asis
13135 @item Awk
13136 @c ------
13137 @prindex Awk
13138 Don't leave white space before the opening parenthesis in a user function call.
13139 Posix does not allow this and @acronym{GNU} Awk rejects it:
13141 @example
13142 $ @kbd{gawk 'function die () @{ print "Aaaaarg!"  @}
13143         BEGIN @{ die () @}'}
13144 gawk: cmd. line:2:         BEGIN @{ die () @}
13145 gawk: cmd. line:2:                      ^ parse error
13146 $ @kbd{gawk 'function die () @{ print "Aaaaarg!"  @}
13147         BEGIN @{ die() @}'}
13148 Aaaaarg!
13149 @end example
13151 Posix says that if a program contains only @samp{BEGIN} actions, and
13152 contains no instances of @code{getline}, then the program merely
13153 executes the actions without reading input.  However, traditional Awk
13154 implementations (such as Solaris 10 @command{awk}) read and discard
13155 input in this case.  Portable scripts can redirect input from
13156 @file{/dev/null} to work around the problem.  For example:
13158 @example
13159 awk 'BEGIN @{print "hello world"@}' </dev/null
13160 @end example
13162 If you want your program to be deterministic, don't depend on @code{for}
13163 on arrays:
13165 @example
13166 $ @kbd{cat for.awk}
13167 END @{
13168   arr["foo"] = 1
13169   arr["bar"] = 1
13170   for (i in arr)
13171     print i
13173 $ @kbd{gawk -f for.awk </dev/null}
13176 $ @kbd{nawk -f for.awk </dev/null}
13179 @end example
13181 Some Awk implementations, such as @acronym{HP-UX} 11.0's native one, mishandle anchors:
13183 @example
13184 $ @kbd{echo xfoo | $AWK '/foo|^bar/ @{ print @}'}
13185 $ @kbd{echo bar | $AWK '/foo|^bar/ @{ print @}'}
13187 $ @kbd{echo xfoo | $AWK '/^bar|foo/ @{ print @}'}
13188 xfoo
13189 $ @kbd{echo bar | $AWK '/^bar|foo/ @{ print @}'}
13191 @end example
13193 @noindent
13194 Either do not depend on such patterns (i.e., use @samp{/^(.*foo|bar)/},
13195 or use a simple test to reject such implementations.
13197 @acronym{AIX} version 5.2 has an arbitrary limit of 399 on the
13198 length of regular expressions and literal strings in an Awk program.
13200 Traditional Awk implementations derived from Unix version 7, such as
13201 Solaris @command{/bin/awk}, have many limitations and do not
13202 conform to Posix.  Nowadays @code{AC_PROG_AWK} (@pxref{Particular
13203 Programs}) finds you an Awk that doesn't have these problems, but if
13204 for some reason you prefer not to use @code{AC_PROG_AWK} you may need to
13205 address them.
13207 Traditional Awk does not support multidimensional arrays or user-defined
13208 functions.
13210 Traditional Awk does not support the @option{-v} option.  You can use
13211 assignments after the program instead, e.g., @command{$AWK '@{print v
13212 $1@}' v=x}; however, don't forget that such assignments are not
13213 evaluated until they are encountered (e.g., after any @code{BEGIN}
13214 action).
13216 Traditional Awk does not support the keywords @code{delete} or @code{do}.
13218 Traditional Awk does not support the expressions
13219 @code{@var{a}?@var{b}:@var{c}}, @code{!@var{a}}, @code{@var{a}^@var{b}},
13220 or @code{@var{a}^=@var{b}}.
13222 Traditional Awk does not support the predefined @code{CONVFMT} variable.
13224 Traditional Awk supports only the predefined functions @code{exp},
13225 @code{int}, @code{length}, @code{log}, @code{split}, @code{sprintf},
13226 @code{sqrt}, and @code{substr}.
13228 Traditional Awk @code{getline} is not at all compatible with Posix;
13229 avoid it.
13231 Traditional Awk has @code{for (i in a) @dots{}} but no other uses of the
13232 @code{in} keyword.  For example, it lacks @code{if (i in a) @dots{}}.
13234 In code portable to both traditional and modern Awk, @code{FS} must be a
13235 string containing just one ordinary character, and similarly for the
13236 field-separator argument to @code{split}.
13238 Traditional Awk has a limit of 99
13239 fields in a record.  You may be able to circumvent this problem by using
13240 @code{split}.
13242 Traditional Awk has a limit of at most 99 bytes in a number formatted by
13243 @code{OFMT}; for example, @code{OFMT="%.300e"; print 0.1;} typically
13244 dumps core.
13246 The original version of Awk had a limit of at most 99 bytes per
13247 @code{split} field, 99 bytes per @code{substr} substring, and 99 bytes
13248 per run of non-special characters in a @code{printf} format, but these
13249 bugs have been fixed on all practical hosts that we know of.
13251 @item @command{basename}
13252 @c ---------------------
13253 @prindex @command{basename}
13254 Not all hosts have a working @command{basename}.
13255 You can use @command{expr} instead.
13257 @c AS_BASENAME is to be replaced by a better API.
13258 @ignore
13259 Not all hosts have a working @command{basename}, and you should instead
13260 use @code{AS_BASENAME} (@pxref{Programming in M4sh}), followed by
13261 @command{expr} if you need to strip a suffix.  For example:
13263 @example
13264 a=`basename "$aname"`       # This is not portable.
13265 a=`AS_BASENAME(["$aname"])` # This is more portable.
13267 # This is not portable.
13268 c=`basename "$cname" .c`
13270 # This is more portable.
13271 c=`AS_BASENAME(["$cname"])`
13272 case $c in
13273 ?*.c) c=`expr "X$c" : 'X\(.*\)\.c'`;;
13274 esac
13275 @end example
13276 @end ignore
13279 @item @command{cat}
13280 @c ----------------
13281 @prindex @command{cat}
13282 Don't rely on any option.
13285 @item @command{cc}
13286 @c ---------------
13287 @prindex @command{cc}
13288 The command @samp{cc -c foo.c} traditionally produces an object file
13289 named @file{foo.o}.  Most compilers allow @option{-c} to be combined
13290 with @option{-o} to specify a different object file name, but
13291 Posix does not require this combination and a few compilers
13292 lack support for it.  @xref{C Compiler}, for how @acronym{GNU} Make
13293 tests for this feature with @code{AC_PROG_CC_C_O}.
13295 When a compilation such as @samp{cc -o foo foo.c} fails, some compilers
13296 (such as @sc{cds} on Reliant Unix) leave a @file{foo.o}.
13298 @acronym{HP-UX} @command{cc} doesn't accept @file{.S} files to preprocess and
13299 assemble.  @samp{cc -c foo.S} appears to succeed, but in fact does
13300 nothing.
13302 The default executable, produced by @samp{cc foo.c}, can be
13304 @itemize
13305 @item @file{a.out} --- usual Posix convention.
13306 @item @file{b.out} --- i960 compilers (including @command{gcc}).
13307 @item @file{a.exe} --- @acronym{DJGPP} port of @command{gcc}.
13308 @item @file{a_out.exe} --- GNV @command{cc} wrapper for DEC C on OpenVMS.
13309 @item @file{foo.exe} --- various MS-DOS compilers.
13310 @end itemize
13312 The C compiler's traditional name is @command{cc}, but other names like
13313 @command{gcc} are common.  Posix 1003.1-2001 specifies the
13314 name @command{c99}, but older Posix editions specified
13315 @command{c89} and anyway these standard names are rarely used in
13316 practice.  Typically the C compiler is invoked from makefiles that use
13317 @samp{$(CC)}, so the value of the @samp{CC} make variable selects the
13318 compiler name.
13321 @item @command{chmod}
13322 @c ------------------
13323 @prindex @command{chmod}
13324 Avoid usages like @samp{chmod -w file}; use @samp{chmod a-w file}
13325 instead, for two reasons.  First, plain @option{-w} does not necessarily
13326 make the file unwritable, since it does not affect mode bits that
13327 correspond to bits in the file mode creation mask.  Second,
13328 Posix says that the @option{-w} might be interpreted as an
13329 implementation-specific option, not as a mode; Posix suggests
13330 using @samp{chmod -- -w file} to avoid this confusion, but unfortunately
13331 @samp{--} does not work on some older hosts.
13334 @item @command{cmp}
13335 @c ----------------
13336 @prindex @command{cmp}
13337 @command{cmp} performs a raw data comparison of two files, while
13338 @command{diff} compares two text files.  Therefore, if you might compare
13339 DOS files, even if only checking whether two files are different, use
13340 @command{diff} to avoid spurious differences due to differences of
13341 newline encoding.
13344 @item @command{cp}
13345 @c ---------------
13346 @prindex @command{cp}
13347 Avoid the @option{-r} option, since Posix 1003.1-2004 marks it as
13348 obsolescent and its behavior on special files is implementation-defined.
13349 Use @option{-R} instead.  On @acronym{GNU} hosts the two options
13350 are equivalent, but on Solaris hosts (for example) @command{cp -r}
13351 reads from pipes instead of replicating them.
13353 Some @command{cp} implementations (e.g., @acronym{BSD/OS} 4.2) do not allow
13354 trailing slashes at the end of nonexistent destination directories.  To
13355 avoid this problem, omit the trailing slashes.  For example, use
13356 @samp{cp -R source /tmp/newdir} rather than @samp{cp -R source
13357 /tmp/newdir/} if @file{/tmp/newdir} does not exist.
13359 @c This is thanks to Ian.
13360 The ancient SunOS 4 @command{cp} does not support @option{-f}, although
13361 its @command{mv} does.
13363 @cindex timestamp resolution
13364 Traditionally, file timestamps had 1-second resolution, and @samp{cp
13365 -p} copied the timestamps exactly.  However, many modern file systems
13366 have timestamps with 1-nanosecond resolution.  Unfortunately, @samp{cp
13367 -p} implementations truncate timestamps when copying files, so this
13368 can result in the destination file appearing to be older than the
13369 source.  The exact amount of truncation depends on the resolution of
13370 the system calls that @command{cp} uses; traditionally this was
13371 @code{utime}, which has 1-second resolution, but some newer
13372 @command{cp} implementations use @code{utimes}, which has
13373 1-microsecond resolution.  These newer implementations include @acronym{GNU}
13374 Core Utilities 5.0.91 or later, and Solaris 8 (sparc) patch 109933-02 or
13375 later.  Unfortunately as of January 2006 there is still no system
13376 call to set timestamps to the full nanosecond resolution.
13378 Bob Proulx notes that @samp{cp -p} always @emph{tries} to copy
13379 ownerships.  But whether it actually does copy ownerships or not is a
13380 system dependent policy decision implemented by the kernel.  If the
13381 kernel allows it then it happens.  If the kernel does not allow it then
13382 it does not happen.  It is not something @command{cp} itself has control
13383 over.
13385 In Unix System V any user can chown files to any other user, and System
13386 V also has a non-sticky @file{/tmp}.  That probably derives from the
13387 heritage of System V in a business environment without hostile users.
13388 @acronym{BSD} changed this
13389 to be a more secure model where only root can @command{chown} files and
13390 a sticky @file{/tmp} is used.  That undoubtedly derives from the heritage
13391 of @acronym{BSD} in a campus environment.
13393 @acronym{GNU}/Linux and Solaris by default follow @acronym{BSD}, but
13394 can be configured to allow a System V style @command{chown}.  On the
13395 other hand, @acronym{HP-UX} follows System V, but can
13396 be configured to use the modern security model and disallow
13397 @command{chown}.  Since it is an administrator-configurable parameter
13398 you can't use the name of the kernel as an indicator of the behavior.
13402 @item @command{date}
13403 @c -----------------
13404 @prindex @command{date}
13405 Some versions of @command{date} do not recognize special @samp{%} directives,
13406 and unfortunately, instead of complaining, they just pass them through,
13407 and exit with success:
13409 @example
13410 $ @kbd{uname -a}
13411 OSF1 medusa.sis.pasteur.fr V5.1 732 alpha
13412 $ @kbd{date "+%s"}
13414 @end example
13417 @item @command{diff}
13418 @c -----------------
13419 @prindex @command{diff}
13420 Option @option{-u} is nonportable.
13422 Some implementations, such as Tru64's, fail when comparing to
13423 @file{/dev/null}.  Use an empty file instead.
13426 @item @command{dirname}
13427 @c --------------------
13428 @prindex @command{dirname}
13429 Not all hosts have a working @command{dirname}, and you should instead
13430 use @code{AS_DIRNAME} (@pxref{Programming in M4sh}).  For example:
13432 @example
13433 dir=`dirname "$file"`       # This is not portable.
13434 dir=`AS_DIRNAME(["$file"])` # This is more portable.
13435 @end example
13438 @item @command{egrep}
13439 @c ------------------
13440 @prindex @command{egrep}
13441 Posix 1003.1-2001 no longer requires @command{egrep},
13442 but many hosts do not yet support the Posix
13443 replacement @code{grep -E}.  Also, some traditional implementations do
13444 not work on long input lines.  To work around these problems, invoke
13445 @code{AC_PROG_EGREP} and then use @code{$EGREP}.
13447 Portable extended regular expressions should use @samp{\} only to escape
13448 characters in the string @samp{$()*+.?[\^@{|}.  For example, @samp{\@}}
13449 is not portable, even though it typically matches @samp{@}}.
13451 The empty alternative is not portable.  Use @samp{?} instead.  For
13452 instance with Digital Unix v5.0:
13454 @example
13455 > printf "foo\n|foo\n" | $EGREP '^(|foo|bar)$'
13456 |foo
13457 > printf "bar\nbar|\n" | $EGREP '^(foo|bar|)$'
13458 bar|
13459 > printf "foo\nfoo|\n|bar\nbar\n" | $EGREP '^(foo||bar)$'
13461 |bar
13462 @end example
13464 @command{$EGREP} also suffers the limitations of @command{grep}.
13466 @item @command{expr}
13467 @c -----------------
13468 @prindex @command{expr}
13469 No @command{expr} keyword starts with @samp{X}, so use @samp{expr
13470 X"@var{word}" : 'X@var{regex}'} to keep @command{expr} from
13471 misinterpreting @var{word}.
13473 Don't use @code{length}, @code{substr}, @code{match} and @code{index}.
13475 @item @command{expr} (@samp{|})
13476 @prindex @command{expr} (@samp{|})
13477 You can use @samp{|}.  Although Posix does require that @samp{expr
13478 ''} return the empty string, it does not specify the result when you
13479 @samp{|} together the empty string (or zero) with the empty string.  For
13480 example:
13482 @example
13483 expr '' \| ''
13484 @end example
13486 Posix 1003.2-1992 returns the empty string
13487 for this case, but traditional Unix returns @samp{0} (Solaris is
13488 one such example).  In Posix 1003.1-2001, the specification was
13489 changed to match traditional Unix's behavior (which is
13490 bizarre, but it's too late to fix this).  Please note that the same
13491 problem does arise when the empty string results from a computation,
13492 as in:
13494 @example
13495 expr bar : foo \| foo : bar
13496 @end example
13498 @noindent
13499 Avoid this portability problem by avoiding the empty string.
13502 @item @command{expr} (@samp{:})
13503 @c ----------------------------
13504 @prindex @command{expr}
13505 Portable @command{expr} regular expressions should use @samp{\} to
13506 escape only characters in the string @samp{$()*.0123456789[\^n@{@}}.
13507 For example, alternation, @samp{\|}, is common but Posix does not
13508 require its support, so it should be avoided in portable scripts.
13509 Similarly, @samp{\+} and @samp{\?} should be avoided.
13511 Portable @command{expr} regular expressions should not begin with
13512 @samp{^}.  Patterns are automatically anchored so leading @samp{^} is
13513 not needed anyway.
13515 The Posix standard is ambiguous as to whether
13516 @samp{expr 'a' : '\(b\)'} outputs @samp{0} or the empty string.
13517 In practice, it outputs the empty string on most platforms, but portable
13518 scripts should not assume this.  For instance, the @acronym{QNX} 4.25 native
13519 @command{expr} returns @samp{0}.
13521 One might think that a way to get a uniform behavior would be to use
13522 the empty string as a default value:
13524 @example
13525 expr a : '\(b\)' \| ''
13526 @end example
13528 @noindent
13529 Unfortunately this behaves exactly as the original expression; see the
13530 @command{expr} (@samp{|}) entry for more information.
13532 Ancient @command{expr} implementations (e.g., SunOS 4 @command{expr} and
13533 Solaris 8 @command{/usr/ucb/expr}) have a silly length limit that causes
13534 @command{expr} to fail if the matched substring is longer than 120
13535 bytes.  In this case, you might want to fall back on @samp{echo|sed} if
13536 @command{expr} fails.  Nowadays this is of practical importance only for
13537 the rare installer who mistakenly puts @file{/usr/ucb} before
13538 @file{/usr/bin} in @env{PATH}.
13540 On Mac OS X 10.4, @command{expr} mishandles the pattern @samp{[^-]} in
13541 some cases.  For example, the command
13542 @example
13543 expr Xpowerpc-apple-darwin8.1.0 : 'X[^-]*-[^-]*-\(.*\)'
13544 @end example
13546 @noindent
13547 outputs @samp{apple-darwin8.1.0} rather than the correct @samp{darwin8.1.0}.
13548 This particular case can be worked around by substituting @samp{[^--]}
13549 for @samp{[^-]}.
13551 Don't leave, there is some more!
13553 The @acronym{QNX} 4.25 @command{expr}, in addition of preferring @samp{0} to
13554 the empty string, has a funny behavior in its exit status: it's always 1
13555 when parentheses are used!
13557 @example
13558 $ @kbd{val=`expr 'a' : 'a'`; echo "$?: $val"}
13559 0: 1
13560 $ @kbd{val=`expr 'a' : 'b'`; echo "$?: $val"}
13561 1: 0
13563 $ @kbd{val=`expr 'a' : '\(a\)'`; echo "?: $val"}
13564 1: a
13565 $ @kbd{val=`expr 'a' : '\(b\)'`; echo "?: $val"}
13566 1: 0
13567 @end example
13569 @noindent
13570 In practice this can be a big problem if you are ready to catch failures
13571 of @command{expr} programs with some other method (such as using
13572 @command{sed}), since you may get twice the result.  For instance
13574 @example
13575 $ @kbd{expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/'}
13576 @end example
13578 @noindent
13579 outputs @samp{a} on most hosts, but @samp{aa} on @acronym{QNX} 4.25.  A
13580 simple workaround consists of testing @command{expr} and using a variable
13581 set to @command{expr} or to @command{false} according to the result.
13583 Tru64 @command{expr} incorrectly treats the result as a number, if it
13584 can be interpreted that way:
13586 @example
13587 $ @kbd{expr 00001 : '.*\(...\)'}
13589 @end example
13592 @item @command{fgrep}
13593 @c ------------------
13594 @prindex @command{fgrep}
13595 Posix 1003.1-2001 no longer requires @command{fgrep},
13596 but many hosts do not yet support the Posix
13597 replacement @code{grep -F}.  Also, some traditional implementations do
13598 not work on long input lines.  To work around these problems, invoke
13599 @code{AC_PROG_FGREP} and then use @code{$FGREP}.
13602 @item @command{find}
13603 @c -----------------
13604 @prindex @command{find}
13605 The option @option{-maxdepth} seems to be @acronym{GNU} specific.
13606 Tru64 v5.1, Net@acronym{BSD} 1.5 and Solaris @command{find}
13607 commands do not understand it.
13609 The replacement of @samp{@{@}} is guaranteed only if the argument is
13610 exactly @emph{@{@}}, not if it's only a part of an argument.  For
13611 instance on DU, and @acronym{HP-UX} 10.20 and @acronym{HP-UX} 11:
13613 @example
13614 $ @kbd{touch foo}
13615 $ @kbd{find . -name foo -exec echo "@{@}-@{@}" \;}
13616 @{@}-@{@}
13617 @end example
13619 @noindent
13620 while @acronym{GNU} @command{find} reports @samp{./foo-./foo}.
13623 @item @command{grep}
13624 @c -----------------
13625 @prindex @command{grep}
13626 Portable scripts can rely on the @command{grep} options @option{-c},
13627 @option{-l}, @option{-n}, and @option{-v}, but should avoid other
13628 options.  For example, don't use @option{-w}, as Posix does not require
13629 it and Irix 6.5.16m's @command{grep} does not support it.  Also,
13630 portable scripts should not combine @option{-c} with @option{-l},
13631 as Posix does not allow this.
13633 Some of the options required by Posix are not portable in practice.
13634 Don't use @samp{grep -q} to suppress output, because many @command{grep}
13635 implementations (e.g., Solaris) do not support @option{-q}.
13636 Don't use @samp{grep -s} to suppress output either, because Posix
13637 says @option{-s} does not suppress output, only some error messages;
13638 also, the @option{-s} option of traditional @command{grep} behaved
13639 like @option{-q} does in most modern implementations.  Instead,
13640 redirect the standard output and standard error (in case the file
13641 doesn't exist) of @code{grep} to @file{/dev/null}.  Check the exit
13642 status of @code{grep} to determine whether it found a match.
13644 Some traditional @command{grep} implementations do not work on long
13645 input lines.  On AIX the default @code{grep} silently truncates long
13646 lines on the input before matching.
13648 Also, many implementations do not support multiple regexps
13649 with @option{-e}: they either reject @option{-e} entirely (e.g., Solaris)
13650 or honor only the last pattern (e.g., @acronym{IRIX} 6.5 and NeXT).  To
13651 work around these problems, invoke @code{AC_PROG_GREP} and then use
13652 @code{$GREP}.
13654 Another possible workaround for the multiple @option{-e} problem is to
13655 separate the patterns by newlines, for example:
13657 @example
13658 grep 'foo
13659 bar' in.txt
13660 @end example
13662 @noindent
13663 except that this fails with traditional @command{grep}
13664 implementations and with Open@acronym{BSD} 3.8 @command{grep}.
13666 Traditional @command{grep} implementations (e.g., Solaris) do not
13667 support the @option{-E} or @option{-F} options.  To work around these
13668 problems, invoke @code{AC_PROG_EGREP} and then use @code{$EGREP}, and
13669 similarly for @code{AC_PROG_FGREP} and @code{$FGREP}.  Even if you are
13670 willing to require support for Posix @command{grep}, your script should
13671 not use both @option{-E} and @option{-F}, since Posix does not allow
13672 this combination.
13674 Portable @command{grep} regular expressions should use @samp{\} only to
13675 escape characters in the string @samp{$()*.0123456789[\^@{@}}.  For example,
13676 alternation, @samp{\|}, is common but Posix does not require its
13677 support in basic regular expressions, so it should be avoided in
13678 portable scripts.  Solaris and HP-UX @command{grep} do not support it.
13679 Similarly, the following escape sequences should also be avoided:
13680 @samp{\<}, @samp{\>}, @samp{\+}, @samp{\?}, @samp{\`}, @samp{\'},
13681 @samp{\B}, @samp{\b}, @samp{\S}, @samp{\s}, @samp{\W}, and @samp{\w}.
13684 @item @command{join}
13685 @c -----------------
13686 @prindex @command{join}
13687 Solaris 8 @command{join} has bugs when the second operand is standard
13688 input, and when standard input is a pipe.  For example, the following
13689 shell script causes Solaris 8 @command{join} to loop forever:
13691 @example
13692 cat >file <<'EOF'
13693 1 x
13694 2 y
13696 cat file | join file -
13697 @end example
13699 Use @samp{join - file} instead.
13702 @item @command{ln}
13703 @c ---------------
13704 @prindex @command{ln}
13705 @cindex Symbolic links
13706 Don't rely on @command{ln} having a @option{-f} option.  Symbolic links
13707 are not available on old systems; use @samp{$(LN_S)} as a portable substitute.
13709 For versions of the @acronym{DJGPP} before 2.04,
13710 @command{ln} emulates symbolic links
13711 to executables by generating a stub that in turn calls the real
13712 program.  This feature also works with nonexistent files like in the
13713 Posix spec.  So @samp{ln -s file link} generates @file{link.exe},
13714 which attempts to call @file{file.exe} if run.  But this feature only
13715 works for executables, so @samp{cp -p} is used instead for these
13716 systems.  @acronym{DJGPP} versions 2.04 and later have full support
13717 for symbolic links.
13720 @item @command{ls}
13721 @c ---------------
13722 @prindex @command{ls}
13723 @cindex Listing directories
13724 The portable options are @option{-acdilrtu}.  Current practice is for
13725 @option{-l} to output both owner and group, even though ancient versions
13726 of @command{ls} omitted the group.
13728 On ancient hosts, @samp{ls foo} sent the diagnostic @samp{foo not found}
13729 to standard output if @file{foo} did not exist.  Hence a shell command
13730 like @samp{sources=`ls *.c 2>/dev/null`} did not always work, since it
13731 was equivalent to @samp{sources='*.c not found'} in the absence of
13732 @samp{.c} files.  This is no longer a practical problem, since current
13733 @command{ls} implementations send diagnostics to standard error.
13735 @item @command{mkdir}
13736 @c ------------------
13737 @prindex @command{mkdir}
13738 @cindex Making directories
13739 No @command{mkdir} option is portable to older systems.  Instead of
13740 @samp{mkdir -p @var{file-name}}, you should use
13741 @code{AS_MKDIR_P(@var{file-name})} (@pxref{Programming in M4sh})
13742 or @code{AC_PROG_MKDIR_P} (@pxref{Particular Programs}).
13744 Combining the @option{-m} and @option{-p} options, as in @samp{mkdir -m
13745 go-w -p @var{dir}}, often leads to trouble.  Free@acronym{BSD}
13746 @command{mkdir} incorrectly attempts to change the permissions of
13747 @var{dir} even if it already exists.  @acronym{HP-UX} 11.23 and
13748 @acronym{IRIX} 6.5 @command{mkdir} often assign the wrong permissions to
13749 any newly-created parents of @var{dir}.
13751 Posix does not clearly specify whether @samp{mkdir -p foo}
13752 should succeed when @file{foo} is a symbolic link to an already-existing
13753 directory.  The @acronym{GNU} Core Utilities 5.1.0 @command{mkdir}
13754 succeeds, but Solaris @command{mkdir} fails.
13756 Traditional @code{mkdir -p} implementations suffer from race conditions.
13757 For example, if you invoke @code{mkdir -p a/b} and @code{mkdir -p a/c}
13758 at the same time, both processes might detect that @file{a} is missing,
13759 one might create @file{a}, then the other might try to create @file{a}
13760 and fail with a @code{File exists} diagnostic.  The @acronym{GNU} Core
13761 Utilities (@samp{fileutils} version 4.1), Free@acronym{BSD} 5.0,
13762 Net@acronym{BSD} 2.0.2, and Open@acronym{BSD} 2.4 are known to be
13763 race-free when two processes invoke @code{mkdir -p} simultaneously, but
13764 earlier versions are vulnerable.  Solaris @command{mkdir} is still
13765 vulnerable as of Solaris 10, and other traditional Unix systems are
13766 probably vulnerable too.  This possible race is harmful in parallel
13767 builds when several Make rules call @code{mkdir -p} to
13768 construct directories.  You may use
13769 @code{install-sh -d} as a safe replacement, provided this script is
13770 recent enough; the copy shipped with Autoconf 2.60 and Automake 1.10 is
13771 OK, but copies from older versions are vulnerable.
13774 @item @command{mktemp}
13775 @c -------------------
13776 @prindex @command{mktemp}
13777 @cindex Creating temporary files
13778 Shell scripts can use temporary files safely with @command{mktemp}, but
13779 it does not exist on all systems.  A portable way to create a safe
13780 temporary file name is to create a temporary directory with mode 700 and
13781 use a file inside this directory.  Both methods prevent attackers from
13782 gaining control, though @command{mktemp} is far less likely to fail
13783 gratuitously under attack.
13785 Here is sample code to create a new temporary directory safely:
13787 @example
13788 # Create a temporary directory $tmp in $TMPDIR (default /tmp).
13789 # Use mktemp if possible; otherwise fall back on mkdir,
13790 # with $RANDOM to make collisions less likely.
13791 : $@{TMPDIR=/tmp@}
13793   tmp=`
13794     (umask 077 && mktemp -d "$TMPDIR/fooXXXXXX") 2>/dev/null
13795   ` &&
13796   test -n "$tmp" && test -d "$tmp"
13797 @} || @{
13798   tmp=$TMPDIR/foo$$-$RANDOM
13799   (umask 077 && mkdir "$tmp")
13800 @} || exit $?
13801 @end example
13804 @item @command{mv}
13805 @c ---------------
13806 @prindex @command{mv}
13807 @cindex Moving open files
13808 The only portable options are @option{-f} and @option{-i}.
13810 Moving individual files between file systems is portable (it was in Unix
13811 version 6),
13812 but it is not always atomic: when doing @samp{mv new existing}, there's
13813 a critical section where neither the old nor the new version of
13814 @file{existing} actually exists.
13816 On some systems moving files from @file{/tmp} can sometimes cause
13817 undesirable (but perfectly valid) warnings, even if you created these
13818 files.  This is because @file{/tmp} belongs to a group that ordinary
13819 users are not members of, and files created in @file{/tmp} inherit
13820 the group of @file{/tmp}.  When the file is copied, @command{mv} issues
13821 a diagnostic without failing:
13823 @smallexample
13824 $ @kbd{touch /tmp/foo}
13825 $ @kbd{mv /tmp/foo .}
13826 @error{}mv: ./foo: set owner/group (was: 100/0): Operation not permitted
13827 $ @kbd{echo $?}
13829 $ @kbd{ls foo}
13831 @end smallexample
13833 @noindent
13834 This annoying behavior conforms to Posix, unfortunately.
13836 Moving directories across mount points is not portable, use @command{cp}
13837 and @command{rm}.
13839 @acronym{DOS} variants cannot rename or remove open files, and do not
13840 support commands like @samp{mv foo bar >foo}, even though this is
13841 perfectly portable among Posix hosts.
13844 @item @command{od}
13845 @c ---------------
13846 @prindex @command{od}
13848 In Mac OS X 10.3, @command{od} does not support the
13849 standard Posix options @option{-A}, @option{-j}, @option{-N}, or
13850 @option{-t}, or the @acronym{XSI} option @option{-s}.  The only
13851 supported Posix option is @option{-v}, and the only supported
13852 @acronym{XSI} options are those in @option{-bcdox}.  The @acronym{BSD}
13853 @command{hexdump} program can be used instead.
13855 This problem no longer exists in Mac OS X 10.4.3.
13858 @item @command{rm}
13859 @c ---------------
13860 @prindex @command{rm}
13861 The @option{-f} and @option{-r} options are portable.
13863 It is not portable to invoke @command{rm} without operands.  For
13864 example, on many systems @samp{rm -f -r} (with no other arguments)
13865 silently succeeds without doing anything, but it fails with a diagnostic
13866 on Net@acronym{BSD} 2.0.2.
13868 A file might not be removed even if its parent directory is writable
13869 and searchable.  Many Posix hosts cannot remove a mount point, a named
13870 stream, a working directory, or a last link to a file that is being
13871 executed.
13873 @acronym{DOS} variants cannot rename or remove open files, and do not
13874 support commands like @samp{rm foo >foo}, even though this is
13875 perfectly portable among Posix hosts.
13878 @item @command{sed}
13879 @c ----------------
13880 @prindex @command{sed}
13881 Patterns should not include the separator (unless escaped), even as part
13882 of a character class.  In conformance with Posix, the Cray
13883 @command{sed} rejects @samp{s/[^/]*$//}: use @samp{s,[^/]*$,,}.
13885 Avoid empty patterns within parentheses (i.e., @samp{\(\)}).  Posix does
13886 not require support for empty patterns, and Unicos 9 @command{sed} rejects
13887 them.
13889 Unicos 9 @command{sed} loops endlessly on patterns like @samp{.*\n.*}.
13891 Sed scripts should not use branch labels longer than 7 characters and
13892 should not contain comments.  @acronym{HP-UX} sed has a limit of 99 commands
13893 (not counting @samp{:} commands) and
13894 48 labels, which can not be circumvented by using more than one script
13895 file.  It can execute up to 19 reads with the @samp{r} command per cycle.
13896 Solaris @command{/usr/ucb/sed} rejects usages that exceed an limit of
13897 about 6000 bytes for the internal representation of commands.
13899 Avoid redundant @samp{;}, as some @command{sed} implementations, such as
13900 Net@acronym{BSD} 1.4.2's, incorrectly try to interpret the second
13901 @samp{;} as a command:
13903 @example
13904 $ @kbd{echo a | sed 's/x/x/;;s/x/x/'}
13905 sed: 1: "s/x/x/;;s/x/x/": invalid command code ;
13906 @end example
13908 Input should not have unreasonably long lines, since some @command{sed}
13909 implementations have an input buffer limited to 4000 bytes.
13911 Portable @command{sed} regular expressions should use @samp{\} only to escape
13912 characters in the string @samp{$()*.0123456789[\^n@{@}}.  For example,
13913 alternation, @samp{\|}, is common but Posix does not require its
13914 support, so it should be avoided in portable scripts.  Solaris
13915 @command{sed} does not support alternation; e.g., @samp{sed '/a\|b/d'}
13916 deletes only lines that contain the literal string @samp{a|b}.
13917 Similarly, @samp{\+} and @samp{\?} should be avoided.
13919 Anchors (@samp{^} and @samp{$}) inside groups are not portable.
13921 Nested parentheses in patterns (e.g., @samp{\(\(a*\)b*)\)}) are
13922 quite portable to current hosts, but was not supported by some ancient
13923 @command{sed} implementations like SVR3.
13925 Some @command{sed} implementations, e.g., Solaris,
13926 restrict the special role of the asterisk to one-character regular expressions.
13927 This may lead to unexpected behavior:
13929 @example
13930 $ @kbd{echo '1*23*4' | /usr/bin/sed 's/\(.\)*/x/g'}
13931 x2x4
13932 $ @kbd{echo '1*23*4' | /usr/xpg4/bin/sed 's/\(.\)*/x/g'}
13934 @end example
13936 The @option{-e} option is portable, so long as its argument
13937 does not begin with @samp{a}, @samp{c}, or @samp{i}
13938 (as this runs afoul of a Tru64 5.1 bug).
13939 Some people prefer to use @samp{-e}:
13941 @example
13942 sed -e '@var{command-1}' \
13943     -e '@var{command-2}'
13944 @end example
13946 @noindent
13947 as opposed to the equivalent:
13949 @example
13950 sed '
13951   @var{command-1}
13952   @var{command-2}
13954 @end example
13956 @noindent
13957 The following usage is sometimes equivalent:
13959 @example
13960 sed '@var{command-1};@var{command-2}'
13961 @end example
13963 but Posix says that this use of a semicolon has undefined effect if
13964 @var{command-1}'s verb is @samp{@{}, @samp{a}, @samp{b}, @samp{c},
13965 @samp{i}, @samp{r}, @samp{t}, @samp{w}, @samp{:}, or @samp{#}, so you
13966 should use semicolon only with simple scripts that do not use these
13967 verbs.
13969 Commands inside @{ @} brackets are further restricted.  Posix says that
13970 they cannot be preceded by addresses, @samp{!}, or @samp{;}, and that
13971 each command must be followed immediately by a newline, without any
13972 intervening blanks or semicolons.  The closing bracket must be alone on
13973 a line, other than white space preceding or following it.
13975 Contrary to yet another urban legend, you may portably use @samp{&} in
13976 the replacement part of the @code{s} command to mean ``what was
13977 matched''.  All descendants of Unix version 7 @command{sed}
13978 (at least; we
13979 don't have first hand experience with older @command{sed} implementations) have
13980 supported it.
13982 Posix requires that you must not have any white space between
13983 @samp{!} and the following command.  It is OK to have blanks between
13984 the address and the @samp{!}.  For instance, on Solaris:
13986 @example
13987 $ @kbd{echo "foo" | sed -n '/bar/ ! p'}
13988 @error{}Unrecognized command: /bar/ ! p
13989 $ @kbd{echo "foo" | sed -n '/bar/! p'}
13990 @error{}Unrecognized command: /bar/! p
13991 $ @kbd{echo "foo" | sed -n '/bar/ !p'}
13993 @end example
13995 Posix also says that you should not combine @samp{!} and @samp{;}.  If
13996 you use @samp{!}, it is best to put it on a command that is delimited by
13997 newlines rather than @samp{;}.
13999 Also note that Posix requires that the @samp{b}, @samp{t}, @samp{r}, and
14000 @samp{w} commands be followed by exactly one space before their argument.
14001 On the other hand, no white space is allowed between @samp{:} and the
14002 subsequent label name.
14004 If a sed script is specified on the command line and ends in an
14005 @samp{a}, @samp{c}, or @samp{i} command, the last line of inserted text
14006 should be followed by a newline.  Otherwise some @command{sed}
14007 implementations (e.g., Open@acronym{BSD} 3.9) do not append a newline to the
14008 inserted text.
14010 Many @command{sed} implementations (e.g., MacOS X 10.4,
14011 Open@acronym{BSD} 3.9, Solaris 10
14012 @command{/usr/ucb/sed}) strip leading white space from the text of
14013 @samp{a}, @samp{c}, and @samp{i} commands.  Prepend a backslash to
14014 work around this incompatibility with Posix:
14016 @example
14017 $ @kbd{echo flushleft | sed 'a\}
14018 > @kbd{   indented}
14019 > @kbd{'}
14020 flushleft
14021 indented
14022 $ @kbd{echo foo | sed 'a\}
14023 > @kbd{\   indented}
14024 > @kbd{'}
14025 flushleft
14026    indented
14027 @end example
14030 @item @command{sed} (@samp{t})
14031 @c ---------------------------
14032 @prindex @command{sed} (@samp{t})
14033 Some old systems have @command{sed} that ``forget'' to reset their
14034 @samp{t} flag when starting a new cycle.  For instance on @acronym{MIPS
14035 RISC/OS}, and on @sc{irix} 5.3, if you run the following @command{sed}
14036 script (the line numbers are not actual part of the texts):
14038 @example
14039 s/keep me/kept/g  # a
14040 t end             # b
14041 s/.*/deleted/g    # c
14042 :end              # d
14043 @end example
14045 @noindent
14048 @example
14049 delete me         # 1
14050 delete me         # 2
14051 keep me           # 3
14052 delete me         # 4
14053 @end example
14055 @noindent
14056 you get
14058 @example
14059 deleted
14060 delete me
14061 kept
14062 deleted
14063 @end example
14065 @noindent
14066 instead of
14068 @example
14069 deleted
14070 deleted
14071 kept
14072 deleted
14073 @end example
14075 Why?  When processing line 1, (c) matches, therefore sets the @samp{t}
14076 flag, and the output is produced.  When processing
14077 line 2, the @samp{t} flag is still set (this is the bug).  Command (a)
14078 fails to match, but @command{sed} is not supposed to clear the @samp{t}
14079 flag when a substitution fails.  Command (b) sees that the flag is set,
14080 therefore it clears it, and jumps to (d), hence you get @samp{delete me}
14081 instead of @samp{deleted}.  When processing line (3), @samp{t} is clear,
14082 (a) matches, so the flag is set, hence (b) clears the flags and jumps.
14083 Finally, since the flag is clear, line 4 is processed properly.
14085 There are two things one should remember about @samp{t} in @command{sed}.
14086 Firstly, always remember that @samp{t} jumps if @emph{some} substitution
14087 succeeded, not only the immediately preceding substitution.  Therefore,
14088 always use a fake @samp{t clear} followed by a @samp{:clear} on the next
14089 line, to reset the @samp{t} flag where needed.
14091 Secondly, you cannot rely on @command{sed} to clear the flag at each new
14092 cycle.
14094 One portable implementation of the script above is:
14096 @example
14097 t clear
14098 :clear
14099 s/keep me/kept/g
14100 t end
14101 s/.*/deleted/g
14102 :end
14103 @end example
14105 @item @command{touch}
14106 @c ------------------
14107 @prindex @command{touch}
14108 @cindex timestamp resolution
14109 If you specify the desired timestamp (e.g., with the @option{-r}
14110 option), @command{touch} typically uses the @code{utime} or
14111 @code{utimes} system call, which can result in the same kind of
14112 timestamp truncation problems that @samp{cp -p} has.
14114 On ancient @acronym{BSD} systems, @command{touch} or any command that
14115 results in an empty file does not update the timestamps, so use a
14116 command like @command{echo} as a workaround.
14117 Also,
14118 @acronym{GNU} @command{touch} 3.16r (and presumably all before that)
14119 fails to work on SunOS 4.1.3 when the empty file is on an
14120 @acronym{NFS}-mounted 4.2 volume.
14121 However, these problems are no longer of practical concern.
14123 @end table
14126 @node Portable Make
14127 @chapter Portable Make Programming
14128 @prindex @command{make}
14129 @cindex Limitations of @command{make}
14131 Writing portable makefiles is an art.  Since a makefile's commands are
14132 executed by the shell, you must consider the shell portability issues
14133 already mentioned.  However, other issues are specific to @command{make}
14134 itself.
14136 @menu
14137 * $< in Ordinary Make Rules::   $< in ordinary rules
14138 * Failure in Make Rules::       Failing portably in rules
14139 * Special Chars in Names::      Special Characters in Macro Names
14140 * Backslash-Newline-Newline::   Empty last lines in macro definitions
14141 * Backslash-Newline Comments::  Spanning comments across line boundaries
14142 * Long Lines in Makefiles::     Line length limitations
14143 * Macros and Submakes::         @code{make macro=value} and submakes
14144 * The Make Macro MAKEFLAGS::    @code{$(MAKEFLAGS)} portability issues
14145 * The Make Macro SHELL::        @code{$(SHELL)} portability issues
14146 * Comments in Make Rules::      Other problems with Make comments
14147 * obj/ and Make::               Don't name a subdirectory @file{obj}
14148 * make -k Status::              Exit status of @samp{make -k}
14149 * VPATH and Make::              @code{VPATH} woes
14150 * Single Suffix Rules::         Single suffix rules and separated dependencies
14151 * Timestamps and Make::         Subsecond timestamp resolution
14152 @end menu
14154 @node $< in Ordinary Make Rules
14155 @section @code{$<} in Ordinary Make Rules
14157 Posix says that the @samp{$<} construct in makefiles can be
14158 used only in inference rules and in the @samp{.DEFAULT} rule; its
14159 meaning in ordinary rules is unspecified.  Solaris @command{make}
14160 for instance replaces it with the empty string.  Open@acronym{BSD} (3.0 and
14161 later) @command{make} diagnoses these uses and errors out.
14163 @node Failure in Make Rules
14164 @section Failure in Make Rules
14166 Since 1992 Posix has required that @command{make} must invoke
14167 each command with the equivalent of a @samp{sh -c} subshell.  However,
14168 many @command{make} implementations, including @acronym{BSD} make through 2004,
14169 use @samp{sh -e -c} instead, and the @option{-e} option causes the
14170 subshell to exit immediately if a subsidiary simple-command fails.  For
14171 example, the command @samp{touch T; rm -f U} always attempts to
14172 remove @file{U} with Posix make, but incompatible
14173 @command{make} implementations skip the @command{rm} if the
14174 @command{touch} fails.  One way to work around this is to reword the
14175 affected simple-commands so that they always succeed, e.g., @samp{touch
14176 T || :; rm -f U}.
14177 However, even this approach can run into common bugs in @acronym{BSD}
14178 implementations of the @option{-e} option of @command{sh} and
14179 @command{set} (@pxref{Limitations of Builtins}), so if you are worried
14180 about porting to buggy @acronym{BSD} shells it may be simpler to migrate
14181 complicated @command{make} actions into separate scripts.
14183 @node Special Chars in Names
14184 @section Special Characters in Make Macro Names
14186 Posix limits macro names to nonempty strings containing only
14187 @acronym{ASCII} letters and digits, @samp{.}, and @samp{_}.  Many
14188 @command{make} implementations allow a wider variety of characters, but
14189 portable makefiles should avoid them.  It is portable to start a name
14190 with a special character, e.g., @samp{$(.FOO)}.
14192 Some ancient @command{make} implementations don't support leading
14193 underscores in macro names.  An example is @acronym{NEWS-OS} 4.2R.
14195 @example
14196 $ @kbd{cat Makefile}
14197 _am_include = #
14198 _am_quote =
14199 all:; @@echo this is test
14200 $ @kbd{make}
14201 Make: Must be a separator on rules line 2.  Stop.
14202 $ @kbd{cat Makefile2}
14203 am_include = #
14204 am_quote =
14205 all:; @@echo this is test
14206 $ @kbd{make -f Makefile2}
14207 this is test
14208 @end example
14210 @noindent
14211 However, this problem is no longer of practical concern.
14213 @node Backslash-Newline-Newline
14214 @section Backslash-Newline-Newline in Make Macro Values
14216 @c  This has been seen on ia64 hpux 11.20, and on one hppa hpux 10.20,
14217 @c  but another hppa hpux 10.20 didn't have it.  Bob Proulx
14218 @c  <bob@proulx.com> thinks it was in hpux 8.0 too.
14219 On some versions of @acronym{HP-UX}, @command{make} reads multiple newlines
14220 following a backslash, continuing to the next non-empty line.  For
14221 example,
14223 @example
14224 FOO = one \
14226 BAR = two
14228 test:
14229         : FOO is "$(FOO)"
14230         : BAR is "$(BAR)"
14231 @end example
14233 @noindent
14234 shows @code{FOO} equal to @code{one BAR = two}.  Other implementations
14235 sensibly let a backslash continue only to the immediately following
14236 line.
14238 @node Backslash-Newline Comments
14239 @section Backslash-Newline in Make Comments
14241 According to Posix, Make comments start with @code{#}
14242 and continue until an unescaped newline is reached.
14244 @example
14245 $ @kbd{cat Makefile}
14246 # A = foo \
14247       bar \
14248       baz
14250 all:
14251         @@echo ok
14252 $ @kbd{make}   # GNU make
14254 @end example
14256 @noindent
14257 However this is not always the case.  Some implementations
14258 discard everything from @code{#} through the end of the line, ignoring any
14259 trailing backslash.
14261 @example
14262 $ @kbd{pmake}  # BSD make
14263 "Makefile", line 3: Need an operator
14264 Fatal errors encountered -- cannot continue
14265 @end example
14267 @noindent
14268 Therefore, if you want to comment out a multi-line definition, prefix each
14269 line with @code{#}, not only the first.
14271 @example
14272 # A = foo \
14273 #     bar \
14274 #     baz
14275 @end example
14277 @node Long Lines in Makefiles
14278 @section Long Lines in Makefiles
14280 Tru64 5.1's @command{make} has been reported to crash when given a
14281 makefile with lines longer than around 20 kB.  Earlier versions are
14282 reported to exit with @code{Line too long} diagnostics.
14284 @node Macros and Submakes
14285 @section @code{make macro=value} and Submakes
14287 A command-line variable definition such as @code{foo=bar} overrides any
14288 definition of @code{foo} in a makefile.  Some @command{make}
14289 implementations (such as @acronym{GNU} @command{make}) propagate this
14290 override to subsidiary invocations of @command{make}.  Some other
14291 implementations do not pass the substitution along to submakes.
14293 @example
14294 $ @kbd{cat Makefile}
14295 foo = foo
14296 one:
14297         @@echo $(foo)
14298         $(MAKE) two
14299 two:
14300         @@echo $(foo)
14301 $ @kbd{make foo=bar}            # GNU make 3.79.1
14303 make two
14304 make[1]: Entering directory `/home/adl'
14306 make[1]: Leaving directory `/home/adl'
14307 $ @kbd{pmake foo=bar}           # BSD make
14309 pmake two
14311 @end example
14313 You have a few possibilities if you do want the @code{foo=bar} override
14314 to propagate to submakes.  One is to use the @option{-e}
14315 option, which causes all environment variables to have precedence over
14316 the makefile macro definitions, and declare foo as an environment
14317 variable:
14319 @example
14320 $ @kbd{env foo=bar make -e}
14321 @end example
14323 The @option{-e} option is propagated to submakes automatically,
14324 and since the environment is inherited between @command{make}
14325 invocations, the @code{foo} macro is overridden in
14326 submakes as expected.
14328 This syntax (@code{foo=bar make -e}) is portable only when used
14329 outside of a makefile, for instance from a script or from the
14330 command line.  When run inside a @command{make} rule, @acronym{GNU}
14331 @command{make} 3.80 and prior versions forget to propagate the
14332 @option{-e} option to submakes.
14334 Moreover, using @option{-e} could have unexpected side effects if your
14335 environment contains some other macros usually defined by the
14336 makefile.  (See also the note about @code{make -e} and @code{SHELL}
14337 below.)
14339 Another way to propagate overrides to submakes is to do it
14340 manually, from your makefile:
14342 @example
14343 foo = foo
14344 one:
14345         @@echo $(foo)
14346         $(MAKE) foo=$(foo) two
14347 two:
14348         @@echo $(foo)
14349 @end example
14351 You need to foresee all macros that a user might want to override if
14352 you do that.
14354 @node The Make Macro MAKEFLAGS
14355 @section The Make Macro MAKEFLAGS
14356 @cindex @code{MAKEFLAGS} and @command{make}
14357 @cindex @command{make} and @code{MAKEFLAGS}
14359 Posix requires @command{make} to use @code{MAKEFLAGS} to affect the
14360 current and recursive invocations of make, but allows implementations
14361 several formats for the variable.  It is tricky to parse
14362 @code{$MAKEFLAGS} to determine whether @option{-s} for silent execution
14363 or @option{-k} for continued execution are in effect.  For example, you
14364 cannot assume that the first space-separated word in @code{$MAKEFLAGS}
14365 contains single-letter options, since in the Cygwin version of
14366 @acronym{GNU} @command{make} it is either @option{--unix} or
14367 @option{--win32} with the second word containing single-letter options.
14369 @example
14370 $ @kbd{cat Makefile}
14371 all:
14372         @@echo MAKEFLAGS = $(MAKEFLAGS)
14373 $ @kbd{make}
14374 MAKEFLAGS = --unix
14375 $ @kbd{make -k}
14376 MAKEFLAGS = --unix -k
14377 @end example
14379 @node The Make Macro SHELL
14380 @section The Make Macro @code{SHELL}
14381 @cindex @code{SHELL} and @command{make}
14382 @cindex @command{make} and @code{SHELL}
14384 Posix-compliant @command{make} internally uses the @code{$(SHELL)}
14385 macro to spawn shell processes and execute Make rules.  This
14386 is a builtin macro supplied by @command{make}, but it can be modified
14387 by a makefile or by a command-line argument.
14389 Not all @command{make} implementations define this @code{SHELL} macro.
14390 Tru64
14391 @command{make} is an example; this implementation always uses
14392 @code{/bin/sh}.  So it's a good idea to always define @code{SHELL} in
14393 your makefiles.  If you use Autoconf, do
14395 @example
14396 SHELL = @@SHELL@@
14397 @end example
14399 Do not force @code{SHELL = /bin/sh} because that is not correct
14400 everywhere.  For instance @acronym{DJGPP} lacks @code{/bin/sh}, and when
14401 its @acronym{GNU} @code{make} port sees such a setting it enters a special
14402 emulation mode where features like pipes and redirections are emulated
14403 on top of DOS's @command{command.com}.  Unfortunately this emulation is
14404 incomplete; for instance it does not handle command substitutions.
14405 On @acronym{DJGPP} @code{SHELL} should point to Bash.
14407 Posix-compliant @command{make} should never acquire the value of
14408 $(SHELL) from the environment, even when @code{make -e} is used
14409 (otherwise, think about what would happen to your rules if
14410 @code{SHELL=/bin/tcsh}).
14412 However not all @command{make} implementations have this exception.
14413 For instance it's not surprising that Tru64 @command{make} doesn't
14414 protect @code{SHELL}, since it doesn't use it.
14416 @example
14417 $ @kbd{cat Makefile}
14418 SHELL = /bin/sh
14419 FOO = foo
14420 all:
14421         @@echo $(SHELL)
14422         @@echo $(FOO)
14423 $ @kbd{env SHELL=/bin/tcsh FOO=bar make -e}   # Tru64 Make
14424 /bin/tcsh
14426 $ @kbd{env SHELL=/bin/tcsh FOO=bar gmake -e}  # GNU make
14427 /bin/sh
14429 @end example
14431 @node Comments in Make Rules
14432 @section Comments in Make Rules
14433 @cindex Comments in @file{Makefile} rules
14434 @cindex @file{Makefile} rules and comments
14436 Never put comments in a rule.
14438 Some @command{make} treat anything starting with a tab as a command for
14439 the current rule, even if the tab is immediately followed by a @code{#}.
14440 The @command{make} from Tru64 Unix V5.1 is one of them.  The following
14441 makefile runs @code{# foo} through the shell.
14443 @example
14444 all:
14445         # foo
14446 @end example
14448 @node obj/ and Make
14449 @section The @file{obj/} Subdirectory and Make
14450 @cindex @file{obj/}, subdirectory
14451 @cindex @acronym{BSD} @command{make} and @file{obj/}
14453 Never name one of your subdirectories @file{obj/} if you don't like
14454 surprises.
14456 If an @file{obj/} directory exists, @acronym{BSD} @command{make} enters it
14457 before reading the makefile.  Hence the makefile in the
14458 current directory is not read.
14460 @example
14461 $ @kbd{cat Makefile}
14462 all:
14463         echo Hello
14464 $ @kbd{cat obj/Makefile}
14465 all:
14466         echo World
14467 $ @kbd{make}      # GNU make
14468 echo Hello
14469 Hello
14470 $ @kbd{pmake}     # BSD make
14471 echo World
14472 World
14473 @end example
14475 @node make -k Status
14476 @section Exit Status of @code{make -k}
14477 @cindex @code{make -k}
14479 Do not rely on the exit status of @code{make -k}.  Some implementations
14480 reflect whether they encountered an error in their exit status; other
14481 implementations always succeed.
14483 @example
14484 $ @kbd{cat Makefile}
14485 all:
14486         false
14487 $ @kbd{make -k; echo exit status: $?}    # GNU make
14488 false
14489 make: *** [all] Error 1
14490 exit status: 2
14491 $ @kbd{pmake -k; echo exit status: $?}   # BSD make
14492 false
14493 *** Error code 1 (continuing)
14494 exit status: 0
14495 @end example
14497 @node VPATH and Make
14498 @section @code{VPATH} and Make
14499 @cindex @code{VPATH}
14501 Posix does not specify the semantics of @code{VPATH}.  Typically,
14502 @command{make} supports @code{VPATH}, but its implementation is not
14503 consistent.
14505 Autoconf and Automake support makefiles whose usages of @code{VPATH} are
14506 portable to recent-enough popular implementations of @command{make}, but
14507 to keep the resulting makefiles portable, a package's makefile
14508 prototypes must take the following issues into account.  These issues
14509 are complicated and are often poorly understood, and installers who use
14510 @code{VPATH} should expect to find many bugs in this area.  If you use
14511 @code{VPATH}, the simplest way to avoid these portability bugs is to
14512 stick with @acronym{GNU} @command{make}, since it is the most
14513 commonly-used @command{make} among Autoconf users.
14515 Here are some known issues with some @code{VPATH}
14516 implementations.
14518 @menu
14519 * VPATH and Double-colon::      Problems with @samp{::} on ancient hosts
14520 * $< in Explicit Rules::        @code{$<} does not work in ordinary rules
14521 * Automatic Rule Rewriting::    @code{VPATH} goes wild on Solaris
14522 * Tru64 Directory Magic::       @command{mkdir} goes wild on Tru64
14523 * Make Target Lookup::          More details about @code{VPATH} lookup
14524 @end menu
14526 @node VPATH and Double-colon
14527 @subsection @code{VPATH} and Double-colon Rules
14528 @cindex @code{VPATH} and double-colon rules
14529 @cindex double-colon rules and @code{VPATH}
14531 With ancient versions of Sun @command{make},
14532 any assignment to @code{VPATH} causes @command{make} to execute only
14533 the first set of double-colon rules.
14534 However, this problem is no longer of practical concern.
14536 @node $< in Explicit Rules
14537 @subsection @code{$<} Not Supported in Explicit Rules
14538 @cindex explicit rules, @code{$<}, and @code{VPATH}
14539 @cindex @code{$<}, explicit rules, and @code{VPATH}
14540 @cindex @code{VPATH}, explicit rules, and @code{$<}
14542 Using @code{$<} in explicit rules is not portable.
14543 The prerequisite file must be named explicitly in the rule.  If you want
14544 to find the prerequisite via a @code{VPATH} search, you have to code the
14545 whole thing manually.  @xref{Build Directories}.
14547 @node Automatic Rule Rewriting
14548 @subsection Automatic Rule Rewriting
14549 @cindex @code{VPATH} and automatic rule rewriting
14550 @cindex automatic rule rewriting and @code{VPATH}
14552 Some @command{make} implementations, such as Solaris and Tru64,
14553 search for prerequisites in @code{VPATH} and
14554 then rewrite each occurrence as a plain word in the rule.
14555 For instance:
14557 @example
14558 # This isn't portable to GNU make.
14559 VPATH = ../pkg/src
14560 f.c: if.c
14561         cp if.c f.c
14562 @end example
14564 @noindent
14565 executes @code{cp ../pkg/src/if.c f.c} if @file{if.c} is
14566 found in @file{../pkg/src}.
14568 However, this rule leads to real problems in practice.  For example, if
14569 the source directory contains an ordinary file named @file{test} that is
14570 used in a dependency, Solaris @command{make} rewrites commands like
14571 @samp{if test -r foo; @dots{}} to @samp{if ../pkg/src/test -r foo;
14572 @dots{}}, which is typically undesirable.  To avoid this problem,
14573 portable makefiles should never mention a source file whose name is that
14574 of a shell keyword like @file{until} or a shell command like
14575 @command{cat} or @command{gcc} or @command{test}.
14577 Because of these problems @acronym{GNU} @command{make} and many other
14578 @command{make} implementations do not rewrite commands, so portable
14579 makefiles should
14580 search @code{VPATH} manually.  It is tempting to write this:
14582 @smallexample
14583 # This isn't portable to Solaris make.
14584 VPATH = ../pkg/src
14585 f.c: if.c
14586         cp `test -f if.c || echo $(VPATH)/`if.c f.c
14587 @end smallexample
14589 @noindent
14590 However, the ``prerequisite rewriting'' still applies here.  So if
14591 @file{if.c} is in @file{../pkg/src}, Solaris and Tru64 @command{make}
14592 execute
14594 @smallexample
14595 cp `test -f ../pkg/src/if.c || echo ../pkg/src/`if.c f.c
14596 @end smallexample
14598 @noindent
14599 which reduces to
14601 @example
14602 cp if.c f.c
14603 @end example
14605 @noindent
14606 and thus fails.  Oops.
14608 A simple workaround, and good practice anyway, is to use @samp{$?} and
14609 @samp{$@@} when possible:
14611 @smallexample
14612 VPATH = ../pkg/src
14613 f.c: if.c
14614         cp $? $@@
14615 @end smallexample
14617 @noindent
14618 but this does not generalize well to commands with multiple
14619 prerequisites.  A more general workaround is to rewrite the rule so that
14620 the prerequisite @file{if.c} never appears as a plain word.  For
14621 example, these three rules would be safe, assuming @file{if.c} is in
14622 @file{../pkg/src} and the other files are in the working directory:
14624 @smallexample
14625 VPATH = ../pkg/src
14626 f.c: if.c f1.c
14627         cat `test -f ./if.c || echo $(VPATH)/`if.c f1.c >$@@
14628 g.c: if.c g1.c
14629         cat `test -f 'if.c' || echo $(VPATH)/`if.c g1.c >$@@
14630 h.c: if.c h1.c
14631         cat `test -f "if.c" || echo $(VPATH)/`if.c h1.c >$@@
14632 @end smallexample
14634 Things get worse when your prerequisites are in a macro.
14636 @example
14637 VPATH = ../pkg/src
14638 HEADERS = f.h g.h h.h
14639 install-HEADERS: $(HEADERS)
14640         for i in $(HEADERS); do \
14641           $(INSTALL) -m 644 \
14642             `test -f $$i || echo $(VPATH)/`$$i \
14643             $(DESTDIR)$(includedir)/$$i; \
14644         done
14645 @end example
14647 The above @code{install-HEADERS} rule is not Solaris-proof because @code{for
14648 i in $(HEADERS);} is expanded to @code{for i in f.h g.h h.h;}
14649 where @code{f.h} and @code{g.h} are plain words and are hence
14650 subject to @code{VPATH} adjustments.
14652 If the three files are in @file{../pkg/src}, the rule is run as:
14654 @example
14655 for i in ../pkg/src/f.h ../pkg/src/g.h h.h; do \
14656   install -m 644 \
14657      `test -f $i || echo ../pkg/src/`$i \
14658      /usr/local/include/$i; \
14659 done
14660 @end example
14662 where the two first @command{install} calls fail.  For instance,
14663 consider the @code{f.h} installation:
14665 @example
14666 install -m 644 \
14667   `test -f ../pkg/src/f.h || \
14668     echo ../pkg/src/ \
14669   `../pkg/src/f.h \
14670   /usr/local/include/../pkg/src/f.h;
14671 @end example
14673 @noindent
14674 It reduces to:
14676 @example
14677 install -m 644 \
14678   ../pkg/src/f.h \
14679   /usr/local/include/../pkg/src/f.h;
14680 @end example
14682 Note that the manual @code{VPATH} search did not cause any problems here;
14683 however this command installs @file{f.h} in an incorrect directory.
14685 Trying to quote @code{$(HEADERS)} in some way, as we did for
14686 @code{foo.c} a few makefiles ago, does not help:
14688 @example
14689 install-HEADERS: $(HEADERS)
14690         headers='$(HEADERS)'; \
14691         for i in $$headers; do \
14692           $(INSTALL) -m 644 \
14693             `test -f $$i || echo $(VPATH)/`$$i \
14694             $(DESTDIR)$(includedir)/$$i; \
14695         done
14696 @end example
14698 Now, @code{headers='$(HEADERS)'} macro-expands to:
14700 @example
14701 headers='f.h g.h h.h'
14702 @end example
14704 @noindent
14705 but @code{g.h} is still a plain word.  (As an aside, the idiom
14706 @code{headers='$(HEADERS)'; for i in $$headers;} is a good
14707 idea if @code{$(HEADERS)} can be empty, because some shells diagnose a
14708 syntax error on @code{for i in;}.)
14710 One workaround is to strip this unwanted @file{../pkg/src/} prefix manually:
14712 @example
14713 VPATH = ../pkg/src
14714 HEADERS = f.h g.h h.h
14715 install-HEADERS: $(HEADERS)
14716         headers='$(HEADERS)'; \
14717         for i in $$headers; do \
14718           i=`expr "$$i" : '$(VPATH)/\(.*\)'`;
14719           $(INSTALL) -m 644 \
14720             `test -f $$i || echo $(VPATH)/`$$i \
14721             $(DESTDIR)$(includedir)/$$i; \
14722         done
14723 @end example
14725 Automake does something similar.  However the above hack works only if
14726 the files listed in @code{HEADERS} are in the current directory or a
14727 subdirectory; they should not be in an enclosing directory.  If we had
14728 @code{HEADERS = ../f.h}, the above fragment would fail in a VPATH
14729 build with Tru64 @command{make}.  The reason is that not only does
14730 Tru64 @command{make} rewrite dependencies, but it also simplifies
14731 them.  Hence @code{../f.h} becomes @code{../pkg/f.h} instead of
14732 @code{../pkg/src/../f.h}.  This obviously defeats any attempt to strip
14733 a leading @file{../pkg/src/} component.
14735 The following example makes the behavior of Tru64 @command{make}
14736 more apparent.
14738 @example
14739 $ @kbd{cat Makefile}
14740 VPATH = sub
14741 all: ../foo
14742         echo ../foo
14743 $ @kbd{ls}
14744 Makefile foo
14745 $ @kbd{make}
14746 echo foo
14748 @end example
14750 @noindent
14751 Dependency @file{../foo} was found in @file{sub/../foo}, but Tru64
14752 @command{make} simplified it as @file{foo}.  (Note that the @file{sub/}
14753 directory does not even exist, this just means that the simplification
14754 occurred before the file was checked for.)
14756 For the record here is how SunOS 4 @command{make} behaves on this
14757 example.
14759 @smallexample
14760 $ @kbd{make}
14761 make: Fatal error: Don't know how to make target `../foo'
14762 $ @kbd{mkdir sub}
14763 $ @kbd{make}
14764 echo sub/../foo
14765 sub/../foo
14766 @end smallexample
14769 @node Tru64 Directory Magic
14770 @subsection Tru64 @command{make} Creates Prerequisite Directories Magically
14771 @cindex @code{VPATH} and prerequisite directories
14772 @cindex prerequisite directories and @code{VPATH}
14774 When a prerequisite is a subdirectory of @code{VPATH}, Tru64
14775 @command{make} creates it in the current directory.
14777 @example
14778 $ @kbd{mkdir -p foo/bar build}
14779 $ @kbd{cd build}
14780 $ @kbd{cat >Makefile <<END
14781 VPATH = ..
14782 all: foo/bar
14783 END}
14784 $ @kbd{make}
14785 mkdir foo
14786 mkdir foo/bar
14787 @end example
14789 This can yield unexpected results if a rule uses a manual @code{VPATH}
14790 search as presented before.
14792 @example
14793 VPATH = ..
14794 all : foo/bar
14795         command `test -d foo/bar || echo ../`foo/bar
14796 @end example
14798 The above @command{command} is run on the empty @file{foo/bar}
14799 directory that was created in the current directory.
14801 @node Make Target Lookup
14802 @subsection Make Target Lookup
14803 @cindex @code{VPATH}, resolving target pathnames
14805 @acronym{GNU} @command{make} uses a complex algorithm to decide when it
14806 should use files found via a @code{VPATH} search.  @xref{Search
14807 Algorithm, , How Directory Searches are Performed, make, The @acronym{GNU} Make
14808 Manual}.
14810 If a target needs to be rebuilt, @acronym{GNU} @command{make} discards the
14811 file name found during the @code{VPATH} search for this target, and
14812 builds the file locally using the file name given in the makefile.
14813 If a target does not need to be rebuilt, @acronym{GNU} @command{make} uses the
14814 file name found during the @code{VPATH} search.
14816 Other @command{make} implementations, like Net@acronym{BSD} @command{make}, are
14817 easier to describe: the file name found during the @code{VPATH} search
14818 is used whether the target needs to be rebuilt or not.  Therefore
14819 new files are created locally, but existing files are updated at their
14820 @code{VPATH} location.
14822 Open@acronym{BSD} and Free@acronym{BSD} @command{make}, however,
14823 never perform a
14824 @code{VPATH} search for a dependency that has an explicit rule.
14825 This is extremely annoying.
14827 When attempting a @code{VPATH} build for an autoconfiscated package
14828 (e.g., @code{mkdir build && cd build && ../configure}), this means
14829 @acronym{GNU}
14830 @command{make} builds everything locally in the @file{build}
14831 directory, while @acronym{BSD} @command{make} builds new files locally and
14832 updates existing files in the source directory.
14834 @example
14835 $ @kbd{cat Makefile}
14836 VPATH = ..
14837 all: foo.x bar.x
14838 foo.x bar.x: newer.x
14839         @@echo Building $@@
14840 $ @kbd{touch ../bar.x}
14841 $ @kbd{touch ../newer.x}
14842 $ @kbd{make}        # GNU make
14843 Building foo.x
14844 Building bar.x
14845 $ @kbd{pmake}       # NetBSD make
14846 Building foo.x
14847 Building ../bar.x
14848 $ @kbd{fmake}       # FreeBSD make, OpenBSD make
14849 Building foo.x
14850 Building bar.x
14851 $ @kbd{tmake}       # Tru64 make
14852 Building foo.x
14853 Building bar.x
14854 $ @kbd{touch ../bar.x}
14855 $ @kbd{make}        # GNU make
14856 Building foo.x
14857 $ @kbd{pmake}       # NetBSD make
14858 Building foo.x
14859 $ @kbd{fmake}       # FreeBSD make, OpenBSD make
14860 Building foo.x
14861 Building bar.x
14862 $ @kbd{tmake}       # Tru64 make
14863 Building foo.x
14864 Building bar.x
14865 @end example
14867 Note how Net@acronym{BSD} @command{make} updates @file{../bar.x} in its
14868 VPATH location, and how Free@acronym{BSD}, Open@acronym{BSD}, and Tru64
14869 @command{make} always
14870 update @file{bar.x}, even when @file{../bar.x} is up to date.
14872 Another point worth mentioning is that once @acronym{GNU} @command{make} has
14873 decided to ignore a @code{VPATH} file name (e.g., it ignored
14874 @file{../bar.x} in the above example) it continues to ignore it when
14875 the target occurs as a prerequisite of another rule.
14877 The following example shows that @acronym{GNU} @command{make} does not look up
14878 @file{bar.x} in @code{VPATH} before performing the @code{.x.y} rule,
14879 because it ignored the @code{VPATH} result of @file{bar.x} while running
14880 the @code{bar.x: newer.x} rule.
14882 @example
14883 $ @kbd{cat Makefile}
14884 VPATH = ..
14885 all: bar.y
14886 bar.x: newer.x
14887         @@echo Building $@@
14888 .SUFFIXES: .x .y
14889 .x.y:
14890         cp $< $@@
14891 $ @kbd{touch ../bar.x}
14892 $ @kbd{touch ../newer.x}
14893 $ @kbd{make}        # GNU make
14894 Building bar.x
14895 cp bar.x bar.y
14896 cp: cannot stat `bar.x': No such file or directory
14897 make: *** [bar.y] Error 1
14898 $ @kbd{pmake}       # NetBSD make
14899 Building ../bar.x
14900 cp ../bar.x bar.y
14901 $ @kbd{rm bar.y}
14902 $ @kbd{fmake}       # FreeBSD make, OpenBSD make
14903 echo Building bar.x
14904 cp bar.x bar.y
14905 cp: cannot stat `bar.x': No such file or directory
14906 *** Error code 1
14907 $ @kbd{tmake}       # Tru64 make
14908 Building bar.x
14909 cp: bar.x: No such file or directory
14910 *** Exit 1
14911 @end example
14913 Note that if you drop away the command from the @code{bar.x: newer.x}
14914 rule, @acronym{GNU} @command{make} magically starts to work: it
14915 knows that @code{bar.x} hasn't been updated, therefore it doesn't
14916 discard the result from @code{VPATH} (@file{../bar.x}) in succeeding
14917 uses.  Tru64 also works, but Free@acronym{BSD} and Open@acronym{BSD}
14918 still don't.
14920 @example
14921 $ @kbd{cat Makefile}
14922 VPATH = ..
14923 all: bar.y
14924 bar.x: newer.x
14925 .SUFFIXES: .x .y
14926 .x.y:
14927         cp $< $@@
14928 $ @kbd{touch ../bar.x}
14929 $ @kbd{touch ../newer.x}
14930 $ @kbd{make}        # GNU make
14931 cp ../bar.x bar.y
14932 $ @kbd{rm bar.y}
14933 $ @kbd{pmake}       # NetBSD make
14934 cp ../bar.x bar.y
14935 $ @kbd{rm bar.y}
14936 $ @kbd{fmake}       # FreeBSD make, OpenBSD make
14937 cp bar.x bar.y
14938 cp: cannot stat `bar.x': No such file or directory
14939 *** Error code 1
14940 $ @kbd{tmake}       # Tru64 make
14941 cp ../bar.x bar.y
14942 @end example
14944 It seems the sole solution that would please every @command{make}
14945 implementation is to never rely on @code{VPATH} searches for targets.
14946 In other words, @code{VPATH} should be reserved to unbuilt sources.
14949 @node Single Suffix Rules
14950 @section Single Suffix Rules and Separated Dependencies
14951 @cindex Single Suffix Inference Rule
14952 @cindex Rule, Single Suffix Inference
14953 A @dfn{Single Suffix Rule} is basically a usual suffix (inference) rule
14954 (@samp{.from.to:}), but which @emph{destination} suffix is empty
14955 (@samp{.from:}).
14957 @cindex Separated Dependencies
14958 @dfn{Separated dependencies} simply refers to listing the prerequisite
14959 of a target, without defining a rule.  Usually one can list on the one
14960 hand side, the rules, and on the other hand side, the dependencies.
14962 Solaris @command{make} does not support separated dependencies for
14963 targets defined by single suffix rules:
14965 @example
14966 $ @kbd{cat Makefile}
14967 .SUFFIXES: .in
14968 foo: foo.in
14969 .in:
14970         cp $< $@@
14971 $ @kbd{touch foo.in}
14972 $ @kbd{make}
14973 $ @kbd{ls}
14974 Makefile  foo.in
14975 @end example
14977 @noindent
14978 while @acronym{GNU} Make does:
14980 @example
14981 $ @kbd{gmake}
14982 cp foo.in foo
14983 $ @kbd{ls}
14984 Makefile  foo       foo.in
14985 @end example
14987 Note it works without the @samp{foo: foo.in} dependency.
14989 @example
14990 $ @kbd{cat Makefile}
14991 .SUFFIXES: .in
14992 .in:
14993         cp $< $@@
14994 $ @kbd{make foo}
14995 cp foo.in foo
14996 @end example
14998 @noindent
14999 and it works with double suffix inference rules:
15001 @example
15002 $ @kbd{cat Makefile}
15003 foo.out: foo.in
15004 .SUFFIXES: .in .out
15005 .in.out:
15006         cp $< $@@
15007 $ @kbd{make}
15008 cp foo.in foo.out
15009 @end example
15011 As a result, in such a case, you have to write target rules.
15013 @node Timestamps and Make
15014 @section Timestamp Resolution and Make
15015 @cindex timestamp resolution
15016 Traditionally, file timestamps had 1-second resolution, and
15017 @command{make} used those timestamps to determine whether one file was
15018 newer than the other.  However, many modern file systems have
15019 timestamps with 1-nanosecond resolution.  Some @command{make}
15020 implementations look at the entire timestamp; others ignore the
15021 fractional part, which can lead to incorrect results.  Normally this
15022 is not a problem, but in some extreme cases you may need to use tricks
15023 like @samp{sleep 1} to work around timestamp truncation bugs.
15025 Commands like @samp{cp -p} and @samp{touch -r} typically do not copy
15026 file timestamps to their full resolutions (@pxref{Limitations of Usual
15027 Tools}).  Hence you should be wary of rules like this:
15029 @example
15030 dest: src
15031         cp -p src dest
15032 @end example
15034 as @file{dest} often appears to be older than @file{src} after the
15035 timestamp is truncated, and this can cause @command{make} to do
15036 needless rework the next time it is invoked.  To work around this
15037 problem, you can use a timestamp file, e.g.:
15039 @example
15040 dest-stamp: src
15041         cp -p src dest
15042         date >dest-stamp
15043 @end example
15048 @c ======================================== Portable C and C++ Programming
15050 @node Portable C and C++
15051 @chapter Portable C and C++ Programming
15052 @cindex Portable C and C++ programming
15054 C and C++ programs often use low-level features of the underlying
15055 system, and therefore are often more difficult to make portable to other
15056 platforms.
15058 Several standards have been developed to help make your programs more
15059 portable.  If you write programs with these standards in mind, you can
15060 have greater confidence that your programs work on a wide variety
15061 of systems.  @xref{Standards, , Language Standards Supported by
15062 @acronym{GCC}, gcc, Using the @acronym{GNU} Compiler Collection
15063 (@acronym{GCC})}, for a list of C-related
15064 standards.  Many programs also assume the
15065 @uref{http://www.opengroup.org/susv3, Posix standard}.
15067 Some old code is written to be portable to K&R C, which predates any C
15068 standard.  K&R C compilers are no longer of practical interest, though,
15069 and the rest of section assumes at least C89, the first C standard.
15071 Program portability is a huge topic, and this section can only briefly
15072 introduce common pitfalls.  @xref{System Portability, , Portability
15073 between System Types, standards, @acronym{GNU} Coding Standards}, for
15074 more information.
15076 @menu
15077 * Varieties of Unportability::  How to make your programs unportable
15078 * Integer Overflow::            When integers get too large
15079 * Null Pointers::               Properties of null pointers
15080 * Buffer Overruns::             Subscript errors and the like
15081 * Volatile Objects::            @code{volatile} and signals
15082 * Floating Point Portability::  Portable floating-point arithmetic
15083 * Exiting Portably::            Exiting and the exit status
15084 @end menu
15086 @node Varieties of Unportability
15087 @section Varieties of Unportability
15088 @cindex portability
15090 Autoconf tests and ordinary programs often need to test what is allowed
15091 on a system, and therefore they may need to deliberately exceed the
15092 boundaries of what the standards allow, if only to see whether an
15093 optional feature is present.  When you write such a program, you should
15094 keep in mind the difference between constraints, unspecified behavior,
15095 and undefined behavior.
15097 In C, a @dfn{constraint} is a rule that the compiler must enforce.  An
15098 example constraint is that C programs must not declare a bit-field with
15099 negative width.  Tests can therefore reliably assume that programs with
15100 negative-width bit-fields are rejected by a compiler that conforms
15101 to the standard.
15103 @dfn{Unspecified behavior} is valid behavior, where the standard allows
15104 multiple possibilities.  For example, the order of evaluation of
15105 function arguments is unspecified.  Some unspecified behavior is
15106 @dfn{implementation-defined}, i.e., documented by the implementation,
15107 but since Autoconf tests cannot read the documentation they cannot
15108 distinguish between implementation-defined and other unspecified
15109 behavior.  It is common for Autoconf tests to probe implementations to
15110 determine otherwise-unspecified behavior.
15112 @dfn{Undefined behavior} is invalid behavior, where the standard allows
15113 the implementation to do anything it pleases.  For example,
15114 dereferencing a null pointer leads to undefined behavior.  If possible,
15115 test programs should avoid undefined behavior, since a program with
15116 undefined behavior might succeed on a test that should fail.
15118 The above rules apply to programs that are intended to conform to the
15119 standard.  However, strictly-conforming programs are quite rare, since
15120 the standards are so limiting.  A major goal of Autoconf is to support
15121 programs that use implementation features not described by the standard,
15122 and it is fairly common for test programs to violate the above rules, if
15123 the programs work well enough in practice.
15125 @node Integer Overflow
15126 @section Integer Overflow
15127 @cindex integer overflow
15128 @cindex overflow, signed integer
15129 @cindex signed integer overflow
15130 @cindex wraparound arithmetic
15132 In practice many portable C programs assume that signed integer overflow wraps
15133 around reliably using two's complement arithmetic.  Yet the C standard
15134 says that program behavior is undefined on overflow, and in a few cases
15135 C programs do not work on some modern implementations because their
15136 overflows do not wrap around as their authors expected.  Conversely, in
15137 signed integer remainder, the C standard requires overflow
15138 behavior that is commonly not implemented.
15140 @menu
15141 * Integer Overflow Basics::      Why integer overflow is a problem
15142 * Signed Overflow Examples::     Examples of code assuming wraparound
15143 * Optimization and Wraparound::  Optimizations that break uses of wraparound
15144 * Signed Overflow Advice::       Practical advice for signed overflow issues
15145 * Signed Integer Division::      @code{INT_MIN / -1} and @code{INT_MIN % -1}
15146 @end menu
15148 @node Integer Overflow Basics
15149 @subsection Basics of Integer Overflow
15150 @cindex integer overflow
15151 @cindex overflow, signed integer
15152 @cindex signed integer overflow
15153 @cindex wraparound arithmetic
15155 In languages like C, unsigned integer overflow reliably wraps around;
15156 e.g., @code{UINT_MAX + 1} yields zero.
15157 This is guaranteed by the C standard and is
15158 portable in practice, unless you specify aggressive,
15159 nonstandard optimization options
15160 suitable only for special applications.
15162 In contrast, the C standard says that signed integer overflow leads to
15163 undefined behavior where a program can do anything, including dumping
15164 core or overrunning a buffer.  The misbehavior can even precede the
15165 overflow.  Such an overflow can occur during addition, subtraction,
15166 multiplication, division, and left shift.
15168 Despite this requirement of the standard, many C programs and Autoconf
15169 tests assume that signed integer overflow silently wraps around modulo a
15170 power of two, using two's complement arithmetic, so long as you cast the
15171 resulting value to a signed integer type or store it into a signed
15172 integer variable.  If you use conservative optimization flags, such
15173 programs are generally portable to the vast majority of modern
15174 platforms, with a few exceptions discussed later.
15176 For historical reasons the C standard also allows implementations with
15177 ones' complement or signed magnitude arithmetic, but it is safe to
15178 assume two's complement nowadays.
15180 Also, overflow can occur when converting an out-of-range value to a
15181 signed integer type.  Here a standard implementation must define what
15182 happens, but this might include raising an exception.  In practice all
15183 known implementations support silent wraparound in this case, so you need
15184 not worry about other possibilities.
15186 @node Signed Overflow Examples
15187 @subsection Examples of Code Assuming Wraparound Overflow
15188 @cindex integer overflow
15189 @cindex overflow, signed integer
15190 @cindex signed integer overflow
15191 @cindex wraparound arithmetic
15193 There has long been a tension between what the C standard requires for
15194 signed integer overflow, and what C programs commonly assume.  The
15195 standard allows aggressive optimizations based on assumptions that
15196 overflow never occurs, but many practical C programs rely on overflow
15197 wrapping around.  These programs do not conform to the standard, but
15198 they commonly work in practice because compiler writers are
15199 understandably reluctant to implement optimizations that would break
15200 many programs, unless perhaps a user specifies aggressive optimization.
15202 The C Standard says that if a program has signed integer overflow its
15203 behavior is undefined, and the undefined behavior can even precede the
15204 overflow.  To take an extreme example:
15206 @c Inspired by Robert Dewar's example in
15207 @c <http://gcc.gnu.org/ml/gcc/2007-01/msg00038.html> (2007-01-01).
15208 @example
15209 if (password == expected_password)
15210   allow_superuser_privileges ();
15211 else if (counter++ == INT_MAX)
15212   abort ();
15213 else
15214   printf ("%d password mismatches\n", counter);
15215 @end example
15217 @noindent
15218 If the @code{int} variable @code{counter} equals @code{INT_MAX},
15219 @code{counter++} must overflow and the behavior is undefined, so the C
15220 standard allows the compiler to optimize away the test against
15221 @code{INT_MAX} and the @code{abort} call.
15222 Worse, if an earlier bug in the program lets the compiler deduce that
15223 @code{counter == INT_MAX} or that @code{counter} previously overflowed,
15224 the C standard allows the compiler to optimize away the password test
15225 and generate code that allows superuser privileges unconditionally.
15227 Despite this requirement by the standard, it has long been common for C
15228 code to assume wraparound arithmetic after signed overflow, and all
15229 known practical C implementations support some C idioms that assume
15230 wraparound signed arithmetic, even if the idioms do not conform
15231 strictly to the standard.  If your code looks like the following
15232 examples it will almost surely work with real-world compilers.
15234 Here is an example derived from the 7th Edition Unix implementation of
15235 @code{atoi} (1979-01-10):
15237 @example
15238 char *p;
15239 int f, n;
15240 @dots{}
15241 while (*p >= '0' && *p <= '9')
15242   n = n * 10 + *p++ - '0';
15243 return (f ? -n : n);
15244 @end example
15246 @noindent
15247 Even if the input string is in range, on most modern machines this has
15248 signed overflow when computing the most negative integer (the @code{-n}
15249 overflows) or a value near an extreme integer (the first @code{+}
15250 overflows).
15252 Here is another example, derived from the 7th Edition implementation of
15253 @code{rand} (1979-01-10).  Here the programmer expects both
15254 multiplication and addition to wrap on overflow:
15256 @example
15257 static long int randx = 1;
15258 @dots{}
15259 randx = randx * 1103515245 + 12345;
15260 return (randx >> 16) & 077777;
15261 @end example
15263 In the following example, derived from the @acronym{GNU} C Library 2.5
15264 implementation of @code{mktime} (2006-09-09), the code assumes
15265 wraparound arithmetic in @code{+} to detect signed overflow:
15267 @example
15268 time_t t, t1, t2;
15269 int sec_requested, sec_adjustment;
15270 @dots{}
15271 t1 = t + sec_requested;
15272 t2 = t1 + sec_adjustment;
15273 if (((t1 < t) != (sec_requested < 0))
15274     | ((t2 < t1) != (sec_adjustment < 0)))
15275   return -1;
15276 @end example
15278 If your code looks like these examples, it is probably safe even though
15279 it does not strictly conform to the C standard.  This might lead one to
15280 believe that one can generally assume wraparound on overflow, but that
15281 is not always true, as can be seen in the next section.
15283 @node Optimization and Wraparound
15284 @subsection Optimizations That Break Wraparound Arithmetic
15285 @cindex loop induction
15287 Compilers sometimes generate code that is incompatible with wraparound
15288 integer arithmetic.  A simple example is an algebraic simplification: a
15289 compiler might translate @code{(i * 2000) / 1000} to @code{i * 2}
15290 because it assumes that @code{i * 2000} does not overflow.  The
15291 translation is not equivalent to the original when overflow occurs:
15292 e.g., in the typical case of 32-bit signed two's complement wraparound
15293 @code{int}, if @code{i} has type @code{int} and value @code{1073742},
15294 the original expression returns @minus{}2147483 but the optimized
15295 version returns the mathematically correct value 2147484.
15297 More subtly, loop induction optimizations often exploit the undefined
15298 behavior of signed overflow.  Consider the following contrived function
15299 @code{sumc}:
15301 @example
15303 sumc (int lo, int hi)
15305   int sum = 0;
15306   int i;
15307   for (i = lo; i <= hi; i++)
15308     sum ^= i * 53;
15309   return sum;
15311 @end example
15313 @noindent
15314 To avoid multiplying by 53 each time through the loop, an optimizing
15315 compiler might internally transform @code{sumc} to the equivalent of the
15316 following:
15318 @example
15320 transformed_sumc (int lo, int hi)
15322   int sum = 0;
15323   int hic = hi * 53;
15324   int ic;
15325   for (ic = lo * 53; ic <= hic; ic += 53)
15326     sum ^= ic;
15327   return sum;
15329 @end example
15331 @noindent
15332 This transformation is allowed by the C standard, but it is invalid for
15333 wraparound arithmetic when @code{INT_MAX / 53 < hi}, because then the
15334 overflow in computing expressions like @code{hi * 53} can cause the
15335 expression @code{i <= hi} to yield a different value from the
15336 transformed expression @code{ic <= hic}.
15338 For this reason, compilers that use loop induction and similar
15339 techniques often do not support reliable wraparound arithmetic when a
15340 loop induction variable like @code{ic} is involved.  Since loop
15341 induction variables are generated by the compiler, and are not visible
15342 in the source code, it is not always trivial to say whether the problem
15343 affects your code.
15345 Hardly any code actually depends on wraparound arithmetic in cases like
15346 these, so in practice these loop induction optimizations are almost
15347 always useful.  However, edge cases in this area can cause problems.
15348 For example:
15350 @example
15351 int j;
15352 for (j = 1; 0 < j; j *= 2)
15353   test (j);
15354 @end example
15356 @noindent
15357 Here, the loop attempts to iterate through all powers of 2 that
15358 @code{int} can represent, but the C standard allows a compiler to
15359 optimize away the comparison and generate an infinite loop,
15360 under the argument that behavior is undefined on overflow.  As of this
15361 writing this optimization is not done by any production version of
15362 @acronym{GCC} with @option{-O2}, but it might be performed by other
15363 compilers, or by more aggressive @acronym{GCC} optimization options,
15364 and the @acronym{GCC} developers have not decided whether it will
15365 continue to work with @acronym{GCC} and @option{-O2}.
15367 @node Signed Overflow Advice
15368 @subsection Practical Advice for Signed Overflow Issues
15369 @cindex integer overflow
15370 @cindex overflow, signed integer
15371 @cindex signed integer overflow
15372 @cindex wraparound arithmetic
15374 Ideally the safest approach is to avoid signed integer overflow
15375 entirely.  For example, instead of multiplying two signed integers, you
15376 can convert them to unsigned integers, multiply the unsigned values,
15377 then test whether the result is in signed range.
15379 Rewriting code in this way will be inconvenient, though, particularly if
15380 the signed values might be negative.  Also, it may hurt
15381 performance.  Using unsigned arithmetic to check for overflow is
15382 particularly painful to do portably and efficiently when dealing with an
15383 integer type like @code{uid_t} whose width and signedness vary from
15384 platform to platform.
15386 Furthermore, many C applications pervasively assume wraparound behavior
15387 and typically it is not easy to find and remove all these assumptions.
15388 Hence it is often useful to maintain nonstandard code that assumes
15389 wraparound on overflow, instead of rewriting the code.  The rest of this
15390 section attempts to give practical advice for this situation.
15392 If your code wants to detect signed integer overflow in @code{sum = a +
15393 b}, it is generally safe to use an expression like @code{(sum < a) != (b
15394 < 0)}.
15396 If your code uses a signed loop index, make sure that the index cannot
15397 overflow, along with all signed expressions derived from the index.
15398 Here is a contrived example of problematic code with two instances of
15399 overflow.
15401 @example
15402 for (i = INT_MAX - 10; i <= INT_MAX; i++)
15403   if (i + 1 < 0)
15404     @{
15405       report_overflow ();
15406       break;
15407     @}
15408 @end example
15410 @noindent
15411 Because of the two overflows, a compiler might optimize away or
15412 transform the two comparisons in a way that is incompatible with the
15413 wraparound assumption.
15415 If your code uses an expression like @code{(i * 2000) / 1000} and you
15416 actually want the multiplication to wrap around on overflow, use
15417 unsigned arithmetic
15418 to do it, e.g., @code{((int) (i * 2000u)) / 1000}.
15420 If your code assumes wraparound behavior and you want to insulate it
15421 against any @acronym{GCC} optimizations that would fail to support that
15422 behavior, you should use @acronym{GCC}'s @option{-fwrapv} option, which
15423 causes signed overflow to wrap around reliably (except for division and
15424 remainder, as discussed in the next section).
15426 If you need to port to platforms where signed integer overflow does not
15427 reliably wrap around (e.g., due to hardware overflow checking, or to
15428 highly aggressive optimizations), you should consider debugging with
15429 @acronym{GCC}'s @option{-ftrapv} option, which causes signed overflow to
15430 raise an exception.
15432 @node Signed Integer Division
15433 @subsection Signed Integer Division and Integer Overflow
15434 @cindex division, integer
15436 Overflow in signed
15437 integer division is not always harmless: for example, on CPUs of the
15438 i386 family, dividing @code{INT_MIN} by @code{-1} yields a SIGFPE signal
15439 which by default terminates the program.  Worse, taking the remainder
15440 of these two values typically yields the same signal on these CPUs,
15441 even though the C standard requires @code{INT_MIN % -1} to yield zero
15442 because the expression does not overflow.
15444 @node Null Pointers
15445 @section Properties of Null Pointers
15446 @cindex null pointers
15448 Most modern hosts reliably fail when you attempt to dereference a null
15449 pointer.
15451 On almost all modern hosts, null pointers use an all-bits-zero internal
15452 representation, so you can reliably use @code{memset} with 0 to set all
15453 the pointers in an array to null values.
15455 If @code{p} is a null pointer to an object type, the C expression
15456 @code{p + 0} always evaluates to @code{p} on modern hosts, even though
15457 the standard says that it has undefined behavior.
15459 @node Buffer Overruns
15460 @section Buffer Overruns and Subscript Errors
15461 @cindex buffer overruns
15463 Buffer overruns and subscript errors are the most common dangerous
15464 errors in C programs.  They result in undefined behavior because storing
15465 outside an array typically modifies storage that is used by some other
15466 object, and most modern systems lack runtime checks to catch these
15467 errors.  Programs should not rely on buffer overruns being caught.
15469 There is one exception to the usual rule that a portable program cannot
15470 address outside an array.  In C, it is valid to compute the address just
15471 past an object, e.g., @code{&a[N]} where @code{a} has @code{N} elements,
15472 so long as you do not dereference the resulting pointer.  But it is not
15473 valid to compute the address just before an object, e.g., @code{&a[-1]};
15474 nor is it valid to compute two past the end, e.g., @code{&a[N+1]}.  On
15475 most platforms @code{&a[-1] < &a[0] && &a[N] < &a[N+1]}, but this is not
15476 reliable in general, and it is usually easy enough to avoid the
15477 potential portability problem, e.g., by allocating an extra unused array
15478 element at the start or end.
15480 @uref{http://valgrind.org/, Valgrind} can catch many overruns.
15481 @acronym{GCC}
15482 users might also consider using the @option{-fmudflap} option to catch
15483 overruns.
15485 Buffer overruns are usually caused by off-by-one errors, but there are
15486 more subtle ways to get them.
15488 Using @code{int} values to index into an array or compute array sizes
15489 causes problems on typical 64-bit hosts where an array index might
15490 be @math{2^31} or larger.  Index values of type @code{size_t} avoid this
15491 problem, but cannot be negative.  Index values of type @code{ptrdiff_t}
15492 are signed, and are wide enough in practice.
15494 If you add or multiply two numbers to calculate an array size, e.g.,
15495 @code{malloc (x * sizeof y + z)}, havoc ensues if the addition or
15496 multiplication overflows.
15498 Many implementations of the @code{alloca} function silently misbehave
15499 and can generate buffer overflows if given sizes that are too large.
15500 The size limits are implementation dependent, but are at least 4000
15501 bytes on all platforms that we know about.
15503 The standard functions @code{asctime}, @code{asctime_r}, @code{ctime},
15504 @code{ctime_r}, and @code{gets} are prone to buffer overflows, and
15505 portable code should not use them unless the inputs are known to be
15506 within certain limits.  The time-related functions can overflow their
15507 buffers if given timestamps out of range (e.g., a year less than -999
15508 or greater than 9999).  Time-related buffer overflows cannot happen with
15509 recent-enough versions of the @acronym{GNU} C library, but are possible
15510 with other
15511 implementations.  The @code{gets} function is the worst, since it almost
15512 invariably overflows its buffer when presented with an input line larger
15513 than the buffer.
15515 @node Volatile Objects
15516 @section Volatile Objects
15517 @cindex volatile objects
15519 The keyword @code{volatile} is often misunderstood in portable code.
15520 Its use inhibits some memory-access optimizations, but programmers often
15521 wish that it had a different meaning than it actually does.
15523 @code{volatile} was designed for code that accesses special objects like
15524 memory-mapped device registers whose contents spontaneously change.
15525 Such code is inherently low-level, and it is difficult to specify
15526 portably what @code{volatile} means in these cases.  The C standard
15527 says, ``What constitutes an access to an object that has
15528 volatile-qualified type is implementation-defined,'' so in theory each
15529 implementation is supposed to fill in the gap by documenting what
15530 @code{volatile} means for that implementation.  In practice, though,
15531 this documentation is usually absent or incomplete.
15533 One area of confusion is the distinction between objects defined with
15534 volatile types, and volatile lvalues.  From the C standard's point of
15535 view, an object defined with a volatile type has externally visible
15536 behavior.  You can think of such objects as having little oscilloscope
15537 probes attached to them, so that the user can observe some properties of
15538 accesses to them, just as the user can observe data written to output
15539 files.  However, the standard does not make it clear whether users can
15540 observe accesses by volatile lvalues to ordinary objects.  For example:
15542 @example
15543 /* Declare and access a volatile object.
15544    Accesses to X are "visible" to users.  */
15545 static int volatile x;
15546 x = 1;
15548 /* Access two ordinary objects via a volatile lvalue.
15549    It's not clear whether accesses to *P are "visible".  */
15550 int y;
15551 int *z = malloc (sizeof (int));
15552 int volatile *p;
15553 p = &y;
15554 *p = 1;
15555 p = z;
15556 *p = 1;
15557 @end example
15559 Programmers often wish that @code{volatile} meant ``Perform the memory
15560 access here and now, without merging several memory accesses, without
15561 changing the memory word size, and without reordering.''  But the C
15562 standard does not require this.  For objects defined with a volatile
15563 type, accesses must be done before the next sequence point; but
15564 otherwise merging, reordering, and word-size change is allowed.  Worse,
15565 it is not clear from the standard whether volatile lvalues provide more
15566 guarantees in general than nonvolatile lvalues, if the underlying
15567 objects are ordinary.
15569 Even when accessing objects defined with a volatile type,
15570 the C standard allows only
15571 extremely limited signal handlers: the behavior is undefined if a signal
15572 handler reads any nonlocal object, or writes to any nonlocal object
15573 whose type is not @code{sig_atomic_t volatile}, or calls any standard
15574 library function other than @code{abort}, @code{signal}, and (if C99)
15575 @code{_Exit}.  Hence C compilers need not worry about a signal handler
15576 disturbing ordinary computation, unless the computation accesses a
15577 @code{sig_atomic_t volatile} lvalue that is not a local variable.
15578 (There is an obscure exception for accesses via a pointer to a volatile
15579 character, since it may point into part of a @code{sig_atomic_t
15580 volatile} object.)  Posix
15581 adds to the list of library functions callable from a portable signal
15582 handler, but otherwise is like the C standard in this area.
15584 Some C implementations allow memory-access optimizations within each
15585 translation unit, such that actual behavior agrees with the behavior
15586 required by the standard only when calling a function in some other
15587 translation unit, and a signal handler acts like it was called from a
15588 different translation unit.  The C standard hints that in these
15589 implementations, objects referred to by signal handlers ``would require
15590 explicit specification of @code{volatile} storage, as well as other
15591 implementation-defined restrictions.''  But unfortunately even for this
15592 special case these other restrictions are often not documented well.
15593 @xref{Volatiles, , When is a Volatile Object Accessed?, gcc, Using the
15594 @acronym{GNU} Compiler Collection (@acronym{GCC})}, for some
15595 restrictions imposed by @acronym{GCC}.  @xref{Defining Handlers, ,
15596 Defining Signal Handlers, libc, The @acronym{GNU} C Library}, for some
15597 restrictions imposed by the @acronym{GNU} C library.  Restrictions
15598 differ on other platforms.
15600 If possible, it is best to use a signal handler that fits within the
15601 limits imposed by the C and Posix standards.
15603 If this is not practical, you can try the following rules of thumb.  A
15604 signal handler should access only volatile lvalues, preferably lvalues
15605 that refer to objects defined with a volatile type, and should not
15606 assume that the accessed objects have an internally consistent state
15607 if they are larger than a machine word.  Furthermore, installers
15608 should employ compilers and compiler options that are commonly used
15609 for building operating system kernels, because kernels often need more
15610 from @code{volatile} than the C Standard requires, and installers who
15611 compile an application in a similar environment can sometimes benefit
15612 from the extra constraints imposed by kernels on compilers.
15613 Admittedly we are handwaving somewhat here, as there are few
15614 guarantees in this area; the rules of thumb may help to fix some bugs
15615 but there is a good chance that they will not fix them all.
15617 For @code{volatile}, C++ has the same problems that C does.
15618 Multithreaded applications have even more problems with @code{volatile},
15619 but they are beyond the scope of this section.
15621 The bottom line is that using @code{volatile} typically hurts
15622 performance but should not hurt correctness.  In some cases its use
15623 does help correctness, but these cases are often so poorly understood
15624 that all too often adding @code{volatile} to a data structure merely
15625 alleviates some symptoms of a bug while not fixing the bug in general.
15627 @node Floating Point Portability
15628 @section Floating Point Portability
15629 @cindex floating point
15631 Almost all modern systems use IEEE-754 floating point, and it is safe to
15632 assume IEEE-754 in most portable code these days.  For more information,
15633 please see David Goldberg's classic paper
15634 @uref{http://www.validlab.com/goldberg/paper.pdf, What Every Computer
15635 Scientist Should Know About Floating-Point Arithmetic}.
15637 @node Exiting Portably
15638 @section Exiting Portably
15639 @cindex exiting portably
15641 A C or C++ program can exit with status @var{N} by returning
15642 @var{N} from the @code{main} function.  Portable programs are supposed
15643 to exit either with status 0 or @code{EXIT_SUCCESS} to succeed, or with
15644 status @code{EXIT_FAILURE} to fail, but in practice it is portable to
15645 fail by exiting with status 1, and test programs that assume Posix can
15646 fail by exiting with status values from 1 through 255.  Programs on
15647 SunOS 2.0 (1985) through 3.5.2 (1988) incorrectly exited with zero
15648 status when @code{main} returned nonzero, but ancient systems like these
15649 are no longer of practical concern.
15651 A program can also exit with status @var{N} by passing @var{N} to the
15652 @code{exit} function, and a program can fail by calling the @code{abort}
15653 function.  If a program is specialized to just some platforms, it can fail
15654 by calling functions specific to those platforms, e.g., @code{_exit}
15655 (Posix) and @code{_Exit} (C99).  However, like other functions, an exit
15656 function should be declared, typically by including a header.  For
15657 example, if a C program calls @code{exit}, it should include @file{stdlib.h}
15658 either directly or via the default includes (@pxref{Default Includes}).
15660 A program can fail due to undefined behavior such as dereferencing a null
15661 pointer, but this is not recommended as undefined behavior allows an
15662 implementation to do whatever it pleases and this includes exiting
15663 successfully.
15666 @c ================================================== Manual Configuration
15668 @node Manual Configuration
15669 @chapter Manual Configuration
15671 A few kinds of features can't be guessed automatically by running test
15672 programs.  For example, the details of the object-file format, or
15673 special options that need to be passed to the compiler or linker.  You
15674 can check for such features using ad-hoc means, such as having
15675 @command{configure} check the output of the @code{uname} program, or
15676 looking for libraries that are unique to particular systems.  However,
15677 Autoconf provides a uniform method for handling unguessable features.
15679 @menu
15680 * Specifying Names::            Specifying the system type
15681 * Canonicalizing::              Getting the canonical system type
15682 * Using System Type::           What to do with the system type
15683 @end menu
15685 @node Specifying Names
15686 @section Specifying the System Type
15687 @cindex System type
15689 Autoconf-generated
15690 @command{configure} scripts can make decisions based on a canonical name
15691 for the system type, which has the form:
15692 @samp{@var{cpu}-@var{vendor}-@var{os}}, where @var{os} can be
15693 @samp{@var{system}} or @samp{@var{kernel}-@var{system}}
15695 @command{configure} can usually guess the canonical name for the type of
15696 system it's running on.  To do so it runs a script called
15697 @command{config.guess}, which infers the name using the @code{uname}
15698 command or symbols predefined by the C preprocessor.
15700 Alternately, the user can specify the system type with command line
15701 arguments to @command{configure}.  Doing so is necessary when
15702 cross-compiling.  In the most complex case of cross-compiling, three
15703 system types are involved.  The options to specify them are:
15705 @table @option
15706 @item --build=@var{build-type}
15707 the type of system on which the package is being configured and
15708 compiled.  It defaults to the result of running @command{config.guess}.
15710 @item --host=@var{host-type}
15711 the type of system on which the package runs.  By default it is the
15712 same as the build machine.  Specifying it enables the cross-compilation
15713 mode.
15715 @item --target=@var{target-type}
15716 the type of system for which any compiler tools in the package
15717 produce code (rarely needed).  By default, it is the same as host.
15718 @end table
15720 If you mean to override the result of @command{config.guess}, use
15721 @option{--build}, not @option{--host}, since the latter enables
15722 cross-compilation.  For historical reasons,
15723 whenever you specify @option{--host},
15724 be sure to specify @option{--build} too; this will be fixed in the
15725 future.  So, to enter cross-compilation mode, use a command like this
15727 @example
15728 ./configure --build=i686-pc-linux-gnu --host=m68k-coff
15729 @end example
15731 @noindent
15732 Note that if you do not specify @option{--host}, @command{configure}
15733 fails if it can't run the code generated by the specified compiler.  For
15734 example, configuring as follows fails:
15736 @example
15737 ./configure CC=m68k-coff-gcc
15738 @end example
15740 In the future, when cross-compiling Autoconf will @emph{not}
15741 accept tools (compilers, linkers, assemblers) whose name is not
15742 prefixed with the host type.  The only case when this may be
15743 useful is when you really are not cross-compiling, but only
15744 building for a least-common-denominator architecture: an example
15745 is building for @code{i386-pc-linux-gnu} while running on an
15746 @code{i686-pc-linux-gnu} architecture.  In this case, some particular
15747 pairs might be similar enough to let you get away with the system
15748 compilers, but in general the compiler might make bogus assumptions
15749 on the host: if you know what you are doing, please create symbolic
15750 links from the host compiler to the build compiler.
15752 @cindex @command{config.sub}
15753 @command{configure} recognizes short aliases for many system types; for
15754 example, @samp{decstation} can be used instead of
15755 @samp{mips-dec-ultrix4.2}.  @command{configure} runs a script called
15756 @command{config.sub} to canonicalize system type aliases.
15758 This section deliberately omits the description of the obsolete
15759 interface; see @ref{Hosts and Cross-Compilation}.
15762 @node Canonicalizing
15763 @section Getting the Canonical System Type
15764 @cindex System type
15765 @cindex Canonical system type
15767 The following macros make the system type available to @command{configure}
15768 scripts.
15770 @ovindex build_alias
15771 @ovindex host_alias
15772 @ovindex target_alias
15774 The variables @samp{build_alias}, @samp{host_alias}, and
15775 @samp{target_alias} are always exactly the arguments of @option{--build},
15776 @option{--host}, and @option{--target}; in particular, they are left empty
15777 if the user did not use them, even if the corresponding
15778 @code{AC_CANONICAL} macro was run.  Any configure script may use these
15779 variables anywhere.  These are the variables that should be used when in
15780 interaction with the user.
15782 If you need to recognize some special environments based on their system
15783 type, run the following macros to get canonical system names.  These
15784 variables are not set before the macro call.
15786 If you use these macros, you must distribute @command{config.guess} and
15787 @command{config.sub} along with your source code.  @xref{Output}, for
15788 information about the @code{AC_CONFIG_AUX_DIR} macro which you can use
15789 to control in which directory @command{configure} looks for those scripts.
15792 @defmac AC_CANONICAL_BUILD
15793 @acindex{CANONICAL_BUILD}
15794 @ovindex build
15795 @ovindex build_cpu
15796 @ovindex build_vendor
15797 @ovindex build_os
15798 Compute the canonical build-system type variable, @code{build}, and its
15799 three individual parts @code{build_cpu}, @code{build_vendor}, and
15800 @code{build_os}.
15802 If @option{--build} was specified, then @code{build} is the
15803 canonicalization of @code{build_alias} by @command{config.sub},
15804 otherwise it is determined by the shell script @command{config.guess}.
15805 @end defmac
15807 @defmac AC_CANONICAL_HOST
15808 @acindex{CANONICAL_HOST}
15809 @ovindex host
15810 @ovindex host_cpu
15811 @ovindex host_vendor
15812 @ovindex host_os
15813 Compute the canonical host-system type variable, @code{host}, and its
15814 three individual parts @code{host_cpu}, @code{host_vendor}, and
15815 @code{host_os}.
15817 If @option{--host} was specified, then @code{host} is the
15818 canonicalization of @code{host_alias} by @command{config.sub},
15819 otherwise it defaults to @code{build}.
15820 @end defmac
15822 @defmac AC_CANONICAL_TARGET
15823 @acindex{CANONICAL_TARGET}
15824 @ovindex target
15825 @ovindex target_cpu
15826 @ovindex target_vendor
15827 @ovindex target_os
15828 Compute the canonical target-system type variable, @code{target}, and its
15829 three individual parts @code{target_cpu}, @code{target_vendor}, and
15830 @code{target_os}.
15832 If @option{--target} was specified, then @code{target} is the
15833 canonicalization of @code{target_alias} by @command{config.sub},
15834 otherwise it defaults to @code{host}.
15835 @end defmac
15837 Note that there can be artifacts due to the backward compatibility
15838 code.  See @xref{Hosts and Cross-Compilation}, for more.
15840 @node Using System Type
15841 @section Using the System Type
15843 In @file{configure.ac} the system type is generally used by one or more
15844 @code{case} statements to select system-specifics.  Shell wildcards can
15845 be used to match a group of system types.
15847 For example, an extra assembler code object file could be chosen, giving
15848 access to a CPU cycle counter register.  @code{$(CYCLE_OBJ)} in the
15849 following would be used in a makefile to add the object to a
15850 program or library.
15852 @example
15853 case $host in
15854   alpha*-*-*) CYCLE_OBJ=rpcc.o ;;
15855   i?86-*-*)   CYCLE_OBJ=rdtsc.o ;;
15856   *)          CYCLE_OBJ= ;;
15857 esac
15858 AC_SUBST([CYCLE_OBJ])
15859 @end example
15861 @code{AC_CONFIG_LINKS} (@pxref{Configuration Links}) is another good way
15862 to select variant source files, for example optimized code for some
15863 CPUs.  The configured CPU type doesn't always indicate exact CPU types,
15864 so some runtime capability checks may be necessary too.
15866 @example
15867 case $host in
15868   alpha*-*-*)   AC_CONFIG_LINKS([dither.c:alpha/dither.c]) ;;
15869   powerpc*-*-*) AC_CONFIG_LINKS([dither.c:powerpc/dither.c]) ;;
15870   *-*-*)        AC_CONFIG_LINKS([dither.c:generic/dither.c]) ;;
15871 esac
15872 @end example
15874 The host system type can also be used to find cross-compilation tools
15875 with @code{AC_CHECK_TOOL} (@pxref{Generic Programs}).
15877 The above examples all show @samp{$host}, since this is where the code
15878 is going to run.  Only rarely is it necessary to test @samp{$build}
15879 (which is where the build is being done).
15881 Whenever you're tempted to use @samp{$host} it's worth considering
15882 whether some sort of probe would be better.  New system types come along
15883 periodically or previously missing features are added.  Well-written
15884 probes can adapt themselves to such things, but hard-coded lists of
15885 names can't.  Here are some guidelines,
15887 @itemize @bullet
15888 @item
15889 Availability of libraries and library functions should always be checked
15890 by probing.
15891 @item
15892 Variant behavior of system calls is best identified with runtime tests
15893 if possible, but bug workarounds or obscure difficulties might have to
15894 be driven from @samp{$host}.
15895 @item
15896 Assembler code is inevitably highly CPU-specific and is best selected
15897 according to @samp{$host_cpu}.
15898 @item
15899 Assembler variations like underscore prefix on globals or ELF versus
15900 COFF type directives are however best determined by probing, perhaps
15901 even examining the compiler output.
15902 @end itemize
15904 @samp{$target} is for use by a package creating a compiler or similar.
15905 For ordinary packages it's meaningless and should not be used.  It
15906 indicates what the created compiler should generate code for, if it can
15907 cross-compile.  @samp{$target} generally selects various hard-coded CPU
15908 and system conventions, since usually the compiler or tools under
15909 construction themselves determine how the target works.
15912 @c ===================================================== Site Configuration.
15914 @node Site Configuration
15915 @chapter Site Configuration
15917 @command{configure} scripts support several kinds of local configuration
15918 decisions.  There are ways for users to specify where external software
15919 packages are, include or exclude optional features, install programs
15920 under modified names, and set default values for @command{configure}
15921 options.
15923 @menu
15924 * Help Formatting::             Customizing @samp{configure --help}
15925 * External Software::           Working with other optional software
15926 * Package Options::             Selecting optional features
15927 * Pretty Help Strings::         Formatting help string
15928 * Option Checking::             Controlling checking of @command{configure} options
15929 * Site Details::                Configuring site details
15930 * Transforming Names::          Changing program names when installing
15931 * Site Defaults::               Giving @command{configure} local defaults
15932 @end menu
15934 @node Help Formatting
15935 @section Controlling Help Output
15937 Users consult @samp{configure --help} to learn of configuration
15938 decisions specific to your package.  By default, @command{configure}
15939 breaks this output into sections for each type of option; within each
15940 section, help strings appear in the order @file{configure.ac} defines
15941 them:
15943 @example
15944 Optional Features:
15945   @dots{}
15946   --enable-bar            include bar
15948 Optional Packages:
15949   @dots{}
15950   --with-foo              use foo
15951 @end example
15953 @defmac AC_PRESERVE_HELP_ORDER
15954 @acindex{PRESERVE_HELP_ORDER}
15956 Request an alternate @option{--help} format, in which options of all
15957 types appear together, in the order defined.  Call this macro before any
15958 @code{AC_ARG_ENABLE} or @code{AC_ARG_WITH}.
15960 @example
15961 Optional Features and Packages:
15962   @dots{}
15963   --enable-bar            include bar
15964   --with-foo              use foo
15965 @end example
15967 @end defmac
15969 @node External Software
15970 @section Working With External Software
15971 @cindex External software
15973 Some packages require, or can optionally use, other software packages
15974 that are already installed.  The user can give @command{configure}
15975 command line options to specify which such external software to use.
15976 The options have one of these forms:
15978 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
15979 @c awful.
15980 @example
15981 --with-@var{package}[=@var{arg}]
15982 --without-@var{package}
15983 @end example
15985 For example, @option{--with-gnu-ld} means work with the @acronym{GNU} linker
15986 instead of some other linker.  @option{--with-x} means work with The X
15987 Window System.
15989 The user can give an argument by following the package name with
15990 @samp{=} and the argument.  Giving an argument of @samp{no} is for
15991 packages that are used by default; it says to @emph{not} use the
15992 package.  An argument that is neither @samp{yes} nor @samp{no} could
15993 include a name or number of a version of the other package, to specify
15994 more precisely which other package this program is supposed to work
15995 with.  If no argument is given, it defaults to @samp{yes}.
15996 @option{--without-@var{package}} is equivalent to
15997 @option{--with-@var{package}=no}.
15999 Normally @command{configure} scripts complain about
16000 @option{--with-@var{package}} options that they do not support.
16001 @xref{Option Checking}, for details, and for how to override the
16002 defaults.
16004 For each external software package that may be used, @file{configure.ac}
16005 should call @code{AC_ARG_WITH} to detect whether the @command{configure}
16006 user asked to use it.  Whether each package is used or not by default,
16007 and which arguments are valid, is up to you.
16009 @defmac AC_ARG_WITH (@var{package}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given})
16010 @acindex{ARG_WITH}
16011 If the user gave @command{configure} the option @option{--with-@var{package}}
16012 or @option{--without-@var{package}}, run shell commands
16013 @var{action-if-given}.  If neither option was given, run shell commands
16014 @var{action-if-not-given}.  The name @var{package} indicates another
16015 software package that this program should work with.  It should consist
16016 only of alphanumeric characters, dashes, and dots.
16018 The option's argument is available to the shell commands
16019 @var{action-if-given} in the shell variable @code{withval}, which is
16020 actually just the value of the shell variable named
16021 @code{with_@var{package}}, with any non-alphanumeric characters in
16022 @var{package} changed into @samp{_}.  You may use that variable instead,
16023 if you wish.
16025 The argument @var{help-string} is a description of the option that
16026 looks like this:
16027 @example
16028   --with-readline         support fancy command line editing
16029 @end example
16031 @noindent
16032 @var{help-string} may be more than one line long, if more detail is
16033 needed.  Just make sure the columns line up in @samp{configure
16034 --help}.  Avoid tabs in the help string.  You'll need to enclose the
16035 help string in @samp{[} and @samp{]} in order to produce the leading
16036 blanks.
16038 You should format your @var{help-string} with the macro
16039 @code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
16041 The following example shows how to use the @code{AC_ARG_WITH} macro in
16042 a common situation.  You want to let the user decide whether to enable
16043 support for an external library (e.g., the readline library); if the user
16044 specified neither @option{--with-readline} nor @option{--without-readline},
16045 you want to enable support for readline only if the library is available
16046 on the system.
16048 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
16049 @example
16050 AC_ARG_WITH([readline],
16051   [AS_HELP_STRING([--with-readline],
16052     [support fancy command line editing @@<:@@default=check@@:>@@])],
16053   [],
16054   [with_readline=check])
16056 LIBREADLINE=
16057 AS_IF([test "x$with_readline" != xno],
16058   [AC_CHECK_LIB([readline], [main],
16059     [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
16060      AC_DEFINE([HAVE_LIBREADLINE], [1],
16061                [Define if you have libreadline])
16062     ],
16063     [if test "x$with_readline" != xcheck; then
16064        AC_MSG_FAILURE(
16065          [--with-readline was given, but test for readline failed])
16066      fi
16067     ], -lncurses)])
16068 @end example
16070 The next example shows how to use @code{AC_ARG_WITH} to give the user the
16071 possibility to enable support for the readline library, in case it is still
16072 experimental and not well tested, and is therefore disabled by default.
16074 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
16075 @example
16076 AC_ARG_WITH([readline],
16077   [AS_HELP_STRING([--with-readline],
16078     [enable experimental support for readline])],
16079   [],
16080   [with_readline=no])
16082 LIBREADLINE=
16083 AS_IF([test "x$with_readline" != xno],
16084   [AC_CHECK_LIB([readline], [main],
16085     [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
16086      AC_DEFINE([HAVE_LIBREADLINE], [1],
16087                [Define if you have libreadline])
16088     ],
16089     [AC_MSG_FAILURE(
16090        [--with-readline was given, but test for readline failed])],
16091     [-lncurses])])
16092 @end example
16094 The last example shows how to use @code{AC_ARG_WITH} to give the user the
16095 possibility to disable support for the readline library, given that it is
16096 an important feature and that it should be enabled by default.
16098 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
16099 @example
16100 AC_ARG_WITH([readline],
16101   [AS_HELP_STRING([--without-readline],
16102     [disable support for readline])],
16103   [],
16104   [with_readline=yes])
16106 LIBREADLINE=
16107 AS_IF([test "x$with_readline" != xno],
16108   [AC_CHECK_LIB([readline], [main],
16109     [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
16110      AC_DEFINE([HAVE_LIBREADLINE], [1],
16111                [Define if you have libreadline])
16112     ],
16113     [AC_MSG_FAILURE(
16114        [readline test failed (--without-readline to disable)])],
16115     [-lncurses])])
16116 @end example
16118 These three examples can be easily adapted to the case where
16119 @code{AC_ARG_ENABLE} should be preferred to @code{AC_ARG_WITH} (see
16120 @ref{Package Options}).
16121 @end defmac
16123 @defmac AC_WITH (@var{package}, @var{action-if-given}, @ovar{action-if-not-given})
16124 @acindex{WITH}
16125 This is an obsolete version of @code{AC_ARG_WITH} that does not
16126 support providing a help string.
16127 @end defmac
16129 @node Package Options
16130 @section Choosing Package Options
16131 @cindex Package options
16132 @cindex Options, package
16134 If a software package has optional compile-time features, the user can
16135 give @command{configure} command line options to specify whether to
16136 compile them.  The options have one of these forms:
16138 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
16139 @c awful.
16140 @example
16141 --enable-@var{feature}[=@var{arg}]
16142 --disable-@var{feature}
16143 @end example
16145 These options allow users to choose which optional features to build and
16146 install.  @option{--enable-@var{feature}} options should never make a
16147 feature behave differently or cause one feature to replace another.
16148 They should only cause parts of the program to be built rather than left
16149 out.
16151 The user can give an argument by following the feature name with
16152 @samp{=} and the argument.  Giving an argument of @samp{no} requests
16153 that the feature @emph{not} be made available.  A feature with an
16154 argument looks like @option{--enable-debug=stabs}.  If no argument is
16155 given, it defaults to @samp{yes}.  @option{--disable-@var{feature}} is
16156 equivalent to @option{--enable-@var{feature}=no}.
16158 Normally @command{configure} scripts complain about
16159 @option{--enable-@var{package}} options that they do not support.
16160 @xref{Option Checking}, for details, and for how to override the
16161 defaults.
16163 For each optional feature, @file{configure.ac} should call
16164 @code{AC_ARG_ENABLE} to detect whether the @command{configure} user asked
16165 to include it.  Whether each feature is included or not by default, and
16166 which arguments are valid, is up to you.
16168 @defmac AC_ARG_ENABLE (@var{feature}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given})
16169 @acindex{ARG_ENABLE}
16170 If the user gave @command{configure} the option
16171 @option{--enable-@var{feature}} or @option{--disable-@var{feature}}, run
16172 shell commands @var{action-if-given}.  If neither option was given, run
16173 shell commands @var{action-if-not-given}.  The name @var{feature}
16174 indicates an optional user-level facility.  It should consist only of
16175 alphanumeric characters, dashes, and dots.
16177 The option's argument is available to the shell commands
16178 @var{action-if-given} in the shell variable @code{enableval}, which is
16179 actually just the value of the shell variable named
16180 @code{enable_@var{feature}}, with any non-alphanumeric characters in
16181 @var{feature} changed into @samp{_}.  You may use that variable instead,
16182 if you wish.  The @var{help-string} argument is like that of
16183 @code{AC_ARG_WITH} (@pxref{External Software}).
16185 You should format your @var{help-string} with the macro
16186 @code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
16188 See the examples suggested with the definition of @code{AC_ARG_WITH}
16189 (@pxref{External Software}) to get an idea of possible applications of
16190 @code{AC_ARG_ENABLE}.
16191 @end defmac
16193 @defmac AC_ENABLE (@var{feature}, @var{action-if-given}, @ovar{action-if-not-given})
16194 @acindex{ENABLE}
16195 This is an obsolete version of @code{AC_ARG_ENABLE} that does not
16196 support providing a help string.
16197 @end defmac
16200 @node Pretty Help Strings
16201 @section Making Your Help Strings Look Pretty
16202 @cindex Help strings
16204 Properly formatting the @samp{help strings} which are used in
16205 @code{AC_ARG_WITH} (@pxref{External Software}) and @code{AC_ARG_ENABLE}
16206 (@pxref{Package Options}) can be challenging.  Specifically, you want
16207 your own @samp{help strings} to line up in the appropriate columns of
16208 @samp{configure --help} just like the standard Autoconf @samp{help
16209 strings} do.  This is the purpose of the @code{AS_HELP_STRING} macro.
16211 @defmac AS_HELP_STRING (@var{left-hand-side}, @var{right-hand-side})
16212 @acindex{HELP_STRING}
16214 Expands into an help string that looks pretty when the user executes
16215 @samp{configure --help}.  It is typically used in @code{AC_ARG_WITH}
16216 (@pxref{External Software}) or @code{AC_ARG_ENABLE} (@pxref{Package
16217 Options}).  The following example makes this clearer.
16219 @example
16220 AC_ARG_WITH([foo],
16221   [AS_HELP_STRING([--with-foo],
16222      [use foo (default is no)])],
16223   [use_foo=$withval],
16224   [use_foo=no])
16225 @end example
16227 The second argument of @code{AS_HELP_STRING} is
16228 not a literal, and should not be double quoted.
16229 @xref{Autoconf Language}, for a more detailed explanation.
16230 Then the last few lines of @samp{configure --help} appear like
16231 this:
16233 @example
16234 --enable and --with options recognized:
16235   --with-foo              use foo (default is no)
16236 @end example
16238 The @code{AS_HELP_STRING} macro is particularly helpful when the
16239 @var{left-hand-side} and/or @var{right-hand-side} are composed of macro
16240 arguments, as shown in the following example.
16242 @example
16243 AC_DEFUN([MY_ARG_WITH],
16244   [AC_ARG_WITH([$1],
16245      [AS_HELP_STRING([--with-$1], [use $1 (default is $2)])],
16246      [use_[]$1=$withval],
16247      [use_[]$1=$2])])
16248 @end example
16249 @end defmac
16252 @node Option Checking
16253 @section Controlling Checking of @command{configure} Options
16254 @cindex Options, Package
16256 The @command{configure} script checks its command-line options against a
16257 list of known options, like @option{--help} or @option{--config-cache}.
16258 An unknown option ordinarily indicates a mistake by the user and
16259 @command{configure} halts with an error.  However, by default unknown
16260 @option{--with-@var{package}} and @option{--enable-@var{feature}}
16261 options elicit only a warning, to support configuring entire source
16262 trees.
16264 Source trees often contain multiple packages with a top-level
16265 @command{configure} script that uses the @code{AC_CONFIG_SUBDIRS} macro
16266 (@pxref{Subdirectories}).  Because the packages generally support
16267 different @option{--with-@var{package}} and
16268 @option{--enable-@var{feature}} options, the @acronym{GNU} Coding
16269 Standards say they must accept unrecognized options without halting.
16270 Even a warning message is undesirable here, so @code{AC_CONFIG_SUBDIRS}
16271 automatically disables the warnings.
16273 This default behavior may be modified in two ways.  First, the installer
16274 can invoke @command{configure} with the
16275 @option{--disable-option-checking} or
16276 @option{--enable-option-checking=fatal} options to disable these
16277 warnings or turn them into fatal errors, respectively.  Second, the
16278 maintainer can use @code{AC_DISABLE_OPTION_CHECKING}.
16280 @defmac AC_DISABLE_OPTION_CHECKING
16281 @acindex{DISABLE_OPTION_CHECKING}
16283 By default, disable warnings for unrecognized
16284 @option{--with-@var{package}} or @option{--enable-@var{feature}}
16285 options.  This is implied by @code{AC_CONFIG_SUBDIRS}.
16287 The installer can override this behavior by passing
16288 @option{--enable-option-checking} (enable warnings) or
16289 @option{--enable-option-checking=fatal} (enable errors) to
16290 @command{configure}.
16291 @end defmac
16294 @node Site Details
16295 @section Configuring Site Details
16296 @cindex Site details
16298 Some software packages require complex site-specific information.  Some
16299 examples are host names to use for certain services, company names, and
16300 email addresses to contact.  Since some configuration scripts generated
16301 by Metaconfig ask for such information interactively, people sometimes
16302 wonder how to get that information in Autoconf-generated configuration
16303 scripts, which aren't interactive.
16305 Such site configuration information should be put in a file that is
16306 edited @emph{only by users}, not by programs.  The location of the file
16307 can either be based on the @code{prefix} variable, or be a standard
16308 location such as the user's home directory.  It could even be specified
16309 by an environment variable.  The programs should examine that file at
16310 runtime, rather than at compile time.  Runtime configuration is more
16311 convenient for users and makes the configuration process simpler than
16312 getting the information while configuring.  @xref{Directory Variables, ,
16313 Variables for Installation Directories, standards, @acronym{GNU} Coding
16314 Standards}, for more information on where to put data files.
16316 @node Transforming Names
16317 @section Transforming Program Names When Installing
16318 @cindex Transforming program names
16319 @cindex Program names, transforming
16321 Autoconf supports changing the names of programs when installing them.
16322 In order to use these transformations, @file{configure.ac} must call the
16323 macro @code{AC_ARG_PROGRAM}.
16325 @defmac AC_ARG_PROGRAM
16326 @acindex{ARG_PROGRAM}
16327 @ovindex program_transform_name
16328 Place in output variable @code{program_transform_name} a sequence of
16329 @code{sed} commands for changing the names of installed programs.
16331 If any of the options described below are given to @command{configure},
16332 program names are transformed accordingly.  Otherwise, if
16333 @code{AC_CANONICAL_TARGET} has been called and a @option{--target} value
16334 is given, the target type followed by a dash is used as a prefix.
16335 Otherwise, no program name transformation is done.
16336 @end defmac
16338 @menu
16339 * Transformation Options::      @command{configure} options to transform names
16340 * Transformation Examples::     Sample uses of transforming names
16341 * Transformation Rules::        Makefile uses of transforming names
16342 @end menu
16344 @node Transformation Options
16345 @subsection Transformation Options
16347 You can specify name transformations by giving @command{configure} these
16348 command line options:
16350 @table @option
16351 @item --program-prefix=@var{prefix}
16352 prepend @var{prefix} to the names;
16354 @item --program-suffix=@var{suffix}
16355 append @var{suffix} to the names;
16357 @item --program-transform-name=@var{expression}
16358 perform @code{sed} substitution @var{expression} on the names.
16359 @end table
16361 @node Transformation Examples
16362 @subsection Transformation Examples
16364 These transformations are useful with programs that can be part of a
16365 cross-compilation development environment.  For example, a
16366 cross-assembler running on a Sun 4 configured with
16367 @option{--target=i960-vxworks} is normally installed as
16368 @file{i960-vxworks-as}, rather than @file{as}, which could be confused
16369 with a native Sun 4 assembler.
16371 You can force a program name to begin with @file{g}, if you don't want
16372 @acronym{GNU} programs installed on your system to shadow other programs with
16373 the same name.  For example, if you configure @acronym{GNU} @code{diff} with
16374 @option{--program-prefix=g}, then when you run @samp{make install} it is
16375 installed as @file{/usr/local/bin/gdiff}.
16377 As a more sophisticated example, you could use
16379 @example
16380 --program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/'
16381 @end example
16382 @noindent
16384 to prepend @samp{g} to most of the program names in a source tree,
16385 excepting those like @code{gdb} that already have one and those like
16386 @code{less} and @code{lesskey} that aren't @acronym{GNU} programs.  (That is
16387 assuming that you have a source tree containing those programs that is
16388 set up to use this feature.)
16390 One way to install multiple versions of some programs simultaneously is
16391 to append a version number to the name of one or both.  For example, if
16392 you want to keep Autoconf version 1 around for awhile, you can configure
16393 Autoconf version 2 using @option{--program-suffix=2} to install the
16394 programs as @file{/usr/local/bin/autoconf2},
16395 @file{/usr/local/bin/autoheader2}, etc.  Nevertheless, pay attention
16396 that only the binaries are renamed, therefore you'd have problems with
16397 the library files which might overlap.
16399 @node Transformation Rules
16400 @subsection Transformation Rules
16402 Here is how to use the variable @code{program_transform_name} in a
16403 @file{Makefile.in}:
16405 @example
16406 PROGRAMS = cp ls rm
16407 transform = @@program_transform_name@@
16408 install:
16409         for p in $(PROGRAMS); do \
16410           $(INSTALL_PROGRAM) $$p $(DESTDIR)$(bindir)/`echo $$p | \
16411                                               sed '$(transform)'`; \
16412         done
16414 uninstall:
16415         for p in $(PROGRAMS); do \
16416           rm -f $(DESTDIR)$(bindir)/`echo $$p | sed '$(transform)'`; \
16417         done
16418 @end example
16420 It is guaranteed that @code{program_transform_name} is never empty, and
16421 that there are no useless separators.  Therefore you may safely embed
16422 @code{program_transform_name} within a sed program using @samp{;}:
16424 @example
16425 transform = @@program_transform_name@@
16426 transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/
16427 @end example
16429 Whether to do the transformations on documentation files (Texinfo or
16430 @code{man}) is a tricky question; there seems to be no perfect answer,
16431 due to the several reasons for name transforming.  Documentation is not
16432 usually particular to a specific architecture, and Texinfo files do not
16433 conflict with system documentation.  But they might conflict with
16434 earlier versions of the same files, and @code{man} pages sometimes do
16435 conflict with system documentation.  As a compromise, it is probably
16436 best to do name transformations on @code{man} pages but not on Texinfo
16437 manuals.
16439 @node Site Defaults
16440 @section Setting Site Defaults
16441 @cindex Site defaults
16443 Autoconf-generated @command{configure} scripts allow your site to provide
16444 default values for some configuration values.  You do this by creating
16445 site- and system-wide initialization files.
16447 @evindex CONFIG_SITE
16448 If the environment variable @code{CONFIG_SITE} is set, @command{configure}
16449 uses its value as the name of a shell script to read.  Otherwise, it
16450 reads the shell script @file{@var{prefix}/share/config.site} if it exists,
16451 then @file{@var{prefix}/etc/config.site} if it exists.  Thus,
16452 settings in machine-specific files override those in machine-independent
16453 ones in case of conflict.
16455 Site files can be arbitrary shell scripts, but only certain kinds of
16456 code are really appropriate to be in them.  Because @command{configure}
16457 reads any cache file after it has read any site files, a site file can
16458 define a default cache file to be shared between all Autoconf-generated
16459 @command{configure} scripts run on that system (@pxref{Cache Files}).  If
16460 you set a default cache file in a site file, it is a good idea to also
16461 set the output variable @code{CC} in that site file, because the cache
16462 file is only valid for a particular compiler, but many systems have
16463 several available.
16465 You can examine or override the value set by a command line option to
16466 @command{configure} in a site file; options set shell variables that have
16467 the same names as the options, with any dashes turned into underscores.
16468 The exceptions are that @option{--without-} and @option{--disable-} options
16469 are like giving the corresponding @option{--with-} or @option{--enable-}
16470 option and the value @samp{no}.  Thus, @option{--cache-file=localcache}
16471 sets the variable @code{cache_file} to the value @samp{localcache};
16472 @option{--enable-warnings=no} or @option{--disable-warnings} sets the variable
16473 @code{enable_warnings} to the value @samp{no}; @option{--prefix=/usr} sets the
16474 variable @code{prefix} to the value @samp{/usr}; etc.
16476 Site files are also good places to set default values for other output
16477 variables, such as @code{CFLAGS}, if you need to give them non-default
16478 values: anything you would normally do, repetitively, on the command
16479 line.  If you use non-default values for @var{prefix} or
16480 @var{exec_prefix} (wherever you locate the site file), you can set them
16481 in the site file if you specify it with the @code{CONFIG_SITE}
16482 environment variable.
16484 You can set some cache values in the site file itself.  Doing this is
16485 useful if you are cross-compiling, where it is impossible to check features
16486 that require running a test program.  You could ``prime the cache'' by
16487 setting those values correctly for that system in
16488 @file{@var{prefix}/etc/config.site}.  To find out the names of the cache
16489 variables you need to set, look for shell variables with @samp{_cv_} in
16490 their names in the affected @command{configure} scripts, or in the Autoconf
16491 M4 source code for those macros.
16493 The cache file is careful to not override any variables set in the site
16494 files.  Similarly, you should not override command-line options in the
16495 site files.  Your code should check that variables such as @code{prefix}
16496 and @code{cache_file} have their default values (as set near the top of
16497 @command{configure}) before changing them.
16499 Here is a sample file @file{/usr/share/local/gnu/share/config.site}.  The
16500 command @samp{configure --prefix=/usr/share/local/gnu} would read this
16501 file (if @code{CONFIG_SITE} is not set to a different file).
16503 @example
16504 # config.site for configure
16506 # Change some defaults.
16507 test "$prefix" = NONE && prefix=/usr/share/local/gnu
16508 test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu
16509 test "$sharedstatedir" = '$prefix/com' && sharedstatedir=/var
16510 test "$localstatedir" = '$prefix/var' && localstatedir=/var
16512 # Give Autoconf 2.x generated configure scripts a shared default
16513 # cache file for feature test results, architecture-specific.
16514 if test "$cache_file" = /dev/null; then
16515   cache_file="$prefix/var/config.cache"
16516   # A cache file is only valid for one C compiler.
16517   CC=gcc
16519 @end example
16522 @c ============================================== Running configure Scripts.
16524 @node Running configure Scripts
16525 @chapter Running @command{configure} Scripts
16526 @cindex @command{configure}
16528 Below are instructions on how to configure a package that uses a
16529 @command{configure} script, suitable for inclusion as an @file{INSTALL}
16530 file in the package.  A plain-text version of @file{INSTALL} which you
16531 may use comes with Autoconf.
16533 @menu
16534 * Basic Installation::          Instructions for typical cases
16535 * Compilers and Options::       Selecting compilers and optimization
16536 * Multiple Architectures::      Compiling for multiple architectures at once
16537 * Installation Names::          Installing in different directories
16538 * Optional Features::           Selecting optional features
16539 * System Type::                 Specifying the system type
16540 * Sharing Defaults::            Setting site-wide defaults for @command{configure}
16541 * Defining Variables::          Specifying the compiler etc.
16542 * configure Invocation::        Changing how @command{configure} runs
16543 @end menu
16545 @set autoconf
16546 @include install.texi
16549 @c ============================================== config.status Invocation
16551 @node config.status Invocation
16552 @chapter config.status Invocation
16553 @cindex @command{config.status}
16555 The @command{configure} script creates a file named @file{config.status},
16556 which actually configures, @dfn{instantiates}, the template files.  It
16557 also records the configuration options that were specified when the
16558 package was last configured in case reconfiguring is needed.
16560 Synopsis:
16561 @example
16562 ./config.status @var{option}@dots{} [@var{file}@dots{}]
16563 @end example
16565 It configures the @var{files}; if none are specified, all the templates
16566 are instantiated.  The files must be specified without their
16567 dependencies, as in
16569 @example
16570 ./config.status foobar
16571 @end example
16573 @noindent
16576 @example
16577 ./config.status foobar:foo.in:bar.in
16578 @end example
16580 The supported options are:
16582 @table @option
16583 @item --help
16584 @itemx -h
16585 Print a summary of the command line options, the list of the template
16586 files, and exit.
16588 @item --version
16589 @itemx -V
16590 Print the version number of Autoconf and the configuration settings,
16591 and exit.
16593 @item --silent
16594 @itemx --quiet
16595 @itemx -q
16596 Do not print progress messages.
16598 @item --debug
16599 @itemx -d
16600 Don't remove the temporary files.
16602 @item --file=@var{file}[:@var{template}]
16603 Require that @var{file} be instantiated as if
16604 @samp{AC_CONFIG_FILES(@var{file}:@var{template})} was used.  Both
16605 @var{file} and @var{template} may be @samp{-} in which case the standard
16606 output and/or standard input, respectively, is used.  If a
16607 @var{template} file name is relative, it is first looked for in the build
16608 tree, and then in the source tree.  @xref{Configuration Actions}, for
16609 more details.
16611 This option and the following ones provide one way for separately
16612 distributed packages to share the values computed by @command{configure}.
16613 Doing so can be useful if some of the packages need a superset of the
16614 features that one of them, perhaps a common library, does.  These
16615 options allow a @file{config.status} file to create files other than the
16616 ones that its @file{configure.ac} specifies, so it can be used for a
16617 different package.
16619 @item --header=@var{file}[:@var{template}]
16620 Same as @option{--file} above, but with @samp{AC_CONFIG_HEADERS}.
16622 @item --recheck
16623 Ask @file{config.status} to update itself and exit (no instantiation).
16624 This option is useful if you change @command{configure}, so that the
16625 results of some tests might be different from the previous run.  The
16626 @option{--recheck} option reruns @command{configure} with the same arguments
16627 you used before, plus the @option{--no-create} option, which prevents
16628 @command{configure} from running @file{config.status} and creating
16629 @file{Makefile} and other files, and the @option{--no-recursion} option,
16630 which prevents @command{configure} from running other @command{configure}
16631 scripts in subdirectories.  (This is so other Make rules can
16632 run @file{config.status} when it changes; @pxref{Automatic Remaking},
16633 for an example).
16634 @end table
16636 @file{config.status} checks several optional environment variables that
16637 can alter its behavior:
16639 @defvar CONFIG_SHELL
16640 @evindex CONFIG_SHELL
16641 The shell with which to run @command{configure} for the @option{--recheck}
16642 option.  It must be Bourne-compatible.  The default is a shell that
16643 supports @code{LINENO} if available, and @file{/bin/sh} otherwise.
16644 Invoking @command{configure} by hand bypasses this setting, so you may
16645 need to use a command like @samp{CONFIG_SHELL=/bin/bash /bin/bash ./configure}
16646 to insure that the same shell is used everywhere.  The absolute name of the
16647 shell should be passed.
16648 @end defvar
16650 @defvar CONFIG_STATUS
16651 @evindex CONFIG_STATUS
16652 The file name to use for the shell script that records the
16653 configuration.  The default is @file{./config.status}.  This variable is
16654 useful when one package uses parts of another and the @command{configure}
16655 scripts shouldn't be merged because they are maintained separately.
16656 @end defvar
16658 You can use @file{./config.status} in your makefiles.  For example, in
16659 the dependencies given above (@pxref{Automatic Remaking}),
16660 @file{config.status} is run twice when @file{configure.ac} has changed.
16661 If that bothers you, you can make each run only regenerate the files for
16662 that rule:
16663 @example
16664 @group
16665 config.h: stamp-h
16666 stamp-h: config.h.in config.status
16667         ./config.status config.h
16668         echo > stamp-h
16670 Makefile: Makefile.in config.status
16671         ./config.status Makefile
16672 @end group
16673 @end example
16675 The calling convention of @file{config.status} has changed; see
16676 @ref{Obsolete config.status Use}, for details.
16679 @c =================================================== Obsolete Constructs
16681 @node Obsolete Constructs
16682 @chapter Obsolete Constructs
16683 @cindex Obsolete constructs
16685 Autoconf changes, and throughout the years some constructs have been
16686 obsoleted.  Most of the changes involve the macros, but in some cases
16687 the tools themselves, or even some concepts, are now considered
16688 obsolete.
16690 You may completely skip this chapter if you are new to Autoconf.  Its
16691 intention is mainly to help maintainers updating their packages by
16692 understanding how to move to more modern constructs.
16694 @menu
16695 * Obsolete config.status Use::  Obsolete convention for @command{config.status}
16696 * acconfig Header::             Additional entries in @file{config.h.in}
16697 * autoupdate Invocation::       Automatic update of @file{configure.ac}
16698 * Obsolete Macros::             Backward compatibility macros
16699 * Autoconf 1::                  Tips for upgrading your files
16700 * Autoconf 2.13::               Some fresher tips
16701 @end menu
16703 @node Obsolete config.status Use
16704 @section Obsolete @file{config.status} Invocation
16706 @file{config.status} now supports arguments to specify the files to
16707 instantiate; see @ref{config.status Invocation}, for more details.
16708 Before, environment variables had to be used.
16710 @defvar CONFIG_COMMANDS
16711 @evindex CONFIG_COMMANDS
16712 The tags of the commands to execute.  The default is the arguments given
16713 to @code{AC_OUTPUT} and @code{AC_CONFIG_COMMANDS} in
16714 @file{configure.ac}.
16715 @end defvar
16717 @defvar CONFIG_FILES
16718 @evindex CONFIG_FILES
16719 The files in which to perform @samp{@@@var{variable}@@} substitutions.
16720 The default is the arguments given to @code{AC_OUTPUT} and
16721 @code{AC_CONFIG_FILES} in @file{configure.ac}.
16722 @end defvar
16724 @defvar CONFIG_HEADERS
16725 @evindex CONFIG_HEADERS
16726 The files in which to substitute C @code{#define} statements.  The
16727 default is the arguments given to @code{AC_CONFIG_HEADERS}; if that
16728 macro was not called, @file{config.status} ignores this variable.
16729 @end defvar
16731 @defvar CONFIG_LINKS
16732 @evindex CONFIG_LINKS
16733 The symbolic links to establish.  The default is the arguments given to
16734 @code{AC_CONFIG_LINKS}; if that macro was not called,
16735 @file{config.status} ignores this variable.
16736 @end defvar
16738 In @ref{config.status Invocation}, using this old interface, the example
16739 would be:
16741 @example
16742 @group
16743 config.h: stamp-h
16744 stamp-h: config.h.in config.status
16745         CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_FILES= \
16746           CONFIG_HEADERS=config.h ./config.status
16747         echo > stamp-h
16749 Makefile: Makefile.in config.status
16750         CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_HEADERS= \
16751           CONFIG_FILES=Makefile ./config.status
16752 @end group
16753 @end example
16755 @noindent
16756 (If @file{configure.ac} does not call @code{AC_CONFIG_HEADERS}, there is
16757 no need to set @code{CONFIG_HEADERS} in the @code{make} rules.  Equally
16758 for @code{CONFIG_COMMANDS}, etc.)
16761 @node acconfig Header
16762 @section @file{acconfig.h}
16764 @cindex @file{acconfig.h}
16765 @cindex @file{config.h.top}
16766 @cindex @file{config.h.bot}
16768 In order to produce @file{config.h.in}, @command{autoheader} needs to
16769 build or to find templates for each symbol.  Modern releases of Autoconf
16770 use @code{AH_VERBATIM} and @code{AH_TEMPLATE} (@pxref{Autoheader
16771 Macros}), but in older releases a file, @file{acconfig.h}, contained the
16772 list of needed templates.  @command{autoheader} copied comments and
16773 @code{#define} and @code{#undef} statements from @file{acconfig.h} in
16774 the current directory, if present.  This file used to be mandatory if
16775 you @code{AC_DEFINE} any additional symbols.
16777 Modern releases of Autoconf also provide @code{AH_TOP} and
16778 @code{AH_BOTTOM} if you need to prepend/append some information to
16779 @file{config.h.in}.  Ancient versions of Autoconf had a similar feature:
16780 if @file{./acconfig.h} contains the string @samp{@@TOP@@},
16781 @command{autoheader} copies the lines before the line containing
16782 @samp{@@TOP@@} into the top of the file that it generates.  Similarly,
16783 if @file{./acconfig.h} contains the string @samp{@@BOTTOM@@},
16784 @command{autoheader} copies the lines after that line to the end of the
16785 file it generates.  Either or both of those strings may be omitted.  An
16786 even older alternate way to produce the same effect in ancient versions
16787 of Autoconf is to create the files @file{@var{file}.top} (typically
16788 @file{config.h.top}) and/or @file{@var{file}.bot} in the current
16789 directory.  If they exist, @command{autoheader} copies them to the
16790 beginning and end, respectively, of its output.
16792 In former versions of Autoconf, the files used in preparing a software
16793 package for distribution were:
16794 @example
16795 @group
16796 configure.ac --.   .------> autoconf* -----> configure
16797                +---+
16798 [aclocal.m4] --+   `---.
16799 [acsite.m4] ---'       |
16800                        +--> [autoheader*] -> [config.h.in]
16801 [acconfig.h] ----.     |
16802                  +-----'
16803 [config.h.top] --+
16804 [config.h.bot] --'
16805 @end group
16806 @end example
16808 Using only the @code{AH_} macros, @file{configure.ac} should be
16809 self-contained, and should not depend upon @file{acconfig.h} etc.
16812 @node autoupdate Invocation
16813 @section Using @command{autoupdate} to Modernize @file{configure.ac}
16814 @cindex @command{autoupdate}
16816 The @command{autoupdate} program updates a @file{configure.ac} file that
16817 calls Autoconf macros by their old names to use the current macro names.
16818 In version 2 of Autoconf, most of the macros were renamed to use a more
16819 uniform and descriptive naming scheme.  @xref{Macro Names}, for a
16820 description of the new scheme.  Although the old names still work
16821 (@pxref{Obsolete Macros}, for a list of the old macros and the corresponding
16822 new names), you can make your @file{configure.ac} files more readable
16823 and make it easier to use the current Autoconf documentation if you
16824 update them to use the new macro names.
16826 @evindex SIMPLE_BACKUP_SUFFIX
16827 If given no arguments, @command{autoupdate} updates @file{configure.ac},
16828 backing up the original version with the suffix @file{~} (or the value
16829 of the environment variable @code{SIMPLE_BACKUP_SUFFIX}, if that is
16830 set).  If you give @command{autoupdate} an argument, it reads that file
16831 instead of @file{configure.ac} and writes the updated file to the
16832 standard output.
16834 @noindent
16835 @command{autoupdate} accepts the following options:
16837 @table @option
16838 @item --help
16839 @itemx -h
16840 Print a summary of the command line options and exit.
16842 @item --version
16843 @itemx -V
16844 Print the version number of Autoconf and exit.
16846 @item --verbose
16847 @itemx -v
16848 Report processing steps.
16850 @item --debug
16851 @itemx -d
16852 Don't remove the temporary files.
16854 @item --force
16855 @itemx -f
16856 Force the update even if the file has not changed.  Disregard the cache.
16858 @item --include=@var{dir}
16859 @itemx -I @var{dir}
16860 Also look for input files in @var{dir}.  Multiple invocations accumulate.
16861 Directories are browsed from last to first.
16862 @end table
16864 @node Obsolete Macros
16865 @section Obsolete Macros
16867 Several macros are obsoleted in Autoconf, for various reasons (typically
16868 they failed to quote properly, couldn't be extended for more recent
16869 issues, etc.).  They are still supported, but deprecated: their use
16870 should be avoided.
16872 During the jump from Autoconf version 1 to version 2, most of the
16873 macros were renamed to use a more uniform and descriptive naming scheme,
16874 but their signature did not change.  @xref{Macro Names}, for a
16875 description of the new naming scheme.  Below, if there is just the mapping
16876 from old names to new names for these macros, the reader is invited to
16877 refer to the definition of the new macro for the signature and the
16878 description.
16880 @defmac AC_ALLOCA
16881 @acindex{ALLOCA}
16882 @code{AC_FUNC_ALLOCA}
16883 @end defmac
16885 @defmac AC_ARG_ARRAY
16886 @acindex{ARG_ARRAY}
16887 removed because of limited usefulness
16888 @end defmac
16890 @defmac AC_C_CROSS
16891 @acindex{C_CROSS}
16892 This macro is obsolete; it does nothing.
16893 @end defmac
16895 @defmac AC_C_LONG_DOUBLE
16896 @acindex{C_LONG_DOUBLE}
16897 @cvindex HAVE_LONG_DOUBLE
16898 If the C compiler supports a working @code{long double} type with more
16899 range or precision than the @code{double} type, define
16900 @code{HAVE_LONG_DOUBLE}.
16902 You should use @code{AC_TYPE_LONG_DOUBLE} or
16903 @code{AC_TYPE_LONG_DOUBLE_WIDER} instead.  @xref{Particular Types}.
16904 @end defmac
16906 @defmac AC_CANONICAL_SYSTEM
16907 @acindex{CANONICAL_SYSTEM}
16908 Determine the system type and set output variables to the names of the
16909 canonical system types.  @xref{Canonicalizing}, for details about the
16910 variables this macro sets.
16912 The user is encouraged to use either @code{AC_CANONICAL_BUILD}, or
16913 @code{AC_CANONICAL_HOST}, or @code{AC_CANONICAL_TARGET}, depending on
16914 the needs.  Using @code{AC_CANONICAL_TARGET} is enough to run the two
16915 other macros.
16916 @end defmac
16918 @defmac AC_CHAR_UNSIGNED
16919 @acindex{CHAR_UNSIGNED}
16920 @code{AC_C_CHAR_UNSIGNED}
16921 @end defmac
16923 @defmac AC_CHECK_TYPE (@var{type}, @var{default})
16924 @acindex{CHECK_TYPE}
16925 Autoconf, up to 2.13, used to provide this version of
16926 @code{AC_CHECK_TYPE}, deprecated because of its flaws.  First, although
16927 it is a member of the @code{CHECK} clan, it does
16928 more than just checking.  Secondly, missing types are defined
16929 using @code{#define}, not @code{typedef}, and this can lead to
16930 problems in the case of pointer types.
16932 This use of @code{AC_CHECK_TYPE} is obsolete and discouraged; see
16933 @ref{Generic Types}, for the description of the current macro.
16935 If the type @var{type} is not defined, define it to be the C (or C++)
16936 builtin type @var{default}, e.g., @samp{short int} or @samp{unsigned int}.
16938 This macro is equivalent to:
16940 @example
16941 AC_CHECK_TYPE([@var{type}], [],
16942   [AC_DEFINE_UNQUOTED([@var{type}], [@var{default}],
16943      [Define to `@var{default}'
16944       if <sys/types.h> does not define.])])
16945 @end example
16947 In order to keep backward compatibility, the two versions of
16948 @code{AC_CHECK_TYPE} are implemented, selected using these heuristics:
16950 @enumerate
16951 @item
16952 If there are three or four arguments, the modern version is used.
16954 @item
16955 If the second argument appears to be a C or C++ type, then the
16956 obsolete version is used.  This happens if the argument is a C or C++
16957 @emph{builtin} type or a C identifier ending in @samp{_t}, optionally
16958 followed by one of @samp{[(* } and then by a string of zero or more
16959 characters taken from the set @samp{[]()* _a-zA-Z0-9}.
16961 @item
16962 If the second argument is spelled with the alphabet of valid C and C++
16963 types, the user is warned and the modern version is used.
16965 @item
16966 Otherwise, the modern version is used.
16967 @end enumerate
16969 @noindent
16970 You are encouraged either to use a valid builtin type, or to use the
16971 equivalent modern code (see above), or better yet, to use
16972 @code{AC_CHECK_TYPES} together with
16974 @example
16975 #ifndef HAVE_LOFF_T
16976 typedef loff_t off_t;
16977 #endif
16978 @end example
16979 @end defmac
16980 @c end of AC_CHECK_TYPE
16982 @defmac AC_CHECKING (@var{feature-description})
16983 @acindex{CHECKING}
16984 Same as @samp{AC_MSG_NOTICE([checking @var{feature-description}@dots{}]}.
16985 @end defmac
16987 @defmac AC_COMPILE_CHECK (@var{echo-text}, @var{includes}, @var{function-body}, @var{action-if-true}, @ovar{action-if-false})
16988 @acindex{COMPILE_CHECK}
16989 This is an obsolete version of @code{AC_TRY_COMPILE} itself replaced by
16990 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}), with the
16991 addition that it prints @samp{checking for @var{echo-text}} to the
16992 standard output first, if @var{echo-text} is non-empty.  Use
16993 @code{AC_MSG_CHECKING} and @code{AC_MSG_RESULT} instead to print
16994 messages (@pxref{Printing Messages}).
16995 @end defmac
16997 @defmac AC_CONST
16998 @acindex{CONST}
16999 @code{AC_C_CONST}
17000 @end defmac
17002 @defmac AC_CROSS_CHECK
17003 @acindex{CROSS_CHECK}
17004 Same as @code{AC_C_CROSS}, which is obsolete too, and does nothing
17005 @code{:-)}.
17006 @end defmac
17008 @defmac AC_CYGWIN
17009 @acindex{CYGWIN}
17010 Check for the Cygwin environment in which case the shell variable
17011 @code{CYGWIN} is set to @samp{yes}.  Don't use this macro, the dignified
17012 means to check the nature of the host is using
17013 @code{AC_CANONICAL_HOST}.  As a matter of fact this macro is defined as:
17015 @example
17016 AC_REQUIRE([AC_CANONICAL_HOST])[]dnl
17017 case $host_os in
17018   *cygwin* ) CYGWIN=yes;;
17019          * ) CYGWIN=no;;
17020 esac
17021 @end example
17023 Beware that the variable @code{CYGWIN} has a special meaning when
17024 running Cygwin, and should not be changed.  That's yet another reason
17025 not to use this macro.
17026 @end defmac
17028 @defmac AC_DECL_SYS_SIGLIST
17029 @acindex{DECL_SYS_SIGLIST}
17030 @cvindex SYS_SIGLIST_DECLARED
17031 Same as:
17033 @example
17034 AC_CHECK_DECLS([sys_siglist], [], [],
17035 [#include <signal.h>
17036 /* NetBSD declares sys_siglist in unistd.h.  */
17037 #ifdef HAVE_UNISTD_H
17038 # include <unistd.h>
17039 #endif
17041 @end example
17042 @end defmac
17044 @defmac AC_DECL_YYTEXT
17045 @acindex{DECL_YYTEXT}
17046 Does nothing, now integrated in @code{AC_PROG_LEX}.
17047 @end defmac
17049 @defmac AC_DIR_HEADER
17050 @acindex{DIR_HEADER}
17051 @cvindex DIRENT
17052 @cvindex SYSNDIR
17053 @cvindex SYSDIR
17054 @cvindex NDIR
17055 Like calling @code{AC_FUNC_CLOSEDIR_VOID} and@code{AC_HEADER_DIRENT},
17056 but defines a different set of C preprocessor macros to indicate which
17057 header file is found:
17059 @multitable {@file{sys/ndir.h}} {Old Symbol} {@code{HAVE_SYS_NDIR_H}}
17060 @item Header            @tab Old Symbol     @tab New Symbol
17061 @item @file{dirent.h}   @tab @code{DIRENT}  @tab @code{HAVE_DIRENT_H}
17062 @item @file{sys/ndir.h} @tab @code{SYSNDIR} @tab @code{HAVE_SYS_NDIR_H}
17063 @item @file{sys/dir.h}  @tab @code{SYSDIR}  @tab @code{HAVE_SYS_DIR_H}
17064 @item @file{ndir.h}     @tab @code{NDIR}    @tab @code{HAVE_NDIR_H}
17065 @end multitable
17066 @end defmac
17068 @defmac AC_DYNIX_SEQ
17069 @acindex{DYNIX_SEQ}
17070 If on DYNIX/ptx, add @option{-lseq} to output variable
17071 @code{LIBS}.  This macro used to be defined as
17073 @example
17074 AC_CHECK_LIB([seq], [getmntent], [LIBS="-lseq $LIBS"])
17075 @end example
17077 @noindent
17078 now it is just @code{AC_FUNC_GETMNTENT}.
17079 @end defmac
17081 @defmac AC_EXEEXT
17082 @acindex{EXEEXT}
17083 @ovindex EXEEXT
17084 Defined the output variable @code{EXEEXT} based on the output of the
17085 compiler, which is now done automatically.  Typically set to empty
17086 string if Posix and @samp{.exe} if a @acronym{DOS} variant.
17087 @end defmac
17089 @defmac AC_EMXOS2
17090 @acindex{EMXOS2}
17091 Similar to @code{AC_CYGWIN} but checks for the EMX environment on OS/2
17092 and sets @code{EMXOS2}.
17093 @end defmac
17095 @defmac AC_ERROR
17096 @acindex{ERROR}
17097 @code{AC_MSG_ERROR}
17098 @end defmac
17100 @defmac AC_FIND_X
17101 @acindex{FIND_X}
17102 @code{AC_PATH_X}
17103 @end defmac
17105 @defmac AC_FIND_XTRA
17106 @acindex{FIND_XTRA}
17107 @code{AC_PATH_XTRA}
17108 @end defmac
17110 @defmac AC_FOREACH
17111 @acindex{FOREACH}
17112 @code{m4_foreach_w}
17113 @end defmac
17115 @defmac AC_FUNC_CHECK
17116 @acindex{FUNC_CHECK}
17117 @code{AC_CHECK_FUNC}
17118 @end defmac
17120 @defmac AC_FUNC_SETVBUF_REVERSED
17121 @acindex{FUNC_SETVBUF_REVERSED}
17122 @cvindex SETVBUF_REVERSED
17123 @c @fuindex setvbuf
17124 @prindex @code{setvbuf}
17125 Do nothing.  Formerly, this macro checked whether @code{setvbuf} takes
17126 the buffering type as its second argument and the buffer pointer as the
17127 third, instead of the other way around, and defined
17128 @code{SETVBUF_REVERSED}.  However, the last systems to have the problem
17129 were those based on SVR2, which became obsolete in 1987, and the macro
17130 is no longer needed.
17131 @end defmac
17133 @defmac AC_FUNC_WAIT3
17134 @acindex{FUNC_WAIT3}
17135 @cvindex HAVE_WAIT3
17136 If @code{wait3} is found and fills in the contents of its third argument
17137 (a @samp{struct rusage *}), which @acronym{HP-UX} does not do, define
17138 @code{HAVE_WAIT3}.
17140 These days portable programs should use @code{waitpid}, not
17141 @code{wait3}, as @code{wait3} has been removed from Posix.
17142 @end defmac
17144 @defmac AC_GCC_TRADITIONAL
17145 @acindex{GCC_TRADITIONAL}
17146 @code{AC_PROG_GCC_TRADITIONAL}
17147 @end defmac
17149 @defmac AC_GETGROUPS_T
17150 @acindex{GETGROUPS_T}
17151 @code{AC_TYPE_GETGROUPS}
17152 @end defmac
17154 @defmac AC_GETLOADAVG
17155 @acindex{GETLOADAVG}
17156 @code{AC_FUNC_GETLOADAVG}
17157 @end defmac
17159 @defmac AC_HAVE_FUNCS
17160 @acindex{HAVE_FUNCS}
17161 @code{AC_CHECK_FUNCS}
17162 @end defmac
17164 @defmac AC_HAVE_HEADERS
17165 @acindex{HAVE_HEADERS}
17166 @code{AC_CHECK_HEADERS}
17167 @end defmac
17169 @defmac AC_HAVE_LIBRARY (@var{library}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
17170 @acindex{HAVE_LIBRARY}
17171 This macro is equivalent to calling @code{AC_CHECK_LIB} with a
17172 @var{function} argument of @code{main}.  In addition, @var{library} can
17173 be written as any of @samp{foo}, @option{-lfoo}, or @samp{libfoo.a}.  In
17174 all of those cases, the compiler is passed @option{-lfoo}.  However,
17175 @var{library} cannot be a shell variable; it must be a literal name.
17176 @end defmac
17178 @defmac AC_HAVE_POUNDBANG
17179 @acindex{HAVE_POUNDBANG}
17180 @code{AC_SYS_INTERPRETER} (different calling convention)
17181 @end defmac
17183 @defmac AC_HEADER_CHECK
17184 @acindex{HEADER_CHECK}
17185 @code{AC_CHECK_HEADER}
17186 @end defmac
17188 @defmac AC_HEADER_EGREP
17189 @acindex{HEADER_EGREP}
17190 @code{AC_EGREP_HEADER}
17191 @end defmac
17193 @defmac AC_HELP_STRING
17194 @acindex{HELP_STRING}
17195 @code{AS_HELP_STRING}
17196 @end defmac
17198 @defmac AC_INIT (@var{unique-file-in-source-dir})
17199 @acindex{INIT}
17200 Formerly @code{AC_INIT} used to have a single argument, and was
17201 equivalent to:
17203 @example
17204 AC_INIT
17205 AC_CONFIG_SRCDIR(@var{unique-file-in-source-dir})
17206 @end example
17207 @end defmac
17209 @defmac AC_INLINE
17210 @acindex{INLINE}
17211 @code{AC_C_INLINE}
17212 @end defmac
17214 @defmac AC_INT_16_BITS
17215 @acindex{INT_16_BITS}
17216 @cvindex INT_16_BITS
17217 If the C type @code{int} is 16 bits wide, define @code{INT_16_BITS}.
17218 Use @samp{AC_CHECK_SIZEOF(int)} instead.
17219 @end defmac
17221 @defmac AC_IRIX_SUN
17222 @acindex{IRIX_SUN}
17223 If on @sc{irix} (Silicon Graphics Unix), add @option{-lsun} to output
17224 @code{LIBS}.  If you were using it to get @code{getmntent}, use
17225 @code{AC_FUNC_GETMNTENT} instead.  If you used it for the NIS versions
17226 of the password and group functions, use @samp{AC_CHECK_LIB(sun,
17227 getpwnam)}.  Up to Autoconf 2.13, it used to be
17229 @example
17230 AC_CHECK_LIB([sun], [getmntent], [LIBS="-lsun $LIBS"])
17231 @end example
17233 @noindent
17234 now it is defined as
17236 @example
17237 AC_FUNC_GETMNTENT
17238 AC_CHECK_LIB([sun], [getpwnam])
17239 @end example
17240 @end defmac
17242 @defmac AC_LANG_C
17243 @acindex{LANG_C}
17244 Same as @samp{AC_LANG([C])}.
17245 @end defmac
17247 @defmac AC_LANG_CPLUSPLUS
17248 @acindex{LANG_CPLUSPLUS}
17249 Same as @samp{AC_LANG([C++])}.
17250 @end defmac
17252 @defmac AC_LANG_FORTRAN77
17253 @acindex{LANG_FORTRAN77}
17254 Same as @samp{AC_LANG([Fortran 77])}.
17255 @end defmac
17257 @defmac AC_LANG_RESTORE
17258 @acindex{LANG_RESTORE}
17259 Select the @var{language} that is saved on the top of the stack, as set
17260 by @code{AC_LANG_SAVE}, remove it from the stack, and call
17261 @code{AC_LANG(@var{language})}.
17262 @end defmac
17264 @defmac AC_LANG_SAVE
17265 @acindex{LANG_SAVE}
17266 Remember the current language (as set by @code{AC_LANG}) on a stack.
17267 The current language does not change.  @code{AC_LANG_PUSH} is preferred.
17268 @end defmac
17270 @defmac AC_LINK_FILES (@var{source}@dots{}, @var{dest}@dots{})
17271 @acindex{LINK_FILES}
17272 This is an obsolete version of @code{AC_CONFIG_LINKS}.  An updated
17273 version of:
17275 @example
17276 AC_LINK_FILES(config/$machine.h config/$obj_format.h,
17277               host.h            object.h)
17278 @end example
17280 @noindent
17283 @example
17284 AC_CONFIG_LINKS([host.h:config/$machine.h
17285                 object.h:config/$obj_format.h])
17286 @end example
17287 @end defmac
17289 @defmac AC_LN_S
17290 @acindex{LN_S}
17291 @code{AC_PROG_LN_S}
17292 @end defmac
17294 @defmac AC_LONG_64_BITS
17295 @acindex{LONG_64_BITS}
17296 @cvindex LONG_64_BITS
17297 Define @code{LONG_64_BITS} if the C type @code{long int} is 64 bits wide.
17298 Use the generic macro @samp{AC_CHECK_SIZEOF([long int])} instead.
17299 @end defmac
17301 @defmac AC_LONG_DOUBLE
17302 @acindex{LONG_DOUBLE}
17303 If the C compiler supports a working @code{long double} type with more
17304 range or precision than the @code{double} type, define
17305 @code{HAVE_LONG_DOUBLE}.
17307 You should use @code{AC_TYPE_LONG_DOUBLE} or
17308 @code{AC_TYPE_LONG_DOUBLE_WIDER} instead.  @xref{Particular Types}.
17309 @end defmac
17311 @defmac AC_LONG_FILE_NAMES
17312 @acindex{LONG_FILE_NAMES}
17313 @code{AC_SYS_LONG_FILE_NAMES}
17314 @end defmac
17316 @defmac AC_MAJOR_HEADER
17317 @acindex{MAJOR_HEADER}
17318 @code{AC_HEADER_MAJOR}
17319 @end defmac
17321 @defmac AC_MEMORY_H
17322 @acindex{MEMORY_H}
17323 @cvindex NEED_MEMORY_H
17324 Used to define @code{NEED_MEMORY_H} if the @code{mem} functions were
17325 defined in @file{memory.h}.  Today it is equivalent to
17326 @samp{AC_CHECK_HEADERS([memory.h])}.  Adjust your code to depend upon
17327 @code{HAVE_MEMORY_H}, not @code{NEED_MEMORY_H}; see @ref{Standard
17328 Symbols}.
17329 @end defmac
17331 @defmac AC_MINGW32
17332 @acindex{MINGW32}
17333 Similar to @code{AC_CYGWIN} but checks for the MinGW compiler
17334 environment and sets @code{MINGW32}.
17335 @end defmac
17337 @defmac AC_MINUS_C_MINUS_O
17338 @acindex{MINUS_C_MINUS_O}
17339 @code{AC_PROG_CC_C_O}
17340 @end defmac
17342 @defmac AC_MMAP
17343 @acindex{MMAP}
17344 @code{AC_FUNC_MMAP}
17345 @end defmac
17347 @defmac AC_MODE_T
17348 @acindex{MODE_T}
17349 @code{AC_TYPE_MODE_T}
17350 @end defmac
17352 @defmac AC_OBJEXT
17353 @acindex{OBJEXT}
17354 @ovindex OBJEXT
17355 Defined the output variable @code{OBJEXT} based on the output of the
17356 compiler, after .c files have been excluded.  Typically set to @samp{o}
17357 if Posix, @samp{obj} if a @acronym{DOS} variant.
17358 Now the compiler checking macros handle
17359 this automatically.
17360 @end defmac
17362 @defmac AC_OBSOLETE (@var{this-macro-name}, @ovar{suggestion})
17363 @acindex{OBSOLETE}
17364 Make M4 print a message to the standard error output warning that
17365 @var{this-macro-name} is obsolete, and giving the file and line number
17366 where it was called.  @var{this-macro-name} should be the name of the
17367 macro that is calling @code{AC_OBSOLETE}.  If @var{suggestion} is given,
17368 it is printed at the end of the warning message; for example, it can be
17369 a suggestion for what to use instead of @var{this-macro-name}.
17371 For instance
17373 @example
17374 AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl
17375 @end example
17377 You are encouraged to use @code{AU_DEFUN} instead, since it gives better
17378 services to the user.
17379 @end defmac
17381 @defmac AC_OFF_T
17382 @acindex{OFF_T}
17383 @code{AC_TYPE_OFF_T}
17384 @end defmac
17386 @defmac AC_OUTPUT (@ovar{file}@dots{}, @ovar{extra-cmds}, @ovar{init-cmds})
17387 @acindex{OUTPUT}
17388 The use of @code{AC_OUTPUT} with argument is deprecated.  This obsoleted
17389 interface is equivalent to:
17391 @example
17392 @group
17393 AC_CONFIG_FILES(@var{file}@dots{})
17394 AC_CONFIG_COMMANDS([default],
17395                    @var{extra-cmds}, @var{init-cmds})
17396 AC_OUTPUT
17397 @end group
17398 @end example
17399 @end defmac
17401 @defmac AC_OUTPUT_COMMANDS (@var{extra-cmds}, @ovar{init-cmds})
17402 @acindex{OUTPUT_COMMANDS}
17403 Specify additional shell commands to run at the end of
17404 @file{config.status}, and shell commands to initialize any variables
17405 from @command{configure}.  This macro may be called multiple times.  It is
17406 obsolete, replaced by @code{AC_CONFIG_COMMANDS}.
17408 Here is an unrealistic example:
17410 @example
17411 fubar=27
17412 AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.],
17413                    [fubar=$fubar])
17414 AC_OUTPUT_COMMANDS([echo this is another, extra, bit],
17415                    [echo init bit])
17416 @end example
17418 Aside from the fact that @code{AC_CONFIG_COMMANDS} requires an
17419 additional key, an important difference is that
17420 @code{AC_OUTPUT_COMMANDS} is quoting its arguments twice, unlike
17421 @code{AC_CONFIG_COMMANDS}.  This means that @code{AC_CONFIG_COMMANDS}
17422 can safely be given macro calls as arguments:
17424 @example
17425 AC_CONFIG_COMMANDS(foo, [my_FOO()])
17426 @end example
17428 @noindent
17429 Conversely, where one level of quoting was enough for literal strings
17430 with @code{AC_OUTPUT_COMMANDS}, you need two with
17431 @code{AC_CONFIG_COMMANDS}.  The following lines are equivalent:
17433 @example
17434 @group
17435 AC_OUTPUT_COMMANDS([echo "Square brackets: []"])
17436 AC_CONFIG_COMMANDS([default], [[echo "Square brackets: []"]])
17437 @end group
17438 @end example
17439 @end defmac
17441 @defmac AC_PID_T
17442 @acindex{PID_T}
17443 @code{AC_TYPE_PID_T}
17444 @end defmac
17446 @defmac AC_PREFIX
17447 @acindex{PREFIX}
17448 @code{AC_PREFIX_PROGRAM}
17449 @end defmac
17451 @defmac AC_PROGRAMS_CHECK
17452 @acindex{PROGRAMS_CHECK}
17453 @code{AC_CHECK_PROGS}
17454 @end defmac
17456 @defmac AC_PROGRAMS_PATH
17457 @acindex{PROGRAMS_PATH}
17458 @code{AC_PATH_PROGS}
17459 @end defmac
17461 @defmac AC_PROGRAM_CHECK
17462 @acindex{PROGRAM_CHECK}
17463 @code{AC_CHECK_PROG}
17464 @end defmac
17466 @defmac AC_PROGRAM_EGREP
17467 @acindex{PROGRAM_EGREP}
17468 @code{AC_EGREP_CPP}
17469 @end defmac
17471 @defmac AC_PROGRAM_PATH
17472 @acindex{PROGRAM_PATH}
17473 @code{AC_PATH_PROG}
17474 @end defmac
17476 @defmac AC_REMOTE_TAPE
17477 @acindex{REMOTE_TAPE}
17478 removed because of limited usefulness
17479 @end defmac
17481 @defmac AC_RESTARTABLE_SYSCALLS
17482 @acindex{RESTARTABLE_SYSCALLS}
17483 @code{AC_SYS_RESTARTABLE_SYSCALLS}
17484 @end defmac
17486 @defmac AC_RETSIGTYPE
17487 @acindex{RETSIGTYPE}
17488 @code{AC_TYPE_SIGNAL}
17489 @end defmac
17491 @defmac AC_RSH
17492 @acindex{RSH}
17493 removed because of limited usefulness
17494 @end defmac
17496 @defmac AC_SCO_INTL
17497 @acindex{SCO_INTL}
17498 @ovindex LIBS
17499 If on SCO Unix, add @option{-lintl} to output variable @code{LIBS}.  This
17500 macro used to do this:
17502 @example
17503 AC_CHECK_LIB([intl], [strftime], [LIBS="-lintl $LIBS"])
17504 @end example
17506 @noindent
17507 Now it just calls @code{AC_FUNC_STRFTIME} instead.
17508 @end defmac
17510 @defmac AC_SETVBUF_REVERSED
17511 @acindex{SETVBUF_REVERSED}
17512 @code{AC_FUNC_SETVBUF_REVERSED}
17513 @end defmac
17515 @defmac AC_SET_MAKE
17516 @acindex{SET_MAKE}
17517 @code{AC_PROG_MAKE_SET}
17518 @end defmac
17520 @defmac AC_SIZEOF_TYPE
17521 @acindex{SIZEOF_TYPE}
17522 @code{AC_CHECK_SIZEOF}
17523 @end defmac
17525 @defmac AC_SIZE_T
17526 @acindex{SIZE_T}
17527 @code{AC_TYPE_SIZE_T}
17528 @end defmac
17530 @defmac AC_STAT_MACROS_BROKEN
17531 @acindex{STAT_MACROS_BROKEN}
17532 @code{AC_HEADER_STAT}
17533 @end defmac
17535 @defmac AC_STDC_HEADERS
17536 @acindex{STDC_HEADERS}
17537 @code{AC_HEADER_STDC}
17538 @end defmac
17540 @defmac AC_STRCOLL
17541 @acindex{STRCOLL}
17542 @code{AC_FUNC_STRCOLL}
17543 @end defmac
17545 @defmac AC_ST_BLKSIZE
17546 @acindex{ST_BLKSIZE}
17547 @code{AC_CHECK_MEMBERS}
17548 @end defmac
17550 @defmac AC_ST_BLOCKS
17551 @acindex{ST_BLOCKS}
17552 @code{AC_STRUCT_ST_BLOCKS}
17553 @end defmac
17555 @defmac AC_ST_RDEV
17556 @acindex{ST_RDEV}
17557 @code{AC_CHECK_MEMBERS}
17558 @end defmac
17560 @defmac AC_SYS_RESTARTABLE_SYSCALLS
17561 @acindex{SYS_RESTARTABLE_SYSCALLS}
17562 @cvindex HAVE_RESTARTABLE_SYSCALLS
17563 If the system automatically restarts a system call that is interrupted
17564 by a signal, define @code{HAVE_RESTARTABLE_SYSCALLS}.  This macro does
17565 not check whether system calls are restarted in general---it checks whether a
17566 signal handler installed with @code{signal} (but not @code{sigaction})
17567 causes system calls to be restarted.  It does not check whether system calls
17568 can be restarted when interrupted by signals that have no handler.
17570 These days portable programs should use @code{sigaction} with
17571 @code{SA_RESTART} if they want restartable system calls.  They should
17572 not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a
17573 system call is restartable is a dynamic issue, not a configuration-time
17574 issue.
17575 @end defmac
17577 @defmac AC_SYS_SIGLIST_DECLARED
17578 @acindex{SYS_SIGLIST_DECLARED}
17579 @code{AC_DECL_SYS_SIGLIST}
17580 @end defmac
17582 @defmac AC_TEST_CPP
17583 @acindex{TEST_CPP}
17584 @code{AC_TRY_CPP}, replaced by @code{AC_PREPROC_IFELSE}.
17585 @end defmac
17587 @defmac AC_TEST_PROGRAM
17588 @acindex{TEST_PROGRAM}
17589 @code{AC_TRY_RUN}, replaced by @code{AC_RUN_IFELSE}.
17590 @end defmac
17592 @defmac AC_TIMEZONE
17593 @acindex{TIMEZONE}
17594 @code{AC_STRUCT_TIMEZONE}
17595 @end defmac
17597 @defmac AC_TIME_WITH_SYS_TIME
17598 @acindex{TIME_WITH_SYS_TIME}
17599 @code{AC_HEADER_TIME}
17600 @end defmac
17602 @defmac AC_TRY_COMPILE (@var{includes}, @var{function-body}, @ovar{action-if-true}, @ovar{action-if-false})
17603 @acindex{TRY_COMPILE}
17604 Same as:
17606 @example
17607 AC_COMPILE_IFELSE(
17608   [AC_LANG_PROGRAM([[@var{includes}]],
17609      [[@var{function-body}]])],
17610   [@var{action-if-true}],
17611   [@var{action-if-false}])
17612 @end example
17614 @noindent
17615 @xref{Running the Compiler}.
17617 This macro double quotes both @var{includes} and @var{function-body}.
17619 For C and C++, @var{includes} is any @code{#include} statements needed
17620 by the code in @var{function-body} (@var{includes} is ignored if
17621 the currently selected language is Fortran or Fortran 77).  The compiler
17622 and compilation flags are determined by the current language
17623 (@pxref{Language Choice}).
17624 @end defmac
17626 @defmac AC_TRY_CPP (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
17627 @acindex{TRY_CPP}
17628 Same as:
17630 @example
17631 AC_PREPROC_IFELSE(
17632   [AC_LANG_SOURCE([[@var{input}]])],
17633   [@var{action-if-true}],
17634   [@var{action-if-false}])
17635 @end example
17637 @noindent
17638 @xref{Running the Preprocessor}.
17640 This macro double quotes the @var{input}.
17641 @end defmac
17643 @defmac AC_TRY_LINK (@var{includes}, @var{function-body}, @ovar{action-if-true}, @ovar{action-if-false})
17644 @acindex{TRY_LINK}
17645 Same as:
17647 @example
17648 AC_LINK_IFELSE(
17649   [AC_LANG_PROGRAM([[@var{includes}]],
17650      [[@var{function-body}]])],
17651   [@var{action-if-true}],
17652   [@var{action-if-false}])
17653 @end example
17655 @noindent
17656 @xref{Running the Compiler}.
17658 This macro double quotes both @var{includes} and @var{function-body}.
17660 Depending on the current language (@pxref{Language Choice}), create a
17661 test program to see whether a function whose body consists of
17662 @var{function-body} can be compiled and linked.  If the file compiles
17663 and links successfully, run shell commands @var{action-if-found},
17664 otherwise run @var{action-if-not-found}.
17666 This macro double quotes both @var{includes} and @var{function-body}.
17668 For C and C++, @var{includes} is any @code{#include} statements needed
17669 by the code in @var{function-body} (@var{includes} is ignored if
17670 the currently selected language is Fortran or Fortran 77).  The compiler
17671 and compilation flags are determined by the current language
17672 (@pxref{Language Choice}), and in addition @code{LDFLAGS} and
17673 @code{LIBS} are used for linking.
17674 @end defmac
17676 @defmac AC_TRY_LINK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found})
17677 @acindex{TRY_LINK_FUNC}
17678 This macro is equivalent to
17679 @samp{AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])],
17680 [@var{action-if-found}], [@var{action-if-not-found}])}.
17681 @end defmac
17683 @defmac AC_TRY_RUN (@var{program}, @ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-cross-compiling})
17684 @acindex{TRY_RUN}
17685 Same as:
17687 @example
17688 AC_RUN_IFELSE(
17689   [AC_LANG_SOURCE([[@var{program}]])],
17690   [@var{action-if-true}],
17691   [@var{action-if-false}],
17692   [@var{action-if-cross-compiling}])
17693 @end example
17695 @noindent
17696 @xref{Runtime}.
17697 @end defmac
17699 @defmac AC_UID_T
17700 @acindex{UID_T}
17701 @code{AC_TYPE_UID_T}
17702 @end defmac
17704 @defmac AC_UNISTD_H
17705 @acindex{UNISTD_H}
17706 Same as @samp{AC_CHECK_HEADERS([unistd.h])}.
17707 @end defmac
17709 @defmac AC_USG
17710 @acindex{USG}
17711 @cvindex USG
17712 Define @code{USG} if the @acronym{BSD} string functions are defined in
17713 @file{strings.h}.  You should no longer depend upon @code{USG}, but on
17714 @code{HAVE_STRING_H}; see @ref{Standard Symbols}.
17715 @end defmac
17717 @defmac AC_UTIME_NULL
17718 @acindex{UTIME_NULL}
17719 @code{AC_FUNC_UTIME_NULL}
17720 @end defmac
17722 @defmac AC_VALIDATE_CACHED_SYSTEM_TUPLE (@ovar{cmd})
17723 @acindex{VALIDATE_CACHED_SYSTEM_TUPLE}
17724 If the cache file is inconsistent with the current host, target and
17725 build system types, it used to execute @var{cmd} or print a default
17726 error message.  This is now handled by default.
17727 @end defmac
17729 @defmac AC_VERBOSE (@var{result-description})
17730 @acindex{VERBOSE}
17731 @code{AC_MSG_RESULT}.
17732 @end defmac
17734 @defmac AC_VFORK
17735 @acindex{VFORK}
17736 @code{AC_FUNC_VFORK}
17737 @end defmac
17739 @defmac AC_VPRINTF
17740 @acindex{VPRINTF}
17741 @code{AC_FUNC_VPRINTF}
17742 @end defmac
17744 @defmac AC_WAIT3
17745 @acindex{WAIT3}
17746 @code{AC_FUNC_WAIT3}
17747 @end defmac
17749 @defmac AC_WARN
17750 @acindex{WARN}
17751 @code{AC_MSG_WARN}
17752 @end defmac
17754 @defmac AC_WORDS_BIGENDIAN
17755 @acindex{WORDS_BIGENDIAN}
17756 @code{AC_C_BIGENDIAN}
17757 @end defmac
17759 @defmac AC_XENIX_DIR
17760 @acindex{XENIX_DIR}
17761 @ovindex LIBS
17762 This macro used to add @option{-lx} to output variable @code{LIBS} if on
17763 Xenix.  Also, if @file{dirent.h} is being checked for, added
17764 @option{-ldir} to @code{LIBS}.  Now it is merely an alias of
17765 @code{AC_HEADER_DIRENT} instead, plus some code to detect whether
17766 running @sc{xenix} on which you should not depend:
17768 @example
17769 AC_MSG_CHECKING([for Xenix])
17770 AC_EGREP_CPP([yes],
17771 [#if defined M_XENIX && !defined M_UNIX
17772   yes
17773 #endif],
17774              [AC_MSG_RESULT([yes]); XENIX=yes],
17775              [AC_MSG_RESULT([no]); XENIX=])
17776 @end example
17777 @end defmac
17779 @defmac AC_YYTEXT_POINTER
17780 @acindex{YYTEXT_POINTER}
17781 @code{AC_DECL_YYTEXT}
17782 @end defmac
17784 @node Autoconf 1
17785 @section Upgrading From Version 1
17786 @cindex Upgrading autoconf
17787 @cindex Autoconf upgrading
17789 Autoconf version 2 is mostly backward compatible with version 1.
17790 However, it introduces better ways to do some things, and doesn't
17791 support some of the ugly things in version 1.  So, depending on how
17792 sophisticated your @file{configure.ac} files are, you might have to do
17793 some manual work in order to upgrade to version 2.  This chapter points
17794 out some problems to watch for when upgrading.  Also, perhaps your
17795 @command{configure} scripts could benefit from some of the new features in
17796 version 2; the changes are summarized in the file @file{NEWS} in the
17797 Autoconf distribution.
17799 @menu
17800 * Changed File Names::          Files you might rename
17801 * Changed Makefiles::           New things to put in @file{Makefile.in}
17802 * Changed Macros::              Macro calls you might replace
17803 * Changed Results::             Changes in how to check test results
17804 * Changed Macro Writing::       Better ways to write your own macros
17805 @end menu
17807 @node Changed File Names
17808 @subsection Changed File Names
17810 If you have an @file{aclocal.m4} installed with Autoconf (as opposed to
17811 in a particular package's source directory), you must rename it to
17812 @file{acsite.m4}.  @xref{autoconf Invocation}.
17814 If you distribute @file{install.sh} with your package, rename it to
17815 @file{install-sh} so @code{make} builtin rules don't inadvertently
17816 create a file called @file{install} from it.  @code{AC_PROG_INSTALL}
17817 looks for the script under both names, but it is best to use the new name.
17819 If you were using @file{config.h.top}, @file{config.h.bot}, or
17820 @file{acconfig.h}, you still can, but you have less clutter if you
17821 use the @code{AH_} macros.  @xref{Autoheader Macros}.
17823 @node Changed Makefiles
17824 @subsection Changed Makefiles
17826 Add @samp{@@CFLAGS@@}, @samp{@@CPPFLAGS@@}, and @samp{@@LDFLAGS@@} in
17827 your @file{Makefile.in} files, so they can take advantage of the values
17828 of those variables in the environment when @command{configure} is run.
17829 Doing this isn't necessary, but it's a convenience for users.
17831 Also add @samp{@@configure_input@@} in a comment to each input file for
17832 @code{AC_OUTPUT}, so that the output files contain a comment saying
17833 they were produced by @command{configure}.  Automatically selecting the
17834 right comment syntax for all the kinds of files that people call
17835 @code{AC_OUTPUT} on became too much work.
17837 Add @file{config.log} and @file{config.cache} to the list of files you
17838 remove in @code{distclean} targets.
17840 If you have the following in @file{Makefile.in}:
17842 @example
17843 prefix = /usr/local
17844 exec_prefix = $(prefix)
17845 @end example
17847 @noindent
17848 you must change it to:
17850 @example
17851 prefix = @@prefix@@
17852 exec_prefix = @@exec_prefix@@
17853 @end example
17855 @noindent
17856 The old behavior of replacing those variables without @samp{@@}
17857 characters around them has been removed.
17859 @node Changed Macros
17860 @subsection Changed Macros
17862 Many of the macros were renamed in Autoconf version 2.  You can still
17863 use the old names, but the new ones are clearer, and it's easier to find
17864 the documentation for them.  @xref{Obsolete Macros}, for a table showing the
17865 new names for the old macros.  Use the @command{autoupdate} program to
17866 convert your @file{configure.ac} to using the new macro names.
17867 @xref{autoupdate Invocation}.
17869 Some macros have been superseded by similar ones that do the job better,
17870 but are not call-compatible.  If you get warnings about calling obsolete
17871 macros while running @command{autoconf}, you may safely ignore them, but
17872 your @command{configure} script generally works better if you follow
17873 the advice that is printed about what to replace the obsolete macros with.  In
17874 particular, the mechanism for reporting the results of tests has
17875 changed.  If you were using @command{echo} or @code{AC_VERBOSE} (perhaps
17876 via @code{AC_COMPILE_CHECK}), your @command{configure} script's output
17877 looks better if you switch to @code{AC_MSG_CHECKING} and
17878 @code{AC_MSG_RESULT}.  @xref{Printing Messages}.  Those macros work best
17879 in conjunction with cache variables.  @xref{Caching Results}.
17883 @node Changed Results
17884 @subsection Changed Results
17886 If you were checking the results of previous tests by examining the
17887 shell variable @code{DEFS}, you need to switch to checking the values of
17888 the cache variables for those tests.  @code{DEFS} no longer exists while
17889 @command{configure} is running; it is only created when generating output
17890 files.  This difference from version 1 is because properly quoting the
17891 contents of that variable turned out to be too cumbersome and
17892 inefficient to do every time @code{AC_DEFINE} is called.  @xref{Cache
17893 Variable Names}.
17895 For example, here is a @file{configure.ac} fragment written for Autoconf
17896 version 1:
17898 @example
17899 AC_HAVE_FUNCS(syslog)
17900 case "$DEFS" in
17901 *-DHAVE_SYSLOG*) ;;
17902 *) # syslog is not in the default libraries.  See if it's in some other.
17903   saved_LIBS="$LIBS"
17904   for lib in bsd socket inet; do
17905     AC_CHECKING(for syslog in -l$lib)
17906     LIBS="-l$lib $saved_LIBS"
17907     AC_HAVE_FUNCS(syslog)
17908     case "$DEFS" in
17909     *-DHAVE_SYSLOG*) break ;;
17910     *) ;;
17911     esac
17912     LIBS="$saved_LIBS"
17913   done ;;
17914 esac
17915 @end example
17917 Here is a way to write it for version 2:
17919 @example
17920 AC_CHECK_FUNCS([syslog])
17921 if test $ac_cv_func_syslog = no; then
17922   # syslog is not in the default libraries.  See if it's in some other.
17923   for lib in bsd socket inet; do
17924     AC_CHECK_LIB([$lib], [syslog], [AC_DEFINE([HAVE_SYSLOG])
17925       LIBS="-l$lib $LIBS"; break])
17926   done
17928 @end example
17930 If you were working around bugs in @code{AC_DEFINE_UNQUOTED} by adding
17931 backslashes before quotes, you need to remove them.  It now works
17932 predictably, and does not treat quotes (except back quotes) specially.
17933 @xref{Setting Output Variables}.
17935 All of the Boolean shell variables set by Autoconf macros now use
17936 @samp{yes} for the true value.  Most of them use @samp{no} for false,
17937 though for backward compatibility some use the empty string instead.  If
17938 you were relying on a shell variable being set to something like 1 or
17939 @samp{t} for true, you need to change your tests.
17941 @node Changed Macro Writing
17942 @subsection Changed Macro Writing
17944 When defining your own macros, you should now use @code{AC_DEFUN}
17945 instead of @code{define}.  @code{AC_DEFUN} automatically calls
17946 @code{AC_PROVIDE} and ensures that macros called via @code{AC_REQUIRE}
17947 do not interrupt other macros, to prevent nested @samp{checking@dots{}}
17948 messages on the screen.  There's no actual harm in continuing to use the
17949 older way, but it's less convenient and attractive.  @xref{Macro
17950 Definitions}.
17952 You probably looked at the macros that came with Autoconf as a guide for
17953 how to do things.  It would be a good idea to take a look at the new
17954 versions of them, as the style is somewhat improved and they take
17955 advantage of some new features.
17957 If you were doing tricky things with undocumented Autoconf internals
17958 (macros, variables, diversions), check whether you need to change
17959 anything to account for changes that have been made.  Perhaps you can
17960 even use an officially supported technique in version 2 instead of
17961 kludging.  Or perhaps not.
17963 To speed up your locally written feature tests, add caching to them.
17964 See whether any of your tests are of general enough usefulness to
17965 encapsulate them into macros that you can share.
17968 @node Autoconf 2.13
17969 @section Upgrading From Version 2.13
17970 @cindex Upgrading autoconf
17971 @cindex Autoconf upgrading
17973 The introduction of the previous section (@pxref{Autoconf 1}) perfectly
17974 suits this section@enddots{}
17976 @quotation
17977 Autoconf version 2.50 is mostly backward compatible with version 2.13.
17978 However, it introduces better ways to do some things, and doesn't
17979 support some of the ugly things in version 2.13.  So, depending on how
17980 sophisticated your @file{configure.ac} files are, you might have to do
17981 some manual work in order to upgrade to version 2.50.  This chapter
17982 points out some problems to watch for when upgrading.  Also, perhaps
17983 your @command{configure} scripts could benefit from some of the new
17984 features in version 2.50; the changes are summarized in the file
17985 @file{NEWS} in the Autoconf distribution.
17986 @end quotation
17988 @menu
17989 * Changed Quotation::           Broken code which used to work
17990 * New Macros::                  Interaction with foreign macros
17991 * Hosts and Cross-Compilation::  Bugward compatibility kludges
17992 * AC_LIBOBJ vs LIBOBJS::        LIBOBJS is a forbidden token
17993 * AC_FOO_IFELSE vs AC_TRY_FOO::  A more generic scheme for testing sources
17994 @end menu
17996 @node Changed Quotation
17997 @subsection Changed Quotation
17999 The most important changes are invisible to you: the implementation of
18000 most macros have completely changed.  This allowed more factorization of
18001 the code, better error messages, a higher uniformity of the user's
18002 interface etc.  Unfortunately, as a side effect, some construct which
18003 used to (miraculously) work might break starting with Autoconf 2.50.
18004 The most common culprit is bad quotation.
18006 For instance, in the following example, the message is not properly
18007 quoted:
18009 @example
18010 AC_INIT
18011 AC_CHECK_HEADERS(foo.h, ,
18012   AC_MSG_ERROR(cannot find foo.h, bailing out))
18013 AC_OUTPUT
18014 @end example
18016 @noindent
18017 Autoconf 2.13 simply ignores it:
18019 @example
18020 $ @kbd{autoconf-2.13; ./configure --silent}
18021 creating cache ./config.cache
18022 configure: error: cannot find foo.h
18024 @end example
18026 @noindent
18027 while Autoconf 2.50 produces a broken @file{configure}:
18029 @example
18030 $ @kbd{autoconf-2.50; ./configure --silent}
18031 configure: error: cannot find foo.h
18032 ./configure: exit: bad non-numeric arg `bailing'
18033 ./configure: exit: bad non-numeric arg `bailing'
18035 @end example
18037 The message needs to be quoted, and the @code{AC_MSG_ERROR} invocation
18038 too!
18040 @example
18041 AC_INIT([Example], [1.0], [bug-example@@example.org])
18042 AC_CHECK_HEADERS([foo.h], [],
18043   [AC_MSG_ERROR([cannot find foo.h, bailing out])])
18044 AC_OUTPUT
18045 @end example
18047 Many many (and many more) Autoconf macros were lacking proper quotation,
18048 including no less than@dots{} @code{AC_DEFUN} itself!
18050 @example
18051 $ @kbd{cat configure.in}
18052 AC_DEFUN([AC_PROG_INSTALL],
18053 [# My own much better version
18055 AC_INIT
18056 AC_PROG_INSTALL
18057 AC_OUTPUT
18058 $ @kbd{autoconf-2.13}
18059 autoconf: Undefined macros:
18060 ***BUG in Autoconf--please report*** AC_FD_MSG
18061 ***BUG in Autoconf--please report*** AC_EPI
18062 configure.in:1:AC_DEFUN([AC_PROG_INSTALL],
18063 configure.in:5:AC_PROG_INSTALL
18064 $ @kbd{autoconf-2.50}
18066 @end example
18069 @node New Macros
18070 @subsection New Macros
18072 @cindex undefined macro
18073 @cindex @code{_m4_divert_diversion}
18075 While Autoconf was relatively dormant in the late 1990s, Automake
18076 provided Autoconf-like macros for a while.  Starting with Autoconf 2.50
18077 in 2001, Autoconf provided
18078 versions of these macros, integrated in the @code{AC_} namespace,
18079 instead of @code{AM_}.  But in order to ease the upgrading via
18080 @command{autoupdate}, bindings to such @code{AM_} macros are provided.
18082 Unfortunately older versions of Automake (e.g., Automake 1.4)
18083 did not quote the names of these macros.
18084 Therefore, when @command{m4} finds something like
18085 @samp{AC_DEFUN(AM_TYPE_PTRDIFF_T, @dots{})} in @file{aclocal.m4},
18086 @code{AM_TYPE_PTRDIFF_T} is
18087 expanded, replaced with its Autoconf definition.
18089 Fortunately Autoconf catches pre-@code{AC_INIT} expansions, and
18090 complains, in its own words:
18092 @example
18093 $ @kbd{cat configure.ac}
18094 AC_INIT([Example], [1.0], [bug-example@@example.org])
18095 AM_TYPE_PTRDIFF_T
18096 $ @kbd{aclocal-1.4}
18097 $ @kbd{autoconf}
18098 aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion
18099 aclocal.m4:17: the top level
18100 autom4te: m4 failed with exit status: 1
18102 @end example
18104 Modern versions of Automake no longer define most of these
18105 macros, and properly quote the names of the remaining macros.
18106 If you must use an old Automake, do not depend upon macros from Automake
18107 as it is simply not its job
18108 to provide macros (but the one it requires itself):
18110 @example
18111 $ @kbd{cat configure.ac}
18112 AC_INIT([Example], [1.0], [bug-example@@example.org])
18113 AM_TYPE_PTRDIFF_T
18114 $ @kbd{rm aclocal.m4}
18115 $ @kbd{autoupdate}
18116 autoupdate: `configure.ac' is updated
18117 $ @kbd{cat configure.ac}
18118 AC_INIT([Example], [1.0], [bug-example@@example.org])
18119 AC_CHECK_TYPES([ptrdiff_t])
18120 $ @kbd{aclocal-1.4}
18121 $ @kbd{autoconf}
18123 @end example
18126 @node Hosts and Cross-Compilation
18127 @subsection Hosts and Cross-Compilation
18128 @cindex Cross compilation
18130 Based on the experience of compiler writers, and after long public
18131 debates, many aspects of the cross-compilation chain have changed:
18133 @itemize @minus
18134 @item
18135 the relationship between the build, host, and target architecture types,
18137 @item
18138 the command line interface for specifying them to @command{configure},
18140 @item
18141 the variables defined in @command{configure},
18143 @item
18144 the enabling of cross-compilation mode.
18145 @end itemize
18147 @sp 1
18149 The relationship between build, host, and target have been cleaned up:
18150 the chain of default is now simply: target defaults to host, host to
18151 build, and build to the result of @command{config.guess}.  Nevertheless,
18152 in order to ease the transition from 2.13 to 2.50, the following
18153 transition scheme is implemented.  @emph{Do not rely on it}, as it will
18154 be completely disabled in a couple of releases (we cannot keep it, as it
18155 proves to cause more problems than it cures).
18157 They all default to the result of running @command{config.guess}, unless
18158 you specify either @option{--build} or @option{--host}.  In this case,
18159 the default becomes the system type you specified.  If you specify both,
18160 and they're different, @command{configure} enters cross compilation
18161 mode, so it doesn't run any tests that require execution.
18163 Hint: if you mean to override the result of @command{config.guess},
18164 prefer @option{--build} over @option{--host}.  In the future,
18165 @option{--host} will not override the name of the build system type.
18166 Whenever you specify @option{--host}, be sure to specify @option{--build}
18167 too.
18169 @sp 1
18171 For backward compatibility, @command{configure} accepts a system
18172 type as an option by itself.  Such an option overrides the
18173 defaults for build, host, and target system types.  The following
18174 configure statement configures a cross toolchain that runs on
18175 Net@acronym{BSD}/alpha but generates code for @acronym{GNU} Hurd/sparc,
18176 which is also the build platform.
18178 @example
18179 ./configure --host=alpha-netbsd sparc-gnu
18180 @end example
18182 @sp 1
18184 In Autoconf 2.13 and before, the variables @code{build}, @code{host},
18185 and @code{target} had a different semantics before and after the
18186 invocation of @code{AC_CANONICAL_BUILD} etc.  Now, the argument of
18187 @option{--build} is strictly copied into @code{build_alias}, and is left
18188 empty otherwise.  After the @code{AC_CANONICAL_BUILD}, @code{build} is
18189 set to the canonicalized build type.  To ease the transition, before,
18190 its contents is the same as that of @code{build_alias}.  Do @emph{not}
18191 rely on this broken feature.
18193 For consistency with the backward compatibility scheme exposed above,
18194 when @option{--host} is specified but @option{--build} isn't, the build
18195 system is assumed to be the same as @option{--host}, and
18196 @samp{build_alias} is set to that value.  Eventually, this
18197 historically incorrect behavior will go away.
18199 @sp 1
18201 The former scheme to enable cross-compilation proved to cause more harm
18202 than good, in particular, it used to be triggered too easily, leaving
18203 regular end users puzzled in front of cryptic error messages.
18204 @command{configure} could even enter cross-compilation mode only
18205 because the compiler was not functional.  This is mainly because
18206 @command{configure} used to try to detect cross-compilation, instead of
18207 waiting for an explicit flag from the user.
18209 Now, @command{configure} enters cross-compilation mode if and only if
18210 @option{--host} is passed.
18212 That's the short documentation.  To ease the transition between 2.13 and
18213 its successors, a more complicated scheme is implemented.  @emph{Do not
18214 rely on the following}, as it will be removed in the near future.
18216 If you specify @option{--host}, but not @option{--build}, when
18217 @command{configure} performs the first compiler test it tries to run
18218 an executable produced by the compiler.  If the execution fails, it
18219 enters cross-compilation mode.  This is fragile.  Moreover, by the time
18220 the compiler test is performed, it may be too late to modify the
18221 build-system type: other tests may have already been performed.
18222 Therefore, whenever you specify @option{--host}, be sure to specify
18223 @option{--build} too.
18225 @example
18226 ./configure --build=i686-pc-linux-gnu --host=m68k-coff
18227 @end example
18229 @noindent
18230 enters cross-compilation mode.  The former interface, which
18231 consisted in setting the compiler to a cross-compiler without informing
18232 @command{configure} is obsolete.  For instance, @command{configure}
18233 fails if it can't run the code generated by the specified compiler if you
18234 configure as follows:
18236 @example
18237 ./configure CC=m68k-coff-gcc
18238 @end example
18241 @node AC_LIBOBJ vs LIBOBJS
18242 @subsection @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}
18244 Up to Autoconf 2.13, the replacement of functions was triggered via the
18245 variable @code{LIBOBJS}.  Since Autoconf 2.50, the macro
18246 @code{AC_LIBOBJ} should be used instead (@pxref{Generic Functions}).
18247 Starting at Autoconf 2.53, the use of @code{LIBOBJS} is an error.
18249 This change is mandated by the unification of the @acronym{GNU} Build System
18250 components.  In particular, the various fragile techniques used to parse
18251 a @file{configure.ac} are all replaced with the use of traces.  As a
18252 consequence, any action must be traceable, which obsoletes critical
18253 variable assignments.  Fortunately, @code{LIBOBJS} was the only problem,
18254 and it can even be handled gracefully (read, ``without your having to
18255 change something'').
18257 There were two typical uses of @code{LIBOBJS}: asking for a replacement
18258 function, and adjusting @code{LIBOBJS} for Automake and/or Libtool.
18260 @sp 1
18262 As for function replacement, the fix is immediate: use
18263 @code{AC_LIBOBJ}.  For instance:
18265 @example
18266 LIBOBJS="$LIBOBJS fnmatch.o"
18267 LIBOBJS="$LIBOBJS malloc.$ac_objext"
18268 @end example
18270 @noindent
18271 should be replaced with:
18273 @example
18274 AC_LIBOBJ([fnmatch])
18275 AC_LIBOBJ([malloc])
18276 @end example
18278 @sp 1
18280 @ovindex LIBOBJDIR
18281 When used with Automake 1.10 or newer, a suitable value for
18282 @code{LIBOBJDIR} is set so that the @code{LIBOBJS} and @code{LTLIBOBJS}
18283 can be referenced from any @file{Makefile.am}.  Even without Automake,
18284 arranging for @code{LIBOBJDIR} to be set correctly enables
18285 referencing @code{LIBOBJS} and @code{LTLIBOBJS} in another directory.
18286 The @code{LIBOBJDIR} feature is experimental.
18289 @node AC_FOO_IFELSE vs AC_TRY_FOO
18290 @subsection @code{AC_FOO_IFELSE} vs.@: @code{AC_TRY_FOO}
18292 Since Autoconf 2.50, internal codes uses @code{AC_PREPROC_IFELSE},
18293 @code{AC_COMPILE_IFELSE}, @code{AC_LINK_IFELSE}, and
18294 @code{AC_RUN_IFELSE} on one hand and @code{AC_LANG_SOURCES},
18295 and @code{AC_LANG_PROGRAM} on the other hand instead of the deprecated
18296 @code{AC_TRY_CPP}, @code{AC_TRY_COMPILE}, @code{AC_TRY_LINK}, and
18297 @code{AC_TRY_RUN}.  The motivations where:
18298 @itemize @minus
18299 @item
18300 a more consistent interface: @code{AC_TRY_COMPILE} etc.@: were double
18301 quoting their arguments;
18303 @item
18304 the combinatoric explosion is solved by decomposing on the one hand the
18305 generation of sources, and on the other hand executing the program;
18307 @item
18308 this scheme helps supporting more languages than plain C and C++.
18309 @end itemize
18311 In addition to the change of syntax, the philosophy has changed too:
18312 while emphasis was put on speed at the expense of accuracy, today's
18313 Autoconf promotes accuracy of the testing framework at, ahem@dots{}, the
18314 expense of speed.
18317 As a perfect example of what is @emph{not} to be done, here is how to
18318 find out whether a header file contains a particular declaration, such
18319 as a typedef, a structure, a structure member, or a function.  Use
18320 @code{AC_EGREP_HEADER} instead of running @code{grep} directly on the
18321 header file; on some systems the symbol might be defined in another
18322 header file that the file you are checking includes.
18324 As a (bad) example, here is how you should not check for C preprocessor
18325 symbols, either defined by header files or predefined by the C
18326 preprocessor: using @code{AC_EGREP_CPP}:
18328 @example
18329 @group
18330 AC_EGREP_CPP(yes,
18331 [#ifdef _AIX
18332   yes
18333 #endif
18334 ], is_aix=yes, is_aix=no)
18335 @end group
18336 @end example
18338 The above example, properly written would (i) use
18339 @code{AC_LANG_PROGRAM}, and (ii) run the compiler:
18341 @example
18342 @group
18343 AC_COMPILE_IFELSE([AC_LANG_PROGRAM(
18344 [[#ifndef _AIX
18345  error: This isn't AIX!
18346 #endif
18347 ]])],
18348                    [is_aix=yes],
18349                    [is_aix=no])
18350 @end group
18351 @end example
18354 @c ============================= Generating Test Suites with Autotest
18356 @node Using Autotest
18357 @chapter Generating Test Suites with Autotest
18359 @cindex Autotest
18361 @display
18362 @strong{N.B.: This section describes an experimental feature which will
18363 be part of Autoconf in a forthcoming release.  Although we believe
18364 Autotest is stabilizing, this documentation describes an interface which
18365 might change in the future: do not depend upon Autotest without
18366 subscribing to the Autoconf mailing lists.}
18367 @end display
18369 It is paradoxical that portable projects depend on nonportable tools
18370 to run their test suite.  Autoconf by itself is the paragon of this
18371 problem: although it aims at perfectly portability, up to 2.13 its
18372 test suite was using Deja@acronym{GNU}, a rich and complex testing
18373 framework, but which is far from being standard on Posix systems.
18374 Worse yet, it was likely to be missing on the most fragile platforms,
18375 the very platforms that are most likely to torture Autoconf and
18376 exhibit deficiencies.
18378 To circumvent this problem, many package maintainers have developed their
18379 own testing framework, based on simple shell scripts whose sole outputs
18380 are exit status values describing whether the test succeeded.  Most of
18381 these tests share common patterns, and this can result in lots of
18382 duplicated code and tedious maintenance.
18384 Following exactly the same reasoning that yielded to the inception of
18385 Autoconf, Autotest provides a test suite generation framework, based on
18386 M4 macros building a portable shell script.  The suite itself is
18387 equipped with automatic logging and tracing facilities which greatly
18388 diminish the interaction with bug reporters, and simple timing reports.
18390 Autoconf itself has been using Autotest for years, and we do attest that
18391 it has considerably improved the strength of the test suite and the
18392 quality of bug reports.  Other projects are known to use some generation
18393 of Autotest, such as Bison, Free Recode, Free Wdiff, @acronym{GNU} Tar, each of
18394 them with different needs, and this usage has validated Autotest as a general
18395 testing framework.
18397 Nonetheless, compared to Deja@acronym{GNU}, Autotest is inadequate for
18398 interactive tool testing, which is probably its main limitation.
18400 @menu
18401 * Using an Autotest Test Suite::  Autotest and the user
18402 * Writing Testsuites::          Autotest macros
18403 * testsuite Invocation::        Running @command{testsuite} scripts
18404 * Making testsuite Scripts::    Using autom4te to create @command{testsuite}
18405 @end menu
18407 @node Using an Autotest Test Suite
18408 @section Using an Autotest Test Suite
18410 @menu
18411 * testsuite Scripts::           The concepts of Autotest
18412 * Autotest Logs::               Their contents
18413 @end menu
18415 @node testsuite Scripts
18416 @subsection @command{testsuite} Scripts
18418 @cindex @command{testsuite}
18420 Generating testing or validation suites using Autotest is rather easy.
18421 The whole validation suite is held in a file to be processed through
18422 @command{autom4te}, itself using @acronym{GNU} M4 under the scene, to
18423 produce a stand-alone Bourne shell script which then gets distributed.
18424 Neither @command{autom4te} nor @acronym{GNU} M4 are needed at
18425 the installer's end.
18427 @cindex test group
18428 Each test of the validation suite should be part of some test group.  A
18429 @dfn{test group} is a sequence of interwoven tests that ought to be
18430 executed together, usually because one test in the group creates data
18431 files than a later test in the same group needs to read.  Complex test
18432 groups make later debugging more tedious.  It is much better to
18433 keep only a few tests per test group.  Ideally there is only one test
18434 per test group.
18436 For all but the simplest packages, some file such as @file{testsuite.at}
18437 does not fully hold all test sources, as these are often easier to
18438 maintain in separate files.  Each of these separate files holds a single
18439 test group, or a sequence of test groups all addressing some common
18440 functionality in the package.  In such cases, @file{testsuite.at}
18441 merely initializes the validation suite, and sometimes does elementary
18442 health checking, before listing include statements for all other test
18443 files.  The special file @file{package.m4}, containing the
18444 identification of the package, is automatically included if found.
18446 A convenient alternative consists in moving all the global issues
18447 (local Autotest macros, elementary health checking, and @code{AT_INIT}
18448 invocation) into the file @code{local.at}, and making
18449 @file{testsuite.at} be a simple list of @code{m4_include} of sub test
18450 suites.  In such case, generating the whole test suite or pieces of it
18451 is only a matter of choosing the @command{autom4te} command line
18452 arguments.
18454 The validation scripts that Autotest produces are by convention called
18455 @command{testsuite}.  When run, @command{testsuite} executes each test
18456 group in turn, producing only one summary line per test to say if that
18457 particular test succeeded or failed.  At end of all tests, summarizing
18458 counters get printed.  One debugging directory is left for each test
18459 group which failed, if any: such directories are named
18460 @file{testsuite.dir/@var{nn}}, where @var{nn} is the sequence number of
18461 the test group, and they include:
18463 @itemize @bullet
18464 @item a debugging script named @file{run} which reruns the test in
18465 @dfn{debug mode} (@pxref{testsuite Invocation}).  The automatic generation
18466 of debugging scripts has the purpose of easing the chase for bugs.
18468 @item all the files created with @code{AT_DATA}
18470 @item a log of the run, named @file{testsuite.log}
18471 @end itemize
18473 In the ideal situation, none of the tests fail, and consequently no
18474 debugging directory is left behind for validation.
18476 It often happens in practice that individual tests in the validation
18477 suite need to get information coming out of the configuration process.
18478 Some of this information, common for all validation suites, is provided
18479 through the file @file{atconfig}, automatically created by
18480 @code{AC_CONFIG_TESTDIR}.  For configuration informations which your
18481 testing environment specifically needs, you might prepare an optional
18482 file named @file{atlocal.in}, instantiated by @code{AC_CONFIG_FILES}.
18483 The configuration process produces @file{atconfig} and @file{atlocal}
18484 out of these two input files, and these two produced files are
18485 automatically read by the @file{testsuite} script.
18487 Here is a diagram showing the relationship between files.
18489 @noindent
18490 Files used in preparing a software package for distribution:
18492 @example
18493                 [package.m4] -->.
18494                                  \
18495 subfile-1.at ->.  [local.at] ---->+
18496     ...         \                  \
18497 subfile-i.at ---->-- testsuite.at -->-- autom4te* -->testsuite
18498     ...         /
18499 subfile-n.at ->'
18500 @end example
18502 @noindent
18503 Files used in configuring a software package:
18505 @example
18506                                      .--> atconfig
18507                                     /
18508 [atlocal.in] -->  config.status* --<
18509                                     \
18510                                      `--> [atlocal]
18511 @end example
18513 @noindent
18514 Files created during the test suite execution:
18516 @example
18517 atconfig -->.                    .--> testsuite.log
18518              \                  /
18519               >-- testsuite* --<
18520              /                  \
18521 [atlocal] ->'                    `--> [testsuite.dir]
18522 @end example
18525 @node Autotest Logs
18526 @subsection Autotest Logs
18528 When run, the test suite creates a log file named after itself, e.g., a
18529 test suite named @command{testsuite} creates @file{testsuite.log}.  It
18530 contains a lot of information, usually more than maintainers actually
18531 need, but therefore most of the time it contains all that is needed:
18533 @table @asis
18534 @item command line arguments
18535 @c akim s/to consist in/to consist of/
18536 A bad but unfortunately widespread habit consists of
18537 setting environment variables before the command, such as in
18538 @samp{CC=my-home-grown-cc ./testsuite}.  The test suite does not
18539 know this change, hence (i) it cannot report it to you, and (ii)
18540 it cannot preserve the value of @code{CC} for subsequent runs.
18541 Autoconf faced exactly the same problem, and solved it by asking
18542 users to pass the variable definitions as command line arguments.
18543 Autotest requires this rule, too, but has no means to enforce it; the log
18544 then contains a trace of the variables that were changed by the user.
18546 @item @file{ChangeLog} excerpts
18547 The topmost lines of all the @file{ChangeLog} files found in the source
18548 hierarchy.  This is especially useful when bugs are reported against
18549 development versions of the package, since the version string does not
18550 provide sufficient information to know the exact state of the sources
18551 the user compiled.  Of course, this relies on the use of a
18552 @file{ChangeLog}.
18554 @item build machine
18555 Running a test suite in a cross-compile environment is not an easy task,
18556 since it would mean having the test suite run on a machine @var{build},
18557 while running programs on a machine @var{host}.  It is much simpler to
18558 run both the test suite and the programs on @var{host}, but then, from
18559 the point of view of the test suite, there remains a single environment,
18560 @var{host} = @var{build}.  The log contains relevant information on the
18561 state of the build machine, including some important environment
18562 variables.
18563 @c FIXME: How about having an M4sh macro to say `hey, log the value
18564 @c of `@dots{}'?  This would help both Autoconf and Autotest.
18566 @item tested programs
18567 The absolute file name and answers to @option{--version} of the tested
18568 programs (see @ref{Writing Testsuites}, @code{AT_TESTED}).
18570 @item configuration log
18571 The contents of @file{config.log}, as created by @command{configure},
18572 are appended.  It contains the configuration flags and a detailed report
18573 on the configuration itself.
18574 @end table
18577 @node Writing Testsuites
18578 @section Writing @file{testsuite.at}
18580 The @file{testsuite.at} is a Bourne shell script making use of special
18581 Autotest M4 macros.  It often contains a call to @code{AT_INIT} near
18582 its beginning followed by one call to @code{m4_include} per source file
18583 for tests.  Each such included file, or the remainder of
18584 @file{testsuite.at} if include files are not used, contain a sequence of
18585 test groups.  Each test group begins with a call to @code{AT_SETUP},
18586 then an arbitrary number of shell commands or calls to @code{AT_CHECK},
18587 and then completes with a call to @code{AT_CLEANUP}.
18589 @defmac AT_INIT (@ovar{name})
18590 @atindex{INIT}
18591 @c FIXME: Not clear, plus duplication of the information.
18592 Initialize Autotest.  Giving a @var{name} to the test suite is
18593 encouraged if your package includes several test suites.  In any case,
18594 the test suite always displays the package name and version.  It also
18595 inherits the package bug report address.
18596 @end defmac
18598 @defmac AT_COPYRIGHT (@var{copyright-notice})
18599 @atindex{COPYRIGHT}
18600 @cindex Copyright Notice
18601 State that, in addition to the Free Software Foundation's copyright on
18602 the Autotest macros, parts of your test suite are covered by
18603 @var{copyright-notice}.
18605 The @var{copyright-notice} shows up in both the head of
18606 @command{testsuite} and in @samp{testsuite --version}.
18607 @end defmac
18609 @defmac AT_TESTED (@var{executables})
18610 @atindex{TESTED}
18611 Log the file name and answer to @option{--version} of each program in
18612 space-separated list @var{executables}.  Several invocations register
18613 new executables, in other words, don't fear registering one program
18614 several times.
18615 @end defmac
18617 Autotest test suites rely on @env{PATH} to find the tested program.
18618 This avoids the need to generate absolute names of the various tools, and
18619 makes it possible to test installed programs.  Therefore, knowing which
18620 programs are being exercised is crucial to understanding problems in
18621 the test suite itself, or its occasional misuses.  It is a good idea to
18622 also subscribe foreign programs you depend upon, to avoid incompatible
18623 diagnostics.
18625 @sp 1
18627 @defmac AT_SETUP (@var{test-group-name})
18628 @atindex{SETUP}
18629 This macro starts a group of related tests, all to be executed in the
18630 same subshell.  It accepts a single argument, which holds a few words
18631 (no more than about 30 or 40 characters) quickly describing the purpose
18632 of the test group being started.
18633 @end defmac
18635 @defmac AT_KEYWORDS (@var{keywords})
18636 @atindex{KEYWORDS}
18637 Associate the space-separated list of @var{keywords} to the enclosing
18638 test group.  This makes it possible to run ``slices'' of the test suite.
18639 For instance, if some of your test groups exercise some @samp{foo}
18640 feature, then using @samp{AT_KEYWORDS(foo)} lets you run
18641 @samp{./testsuite -k foo} to run exclusively these test groups.  The
18642 @var{title} of the test group is automatically recorded to
18643 @code{AT_KEYWORDS}.
18645 Several invocations within a test group accumulate new keywords.  In
18646 other words, don't fear registering the same keyword several times in a
18647 test group.
18648 @end defmac
18650 @defmac AT_CAPTURE_FILE (@var{file})
18651 @atindex{CAPTURE_FILE}
18652 If the current test group fails, log the contents of @var{file}.
18653 Several identical calls within one test group have no additional effect.
18654 @end defmac
18656 @defmac AT_XFAIL_IF (@var{shell-condition})
18657 @atindex{XFAIL_IF}
18658 Determine whether the test is expected to fail because it is a known
18659 bug (for unsupported features, you should skip the test).
18660 @var{shell-condition} is a shell expression such as a @code{test}
18661 command; you can instantiate this macro many times from within the
18662 same test group, and one of the conditions is enough to turn
18663 the test into an expected failure.
18664 @end defmac
18666 @defmac AT_CLEANUP
18667 @atindex{CLEANUP}
18668 End the current test group.
18669 @end defmac
18671 @sp 1
18673 @defmac AT_DATA (@var{file}, @var{contents})
18674 @atindex{DATA}
18675 Initialize an input data @var{file} with given @var{contents}.  Of
18676 course, the @var{contents} have to be properly quoted between square
18677 brackets to protect against included commas or spurious M4
18678 expansion.  The contents ought to end with an end of line.
18679 @end defmac
18681 @defmac AT_CHECK (@var{commands}, @dvar{status, 0}, @dvar{stdout, }, @dvar{stderr, }, @ovar{run-if-fail}, @ovar{run-if-pass})
18682 @atindex{CHECK}
18683 Execute a test by performing given shell @var{commands}.  These commands
18684 should normally exit with @var{status}, while producing expected
18685 @var{stdout} and @var{stderr} contents.  If @var{commands} exit with
18686 status 77, then the whole test group is skipped.  Otherwise, if this test
18687 fails, run shell commands @var{run-if-fail} or, if this test passes, run shell
18688 commands @var{run-if-pass}.
18690 The @var{commands} @emph{must not} redirect the standard output, nor the
18691 standard error.
18693 If @var{status}, or @var{stdout}, or @var{stderr} is @samp{ignore}, then
18694 the corresponding value is not checked.
18696 The special value @samp{expout} for @var{stdout} means the expected
18697 output of the @var{commands} is the content of the file @file{expout}.
18698 If @var{stdout} is @samp{stdout}, then the standard output of the
18699 @var{commands} is available for further tests in the file @file{stdout}.
18700 Similarly for @var{stderr} with @samp{experr} and @samp{stderr}.
18701 @end defmac
18704 @node testsuite Invocation
18705 @section Running @command{testsuite} Scripts
18706 @cindex @command{testsuite}
18708 Autotest test suites support the following arguments:
18710 @table @option
18711 @item --help
18712 @itemx -h
18713 Display the list of options and exit successfully.
18715 @item --version
18716 @itemx -V
18717 Display the version of the test suite and exit successfully.
18719 @item --clean
18720 @itemx -c
18721 Remove all the files the test suite might have created and exit.  Meant
18722 for @code{clean} Make targets.
18724 @item --list
18725 @itemx -l
18726 List all the tests (or only the selection), including their possible
18727 keywords.
18728 @end table
18730 @sp 1
18732 By default all tests are performed (or described with
18733 @option{--list}) in the default environment first silently, then
18734 verbosely, but the environment, set of tests, and verbosity level can be
18735 tuned:
18737 @table @samp
18738 @item @var{variable}=@var{value}
18739 Set the environment @var{variable} to @var{value}.  Use this rather
18740 than @samp{FOO=foo ./testsuite} as debugging scripts would then run in a
18741 different environment.
18743 @cindex @code{AUTOTEST_PATH}
18744 The variable @code{AUTOTEST_PATH} specifies the testing path to prepend
18745 to @env{PATH}.  Relative directory names (not starting with
18746 @samp{/}) are considered to be relative to the top level of the
18747 package being built.  All directories are made absolute, first
18748 starting from the top level @emph{build} tree, then from the
18749 @emph{source} tree.  For instance @samp{./testsuite
18750 AUTOTEST_PATH=tests:bin} for a @file{/src/foo-1.0} source package built
18751 in @file{/tmp/foo} results in @samp{/tmp/foo/tests:/tmp/foo/bin} and
18752 then @samp{/src/foo-1.0/tests:/src/foo-1.0/bin} being prepended to
18753 @env{PATH}.
18755 @item @var{number}
18756 @itemx @var{number}-@var{number}
18757 @itemx @var{number}-
18758 @itemx -@var{number}
18759 Add the corresponding test groups, with obvious semantics, to the
18760 selection.
18762 @item --keywords=@var{keywords}
18763 @itemx -k @var{keywords}
18764 Add to the selection the test groups with title or keywords (arguments
18765 to @code{AT_SETUP} or @code{AT_KEYWORDS}) that match @emph{all} keywords
18766 of the comma separated list @var{keywords}, case-insensitively.  Use
18767 @samp{!} immediately before the keyword to invert the selection for this
18768 keyword.  By default, the keywords match whole words; enclose them in
18769 @samp{.*} to also match parts of words.
18771 For example, running
18773 @example
18774 @kbd{./testsuite -k 'autoupdate,.*FUNC.*'}
18775 @end example
18777 @noindent
18778 selects all tests tagged @samp{autoupdate} @emph{and} with tags
18779 containing @samp{FUNC} (as in @samp{AC_CHECK_FUNC}, @samp{AC_FUNC_ALLOCA},
18780 etc.), while
18782 @example
18783 @kbd{./testsuite -k '!autoupdate' -k '.*FUNC.*'}
18784 @end example
18786 @noindent
18787 selects all tests not tagged @samp{autoupdate} @emph{or} with tags
18788 containing @samp{FUNC}.
18790 @item --errexit
18791 @itemx -e
18792 If any test fails, immediately abort testing.  It implies
18793 @option{--debug}: post test group clean up, and top-level logging
18794 are inhibited.  This option is meant for the full test
18795 suite, it is not really useful for generated debugging scripts.
18797 @item --verbose
18798 @itemx -v
18799 Force more verbosity in the detailed output of what is being done.  This
18800 is the default for debugging scripts.
18802 @item --debug
18803 @itemx -d
18804 Do not remove the files after a test group was performed ---but they are
18805 still removed @emph{before}, therefore using this option is sane when
18806 running several test groups.  Create debugging scripts.  Do not
18807 overwrite the top-level
18808 log (in order to preserve supposedly existing full log file).  This is
18809 the default for debugging scripts, but it can also be useful to debug
18810 the testsuite itself.
18812 @item --trace
18813 @itemx -x
18814 Trigger shell tracing of the test groups.
18815 @end table
18818 @node Making testsuite Scripts
18819 @section Making @command{testsuite} Scripts
18821 For putting Autotest into movement, you need some configuration and
18822 makefile machinery.  We recommend, at least if your package uses deep or
18823 shallow hierarchies, that you use @file{tests/} as the name of the
18824 directory holding all your tests and their makefile.  Here is a
18825 check list of things to do.
18827 @itemize @minus
18829 @item
18830 @cindex @file{package.m4}
18831 Make sure to create the file @file{package.m4}, which defines the
18832 identity of the package.  It must define @code{AT_PACKAGE_STRING}, the
18833 full signature of the package, and @code{AT_PACKAGE_BUGREPORT}, the
18834 address to which bug reports should be sent.  For sake of completeness,
18835 we suggest that you also define @code{AT_PACKAGE_NAME},
18836 @code{AT_PACKAGE_TARNAME}, and @code{AT_PACKAGE_VERSION}.
18837 @xref{Initializing configure}, for a description of these variables.  We
18838 suggest the following makefile excerpt:
18840 @smallexample
18841 $(srcdir)/package.m4: $(top_srcdir)/configure.ac
18842         @{                                      \
18843           echo '# Signature of the current package.'; \
18844           echo 'm4_define([AT_PACKAGE_NAME],      [@@PACKAGE_NAME@@])'; \
18845           echo 'm4_define([AT_PACKAGE_TARNAME],   [@@PACKAGE_TARNAME@@])'; \
18846           echo 'm4_define([AT_PACKAGE_VERSION],   [@@PACKAGE_VERSION@@])'; \
18847           echo 'm4_define([AT_PACKAGE_STRING],    [@@PACKAGE_STRING@@])'; \
18848           echo 'm4_define([AT_PACKAGE_BUGREPORT], [@@PACKAGE_BUGREPORT@@])'; \
18849         @} >'$(srcdir)/package.m4'
18850 @end smallexample
18852 @noindent
18853 Be sure to distribute @file{package.m4} and to put it into the source
18854 hierarchy: the test suite ought to be shipped!
18856 @item
18857 Invoke @code{AC_CONFIG_TESTDIR}.
18859 @defmac AC_CONFIG_TESTDIR (@var{directory}, @dvar{test-path, directory})
18860 @acindex{CONFIG_TESTDIR}
18861 An Autotest test suite is to be configured in @var{directory}.  This
18862 macro requires the instantiation of @file{@var{directory}/atconfig} from
18863 @file{@var{directory}/atconfig.in}, and sets the default
18864 @code{AUTOTEST_PATH} to @var{test-path} (@pxref{testsuite Invocation}).
18865 @end defmac
18867 @item
18868 Still within @file{configure.ac}, as appropriate, ensure that some
18869 @code{AC_CONFIG_FILES} command includes substitution for
18870 @file{tests/atlocal}.
18872 @item
18873 The @file{tests/Makefile.in} should be modified so the validation in
18874 your package is triggered by @samp{make check}.  An example is provided
18875 below.
18876 @end itemize
18878 With Automake, here is a minimal example about how to link @samp{make
18879 check} with a validation suite.
18881 @example
18882 EXTRA_DIST = testsuite.at $(TESTSUITE) atlocal.in
18883 TESTSUITE = $(srcdir)/testsuite
18885 check-local: atconfig atlocal $(TESTSUITE)
18886         $(SHELL) '$(TESTSUITE)' $(TESTSUITEFLAGS)
18888 installcheck-local: atconfig atlocal $(TESTSUITE)
18889         $(SHELL) '$(TESTSUITE)' AUTOTEST_PATH='$(bindir)' \
18890           $(TESTSUITEFLAGS)
18892 clean-local:
18893         test ! -f '$(TESTSUITE)' || \
18894          $(SHELL) '$(TESTSUITE)' --clean
18896 AUTOTEST = $(AUTOM4TE) --language=autotest
18897 $(TESTSUITE): $(srcdir)/testsuite.at
18898         $(AUTOTEST) -I '$(srcdir)' -o $@@.tmp $@@.at
18899         mv $@@.tmp $@@
18900 @end example
18902 You might want to list explicitly the dependencies, i.e., the list of
18903 the files @file{testsuite.at} includes.
18905 With strict Autoconf, you might need to add lines inspired from the
18906 following:
18908 @example
18909 subdir = tests
18911 atconfig: $(top_builddir)/config.status
18912         cd $(top_builddir) && \
18913            $(SHELL) ./config.status $(subdir)/$@@
18915 atlocal: $(srcdir)/atlocal.in $(top_builddir)/config.status
18916         cd $(top_builddir) && \
18917            $(SHELL) ./config.status $(subdir)/$@@
18918 @end example
18920 @noindent
18921 and manage to have @file{atconfig.in} and @code{$(EXTRA_DIST)}
18922 distributed.
18924 With all this in place, and if you have not initialized @samp{TESTSUITEFLAGS}
18925 within your makefile, you can fine-tune test suite execution with this variable,
18926 for example:
18928 @example
18929 make check TESTSUITEFLAGS='-v -d -x 75 -k AC_PROG_CC CFLAGS=-g'
18930 @end example
18934 @c =============================== Frequent Autoconf Questions, with answers
18936 @node FAQ
18937 @chapter Frequent Autoconf Questions, with answers
18939 Several questions about Autoconf come up occasionally.  Here some of them
18940 are addressed.
18942 @menu
18943 * Distributing::                Distributing @command{configure} scripts
18944 * Why GNU M4::                  Why not use the standard M4?
18945 * Bootstrapping::               Autoconf and @acronym{GNU} M4 require each other?
18946 * Why Not Imake::               Why @acronym{GNU} uses @command{configure} instead of Imake
18947 * Defining Directories::        Passing @code{datadir} to program
18948 * Autom4te Cache::              What is it?  Can I remove it?
18949 * Present But Cannot Be Compiled::  Compiler and Preprocessor Disagree
18950 @end menu
18952 @node Distributing
18953 @section Distributing @command{configure} Scripts
18954 @cindex License
18956 @display
18957 What are the restrictions on distributing @command{configure}
18958 scripts that Autoconf generates?  How does that affect my
18959 programs that use them?
18960 @end display
18962 There are no restrictions on how the configuration scripts that Autoconf
18963 produces may be distributed or used.  In Autoconf version 1, they were
18964 covered by the @acronym{GNU} General Public License.  We still encourage
18965 software authors to distribute their work under terms like those of the
18966 @acronym{GPL}, but doing so is not required to use Autoconf.
18968 Of the other files that might be used with @command{configure},
18969 @file{config.h.in} is under whatever copyright you use for your
18970 @file{configure.ac}.  @file{config.sub} and @file{config.guess} have an
18971 exception to the @acronym{GPL} when they are used with an Autoconf-generated
18972 @command{configure} script, which permits you to distribute them under the
18973 same terms as the rest of your package.  @file{install-sh} is from the X
18974 Consortium and is not copyrighted.
18976 @node Why GNU M4
18977 @section Why Require @acronym{GNU} M4?
18979 @display
18980 Why does Autoconf require @acronym{GNU} M4?
18981 @end display
18983 Many M4 implementations have hard-coded limitations on the size and
18984 number of macros that Autoconf exceeds.  They also lack several
18985 builtin macros that it would be difficult to get along without in a
18986 sophisticated application like Autoconf, including:
18988 @example
18989 m4_builtin
18990 m4_indir
18991 m4_bpatsubst
18992 __file__
18993 __line__
18994 @end example
18996 Autoconf requires version 1.4.5 or later of @acronym{GNU} M4.
18998 Since only software maintainers need to use Autoconf, and since @acronym{GNU}
18999 M4 is simple to configure and install, it seems reasonable to require
19000 @acronym{GNU} M4 to be installed also.  Many maintainers of @acronym{GNU} and
19001 other free software already have most of the @acronym{GNU} utilities
19002 installed, since they prefer them.
19004 @node Bootstrapping
19005 @section How Can I Bootstrap?
19006 @cindex Bootstrap
19008 @display
19009 If Autoconf requires @acronym{GNU} M4 and @acronym{GNU} M4 has an Autoconf
19010 @command{configure} script, how do I bootstrap?  It seems like a chicken
19011 and egg problem!
19012 @end display
19014 This is a misunderstanding.  Although @acronym{GNU} M4 does come with a
19015 @command{configure} script produced by Autoconf, Autoconf is not required
19016 in order to run the script and install @acronym{GNU} M4.  Autoconf is only
19017 required if you want to change the M4 @command{configure} script, which few
19018 people have to do (mainly its maintainer).
19020 @node Why Not Imake
19021 @section Why Not Imake?
19022 @cindex Imake
19024 @display
19025 Why not use Imake instead of @command{configure} scripts?
19026 @end display
19028 Several people have written addressing this question, so I include
19029 adaptations of their explanations here.
19031 The following answer is based on one written by Richard Pixley:
19033 @quotation
19034 Autoconf generated scripts frequently work on machines that it has
19035 never been set up to handle before.  That is, it does a good job of
19036 inferring a configuration for a new system.  Imake cannot do this.
19038 Imake uses a common database of host specific data.  For X11, this makes
19039 sense because the distribution is made as a collection of tools, by one
19040 central authority who has control over the database.
19042 @acronym{GNU} tools are not released this way.  Each @acronym{GNU} tool has a
19043 maintainer; these maintainers are scattered across the world.  Using a
19044 common database would be a maintenance nightmare.  Autoconf may appear
19045 to be this kind of database, but in fact it is not.  Instead of listing
19046 host dependencies, it lists program requirements.
19048 If you view the @acronym{GNU} suite as a collection of native tools, then the
19049 problems are similar.  But the @acronym{GNU} development tools can be
19050 configured as cross tools in almost any host+target permutation.  All of
19051 these configurations can be installed concurrently.  They can even be
19052 configured to share host independent files across hosts.  Imake doesn't
19053 address these issues.
19055 Imake templates are a form of standardization.  The @acronym{GNU} coding
19056 standards address the same issues without necessarily imposing the same
19057 restrictions.
19058 @end quotation
19061 Here is some further explanation, written by Per Bothner:
19063 @quotation
19064 One of the advantages of Imake is that it easy to generate large
19065 makefiles using the @samp{#include} and macro mechanisms of @command{cpp}.
19066 However, @code{cpp} is not programmable: it has limited conditional
19067 facilities, and no looping.  And @code{cpp} cannot inspect its
19068 environment.
19070 All of these problems are solved by using @code{sh} instead of
19071 @code{cpp}.  The shell is fully programmable, has macro substitution,
19072 can execute (or source) other shell scripts, and can inspect its
19073 environment.
19074 @end quotation
19077 Paul Eggert elaborates more:
19079 @quotation
19080 With Autoconf, installers need not assume that Imake itself is already
19081 installed and working well.  This may not seem like much of an advantage
19082 to people who are accustomed to Imake.  But on many hosts Imake is not
19083 installed or the default installation is not working well, and requiring
19084 Imake to install a package hinders the acceptance of that package on
19085 those hosts.  For example, the Imake template and configuration files
19086 might not be installed properly on a host, or the Imake build procedure
19087 might wrongly assume that all source files are in one big directory
19088 tree, or the Imake configuration might assume one compiler whereas the
19089 package or the installer needs to use another, or there might be a
19090 version mismatch between the Imake expected by the package and the Imake
19091 supported by the host.  These problems are much rarer with Autoconf,
19092 where each package comes with its own independent configuration
19093 processor.
19095 Also, Imake often suffers from unexpected interactions between
19096 @command{make} and the installer's C preprocessor.  The fundamental problem
19097 here is that the C preprocessor was designed to preprocess C programs,
19098 not makefiles.  This is much less of a problem with Autoconf,
19099 which uses the general-purpose preprocessor M4, and where the
19100 package's author (rather than the installer) does the preprocessing in a
19101 standard way.
19102 @end quotation
19105 Finally, Mark Eichin notes:
19107 @quotation
19108 Imake isn't all that extensible, either.  In order to add new features to
19109 Imake, you need to provide your own project template, and duplicate most
19110 of the features of the existing one.  This means that for a sophisticated
19111 project, using the vendor-provided Imake templates fails to provide any
19112 leverage---since they don't cover anything that your own project needs
19113 (unless it is an X11 program).
19115 On the other side, though:
19117 The one advantage that Imake has over @command{configure}:
19118 @file{Imakefile} files tend to be much shorter (likewise, less redundant)
19119 than @file{Makefile.in} files.  There is a fix to this, however---at least
19120 for the Kerberos V5 tree, we've modified things to call in common
19121 @file{post.in} and @file{pre.in} makefile fragments for the
19122 entire tree.  This means that a lot of common things don't have to be
19123 duplicated, even though they normally are in @command{configure} setups.
19124 @end quotation
19127 @node Defining Directories
19128 @section How Do I @code{#define} Installation Directories?
19130 @display
19131 My program needs library files, installed in @code{datadir} and
19132 similar.  If I use
19134 @example
19135 AC_DEFINE_UNQUOTED([DATADIR], [$datadir],
19136   [Define to the read-only architecture-independent
19137    data directory.])
19138 @end example
19140 @noindent
19141 I get
19143 @example
19144 #define DATADIR "$@{prefix@}/share"
19145 @end example
19146 @end display
19148 As already explained, this behavior is on purpose, mandated by the
19149 @acronym{GNU} Coding Standards, see @ref{Installation Directory
19150 Variables}.  There are several means to achieve a similar goal:
19152 @itemize @minus
19153 @item
19154 Do not use @code{AC_DEFINE} but use your makefile to pass the
19155 actual value of @code{datadir} via compilation flags.
19156 @xref{Installation Directory Variables}, for the details.
19158 @item
19159 This solution can be simplified when compiling a program: you may either
19160 extend the @code{CPPFLAGS}:
19162 @example
19163 CPPFLAGS = -DDATADIR='"$(datadir)"' @@CPPFLAGS@@
19164 @end example
19166 @noindent
19167 or create a dedicated header file:
19169 @example
19170 DISTCLEANFILES = datadir.h
19171 datadir.h: Makefile
19172         echo '#define DATADIR "$(datadir)"' >$@@
19173 @end example
19175 @item
19176 Use @code{AC_DEFINE} but have @command{configure} compute the literal
19177 value of @code{datadir} and others.  Many people have wrapped macros to
19178 automate this task.  For instance, the macro @code{AC_DEFINE_DIR} from
19179 the @uref{http://autoconf-archive.cryp.to/, Autoconf Macro
19180 Archive}.
19182 This solution does not conform to the @acronym{GNU} Coding Standards.
19184 @item
19185 Note that all the previous solutions hard wire the absolute name of
19186 these directories in the executables, which is not a good property.  You
19187 may try to compute the names relative to @code{prefix}, and try to
19188 find @code{prefix} at runtime, this way your package is relocatable.
19189 @end itemize
19192 @node Autom4te Cache
19193 @section What is @file{autom4te.cache}?
19195 @display
19196 What is this directory @file{autom4te.cache}?  Can I safely remove it?
19197 @end display
19199 In the @acronym{GNU} Build System, @file{configure.ac} plays a central
19200 role and is read by many tools: @command{autoconf} to create
19201 @file{configure}, @command{autoheader} to create @file{config.h.in},
19202 @command{automake} to create @file{Makefile.in}, @command{autoscan} to
19203 check the completeness of @file{configure.ac}, @command{autoreconf} to
19204 check the @acronym{GNU} Build System components that are used.  To
19205 ``read @file{configure.ac}'' actually means to compile it with M4,
19206 which can be a long process for complex @file{configure.ac}.
19208 This is why all these tools, instead of running directly M4, invoke
19209 @command{autom4te} (@pxref{autom4te Invocation}) which, while answering to
19210 a specific demand, stores additional information in
19211 @file{autom4te.cache} for future runs.  For instance, if you run
19212 @command{autoconf}, behind the scenes, @command{autom4te} also
19213 stores information for the other tools, so that when you invoke
19214 @command{autoheader} or @command{automake} etc., reprocessing
19215 @file{configure.ac} is not needed.  The speed up is frequently of 30%,
19216 and is increasing with the size of @file{configure.ac}.
19218 But it is and remains being simply a cache: you can safely remove it.
19220 @sp 1
19222 @display
19223 Can I permanently get rid of it?
19224 @end display
19226 The creation of this cache can be disabled from
19227 @file{~/.autom4te.cfg}, see @ref{Customizing autom4te}, for more
19228 details.  You should be aware that disabling the cache slows down the
19229 Autoconf test suite by 40%.  The more @acronym{GNU} Build System
19230 components are used, the more the cache is useful; for instance
19231 running @samp{autoreconf -f} on the Core Utilities is twice slower without
19232 the cache @emph{although @option{--force} implies that the cache is
19233 not fully exploited}, and eight times slower than without
19234 @option{--force}.
19237 @node Present But Cannot Be Compiled
19238 @section Header Present But Cannot Be Compiled
19240 The most important guideline to bear in mind when checking for
19241 features is to mimic as much as possible the intended use.
19242 Unfortunately, old versions of @code{AC_CHECK_HEADER} and
19243 @code{AC_CHECK_HEADERS} failed to follow this idea, and called
19244 the preprocessor, instead of the compiler, to check for headers.  As a
19245 result, incompatibilities between headers went unnoticed during
19246 configuration, and maintainers finally had to deal with this issue
19247 elsewhere.
19249 As of Autoconf 2.56 both checks are performed, and @code{configure}
19250 complains loudly if the compiler and the preprocessor do not agree.
19251 For the time being the result used is that of the preprocessor, to give
19252 maintainers time to adjust their @file{configure.ac}, but in the
19253 future, only the compiler will be considered.
19255 Consider the following example:
19257 @smallexample
19258 $ @kbd{cat number.h}
19259 typedef int number;
19260 $ @kbd{cat pi.h}
19261 const number pi = 3;
19262 $ @kbd{cat configure.ac}
19263 AC_INIT([Example], [1.0], [bug-example@@example.org])
19264 AC_CHECK_HEADERS([pi.h])
19265 $ @kbd{autoconf -Wall}
19266 $ @kbd{./configure}
19267 checking for gcc... gcc
19268 checking for C compiler default output file name... a.out
19269 checking whether the C compiler works... yes
19270 checking whether we are cross compiling... no
19271 checking for suffix of executables...
19272 checking for suffix of object files... o
19273 checking whether we are using the GNU C compiler... yes
19274 checking whether gcc accepts -g... yes
19275 checking for gcc option to accept ISO C89... none needed
19276 checking how to run the C preprocessor... gcc -E
19277 checking for grep that handles long lines and -e... grep
19278 checking for egrep... grep -E
19279 checking for ANSI C header files... yes
19280 checking for sys/types.h... yes
19281 checking for sys/stat.h... yes
19282 checking for stdlib.h... yes
19283 checking for string.h... yes
19284 checking for memory.h... yes
19285 checking for strings.h... yes
19286 checking for inttypes.h... yes
19287 checking for stdint.h... yes
19288 checking for unistd.h... yes
19289 checking pi.h usability... no
19290 checking pi.h presence... yes
19291 configure: WARNING: pi.h: present but cannot be compiled
19292 configure: WARNING: pi.h:     check for missing prerequisite headers?
19293 configure: WARNING: pi.h: see the Autoconf documentation
19294 configure: WARNING: pi.h:     section "Present But Cannot Be Compiled"
19295 configure: WARNING: pi.h: proceeding with the preprocessor's result
19296 configure: WARNING: pi.h: in the future, the compiler will take precedence
19297 configure: WARNING:     ## -------------------------------------- ##
19298 configure: WARNING:     ## Report this to bug-example@@example.org ##
19299 configure: WARNING:     ## -------------------------------------- ##
19300 checking for pi.h... yes
19301 @end smallexample
19303 @noindent
19304 The proper way the handle this case is using the fourth argument
19305 (@pxref{Generic Headers}):
19307 @example
19308 $ @kbd{cat configure.ac}
19309 AC_INIT([Example], [1.0], [bug-example@@example.org])
19310 AC_CHECK_HEADERS([number.h pi.h], [], [],
19311 [[#ifdef HAVE_NUMBER_H
19312 # include <number.h>
19313 #endif
19315 $ @kbd{autoconf -Wall}
19316 $ @kbd{./configure}
19317 checking for gcc... gcc
19318 checking for C compiler default output... a.out
19319 checking whether the C compiler works... yes
19320 checking whether we are cross compiling... no
19321 checking for suffix of executables...
19322 checking for suffix of object files... o
19323 checking whether we are using the GNU C compiler... yes
19324 checking whether gcc accepts -g... yes
19325 checking for gcc option to accept ANSI C... none needed
19326 checking for number.h... yes
19327 checking for pi.h... yes
19328 @end example
19330 See @ref{Particular Headers}, for a list of headers with their
19331 prerequisite.
19333 @c ===================================================== History of Autoconf.
19335 @node History
19336 @chapter History of Autoconf
19337 @cindex History of autoconf
19339 You may be wondering, Why was Autoconf originally written?  How did it
19340 get into its present form?  (Why does it look like gorilla spit?)  If
19341 you're not wondering, then this chapter contains no information useful
19342 to you, and you might as well skip it.  If you @emph{are} wondering,
19343 then let there be light@enddots{}
19345 @menu
19346 * Genesis::                     Prehistory and naming of @command{configure}
19347 * Exodus::                      The plagues of M4 and Perl
19348 * Leviticus::                   The priestly code of portability arrives
19349 * Numbers::                     Growth and contributors
19350 * Deuteronomy::                 Approaching the promises of easy configuration
19351 @end menu
19353 @node Genesis
19354 @section Genesis
19356 In June 1991 I was maintaining many of the @acronym{GNU} utilities for the
19357 Free Software Foundation.  As they were ported to more platforms and
19358 more programs were added, the number of @option{-D} options that users
19359 had to select in the makefile (around 20) became burdensome.
19360 Especially for me---I had to test each new release on a bunch of
19361 different systems.  So I wrote a little shell script to guess some of
19362 the correct settings for the fileutils package, and released it as part
19363 of fileutils 2.0.  That @command{configure} script worked well enough that
19364 the next month I adapted it (by hand) to create similar @command{configure}
19365 scripts for several other @acronym{GNU} utilities packages.  Brian Berliner
19366 also adapted one of my scripts for his @acronym{CVS} revision control system.
19368 Later that summer, I learned that Richard Stallman and Richard Pixley
19369 were developing similar scripts to use in the @acronym{GNU} compiler tools;
19370 so I adapted my @command{configure} scripts to support their evolving
19371 interface: using the file name @file{Makefile.in} as the templates;
19372 adding @samp{+srcdir}, the first option (of many); and creating
19373 @file{config.status} files.
19375 @node Exodus
19376 @section Exodus
19378 As I got feedback from users, I incorporated many improvements, using
19379 Emacs to search and replace, cut and paste, similar changes in each of
19380 the scripts.  As I adapted more @acronym{GNU} utilities packages to use
19381 @command{configure} scripts, updating them all by hand became impractical.
19382 Rich Murphey, the maintainer of the @acronym{GNU} graphics utilities, sent me
19383 mail saying that the @command{configure} scripts were great, and asking if
19384 I had a tool for generating them that I could send him.  No, I thought,
19385 but I should!  So I started to work out how to generate them.  And the
19386 journey from the slavery of hand-written @command{configure} scripts to the
19387 abundance and ease of Autoconf began.
19389 Cygnus @command{configure}, which was being developed at around that time,
19390 is table driven; it is meant to deal mainly with a discrete number of
19391 system types with a small number of mainly unguessable features (such as
19392 details of the object file format).  The automatic configuration system
19393 that Brian Fox had developed for Bash takes a similar approach.  For
19394 general use, it seems to me a hopeless cause to try to maintain an
19395 up-to-date database of which features each variant of each operating
19396 system has.  It's easier and more reliable to check for most features on
19397 the fly---especially on hybrid systems that people have hacked on
19398 locally or that have patches from vendors installed.
19400 I considered using an architecture similar to that of Cygnus
19401 @command{configure}, where there is a single @command{configure} script that
19402 reads pieces of @file{configure.in} when run.  But I didn't want to have
19403 to distribute all of the feature tests with every package, so I settled
19404 on having a different @command{configure} made from each
19405 @file{configure.in} by a preprocessor.  That approach also offered more
19406 control and flexibility.
19408 I looked briefly into using the Metaconfig package, by Larry Wall,
19409 Harlan Stenn, and Raphael Manfredi, but I decided not to for several
19410 reasons.  The @command{Configure} scripts it produces are interactive,
19411 which I find quite inconvenient; I didn't like the ways it checked for
19412 some features (such as library functions); I didn't know that it was
19413 still being maintained, and the @command{Configure} scripts I had
19414 seen didn't work on many modern systems (such as System V R4 and NeXT);
19415 it wasn't flexible in what it could do in response to a feature's
19416 presence or absence; I found it confusing to learn; and it was too big
19417 and complex for my needs (I didn't realize then how much Autoconf would
19418 eventually have to grow).
19420 I considered using Perl to generate my style of @command{configure}
19421 scripts, but decided that M4 was better suited to the job of simple
19422 textual substitutions: it gets in the way less, because output is
19423 implicit.  Plus, everyone already has it.  (Initially I didn't rely on
19424 the @acronym{GNU} extensions to M4.)  Also, some of my friends at the
19425 University of Maryland had recently been putting M4 front ends on
19426 several programs, including @code{tvtwm}, and I was interested in trying
19427 out a new language.
19429 @node Leviticus
19430 @section Leviticus
19432 Since my @command{configure} scripts determine the system's capabilities
19433 automatically, with no interactive user intervention, I decided to call
19434 the program that generates them Autoconfig.  But with a version number
19435 tacked on, that name would be too long for old Unix file systems,
19436 so I shortened it to Autoconf.
19438 In the fall of 1991 I called together a group of fellow questers after
19439 the Holy Grail of portability (er, that is, alpha testers) to give me
19440 feedback as I encapsulated pieces of my handwritten scripts in M4 macros
19441 and continued to add features and improve the techniques used in the
19442 checks.  Prominent among the testers were Fran@,{c}ois Pinard, who came up
19443 with the idea of making an Autoconf shell script to run M4
19444 and check for unresolved macro calls; Richard Pixley, who suggested
19445 running the compiler instead of searching the file system to find
19446 include files and symbols, for more accurate results; Karl Berry, who
19447 got Autoconf to configure @TeX{} and added the macro index to the
19448 documentation; and Ian Lance Taylor, who added support for creating a C
19449 header file as an alternative to putting @option{-D} options in a
19450 makefile, so he could use Autoconf for his @acronym{UUCP} package.
19451 The alpha testers cheerfully adjusted their files again and again as the
19452 names and calling conventions of the Autoconf macros changed from
19453 release to release.  They all contributed many specific checks, great
19454 ideas, and bug fixes.
19456 @node Numbers
19457 @section Numbers
19459 In July 1992, after months of alpha testing, I released Autoconf 1.0,
19460 and converted many @acronym{GNU} packages to use it.  I was surprised by how
19461 positive the reaction to it was.  More people started using it than I
19462 could keep track of, including people working on software that wasn't
19463 part of the @acronym{GNU} Project (such as TCL, FSP, and Kerberos V5).
19464 Autoconf continued to improve rapidly, as many people using the
19465 @command{configure} scripts reported problems they encountered.
19467 Autoconf turned out to be a good torture test for M4 implementations.
19468 Unix M4 started to dump core because of the length of the
19469 macros that Autoconf defined, and several bugs showed up in @acronym{GNU}
19470 M4 as well.  Eventually, we realized that we needed to use some
19471 features that only @acronym{GNU} M4 has.  4.3@acronym{BSD} M4, in
19472 particular, has an impoverished set of builtin macros; the System V
19473 version is better, but still doesn't provide everything we need.
19475 More development occurred as people put Autoconf under more stresses
19476 (and to uses I hadn't anticipated).  Karl Berry added checks for X11.
19477 david zuhn contributed C++ support.  Fran@,{c}ois Pinard made it diagnose
19478 invalid arguments.  Jim Blandy bravely coerced it into configuring
19479 @acronym{GNU} Emacs, laying the groundwork for several later improvements.
19480 Roland McGrath got it to configure the @acronym{GNU} C Library, wrote the
19481 @command{autoheader} script to automate the creation of C header file
19482 templates, and added a @option{--verbose} option to @command{configure}.
19483 Noah Friedman added the @option{--autoconf-dir} option and
19484 @code{AC_MACRODIR} environment variable.  (He also coined the term
19485 @dfn{autoconfiscate} to mean ``adapt a software package to use
19486 Autoconf''.)  Roland and Noah improved the quoting protection in
19487 @code{AC_DEFINE} and fixed many bugs, especially when I got sick of
19488 dealing with portability problems from February through June, 1993.
19490 @node Deuteronomy
19491 @section Deuteronomy
19493 A long wish list for major features had accumulated, and the effect of
19494 several years of patching by various people had left some residual
19495 cruft.  In April 1994, while working for Cygnus Support, I began a major
19496 revision of Autoconf.  I added most of the features of the Cygnus
19497 @command{configure} that Autoconf had lacked, largely by adapting the
19498 relevant parts of Cygnus @command{configure} with the help of david zuhn
19499 and Ken Raeburn.  These features include support for using
19500 @file{config.sub}, @file{config.guess}, @option{--host}, and
19501 @option{--target}; making links to files; and running @command{configure}
19502 scripts in subdirectories.  Adding these features enabled Ken to convert
19503 @acronym{GNU} @code{as}, and Rob Savoye to convert Deja@acronym{GNU}, to using
19504 Autoconf.
19506 I added more features in response to other peoples' requests.  Many
19507 people had asked for @command{configure} scripts to share the results of
19508 the checks between runs, because (particularly when configuring a large
19509 source tree, like Cygnus does) they were frustratingly slow.  Mike
19510 Haertel suggested adding site-specific initialization scripts.  People
19511 distributing software that had to unpack on MS-DOS asked for a way to
19512 override the @file{.in} extension on the file names, which produced file
19513 names like @file{config.h.in} containing two dots.  Jim Avera did an
19514 extensive examination of the problems with quoting in @code{AC_DEFINE}
19515 and @code{AC_SUBST}; his insights led to significant improvements.
19516 Richard Stallman asked that compiler output be sent to @file{config.log}
19517 instead of @file{/dev/null}, to help people debug the Emacs
19518 @command{configure} script.
19520 I made some other changes because of my dissatisfaction with the quality
19521 of the program.  I made the messages showing results of the checks less
19522 ambiguous, always printing a result.  I regularized the names of the
19523 macros and cleaned up coding style inconsistencies.  I added some
19524 auxiliary utilities that I had developed to help convert source code
19525 packages to use Autoconf.  With the help of Fran@,{c}ois Pinard, I made
19526 the macros not interrupt each others' messages.  (That feature revealed
19527 some performance bottlenecks in @acronym{GNU} M4, which he hastily
19528 corrected!)  I reorganized the documentation around problems people want
19529 to solve.  And I began a test suite, because experience had shown that
19530 Autoconf has a pronounced tendency to regress when we change it.
19532 Again, several alpha testers gave invaluable feedback, especially
19533 Fran@,{c}ois Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn,
19534 and Mark Eichin.
19536 Finally, version 2.0 was ready.  And there was much rejoicing.  (And I
19537 have free time again.  I think.  Yeah, right.)
19540 @c ========================================================== Appendices
19542 @node Copying This Manual
19543 @appendix Copying This Manual
19544 @cindex License
19546 @menu
19547 * GNU Free Documentation License::  License for copying this manual
19548 @end menu
19550 @include fdl.texi
19552 @node Indices
19553 @appendix Indices
19555 @menu
19556 * Environment Variable Index::  Index of environment variables used
19557 * Output Variable Index::       Index of variables set in output files
19558 * Preprocessor Symbol Index::   Index of C preprocessor symbols defined
19559 * Autoconf Macro Index::        Index of Autoconf macros
19560 * M4 Macro Index::              Index of M4, M4sugar, and M4sh macros
19561 * Autotest Macro Index::        Index of Autotest macros
19562 * Program & Function Index::    Index of those with portability problems
19563 * Concept Index::               General index
19564 @end menu
19566 @node Environment Variable Index
19567 @appendixsec Environment Variable Index
19569 This is an alphabetical list of the environment variables that Autoconf
19570 checks.
19572 @printindex ev
19574 @node Output Variable Index
19575 @appendixsec Output Variable Index
19577 This is an alphabetical list of the variables that Autoconf can
19578 substitute into files that it creates, typically one or more
19579 makefiles.  @xref{Setting Output Variables}, for more information
19580 on how this is done.
19582 @printindex ov
19584 @node Preprocessor Symbol Index
19585 @appendixsec Preprocessor Symbol Index
19587 This is an alphabetical list of the C preprocessor symbols that the
19588 Autoconf macros define.  To work with Autoconf, C source code needs to
19589 use these names in @code{#if} or @code{#ifdef} directives.
19591 @printindex cv
19593 @node Autoconf Macro Index
19594 @appendixsec Autoconf Macro Index
19596 This is an alphabetical list of the Autoconf macros.
19597 @ifset shortindexflag
19598 To make the list easier to use, the macros are listed without their
19599 preceding @samp{AC_}.
19600 @end ifset
19602 @printindex AC
19604 @node M4 Macro Index
19605 @appendixsec M4 Macro Index
19607 This is an alphabetical list of the M4, M4sugar, and M4sh macros.
19608 @ifset shortindexflag
19609 To make the list easier to use, the macros are listed without their
19610 preceding @samp{m4_} or @samp{AS_}.
19611 @end ifset
19613 @printindex MS
19615 @node Autotest Macro Index
19616 @appendixsec Autotest Macro Index
19618 This is an alphabetical list of the Autotest macros.
19619 @ifset shortindexflag
19620 To make the list easier to use, the macros are listed without their
19621 preceding @samp{AT_}.
19622 @end ifset
19624 @printindex AT
19626 @node Program & Function Index
19627 @appendixsec Program and Function Index
19629 This is an alphabetical list of the programs and functions which
19630 portability is discussed in this document.
19632 @printindex pr
19634 @node Concept Index
19635 @appendixsec Concept Index
19637 This is an alphabetical list of the files, tools, and concepts
19638 introduced in this document.
19640 @printindex cp
19642 @bye
19644 @c  LocalWords:  texinfo setfilename autoconf texi settitle setchapternewpage
19645 @c  LocalWords:  setcontentsaftertitlepage finalout ARG ovar varname dvar acx
19646 @c  LocalWords:  makeinfo dvi defcodeindex ev ov CPP cv Autotest mv defindex fn
19647 @c  LocalWords:  shortindexflag iftex ifset acindex ACindex ifclear ahindex fu
19648 @c  LocalWords:  asindex MSindex atindex ATindex auindex hdrindex prindex FIXME
19649 @c  LocalWords:  msindex alloca fnindex Aaarg indices FSF's dircategory ifnames
19650 @c  LocalWords:  direntry autoscan autoreconf autoheader autoupdate config FDs
19651 @c  LocalWords:  testsuite titlepage Elliston Demaille vskip filll ifnottex hmm
19652 @c  LocalWords:  insertcopying Autoconf's detailmenu Automake Libtool Posix ois
19653 @c  LocalWords:  Systemology Checkpointing Changequote INTERCAL changequote dfn
19654 @c  LocalWords:  Quadrigraphs builtins Shellology acconfig Bugward LIBOBJ Imake
19655 @c  LocalWords:  LIBOBJS IFELSE cindex flushright Pinard Metaconfig uref Simons
19656 @c  LocalWords:  distclean uninstall noindent versioning Tromey dir
19657 @c  LocalWords:  SAMS samp aclocal acsite underquoted emph itemx prepend SUBST
19658 @c  LocalWords:  evindex automake Gettext autopoint gettext symlink libtoolize
19659 @c  LocalWords:  defmac INIT tarname ovindex cvindex BUGREPORT PREREQ asis PROG
19660 @c  LocalWords:  SRCDIR srcdir globbing afterwards cmds foos fooo foooo init cd
19661 @c  LocalWords:  builddir timestamp src Imakefile chmod defvar CFLAGS CPPFLAGS
19662 @c  LocalWords:  CXXFLAGS DEFS DHAVE defvarx FCFLAGS FFLAGS LDFLAGS bindir GCC
19663 @c  LocalWords:  datadir datarootdir docdir dvidir htmldir libdir ifnothtml kbd
19664 @c  LocalWords:  includedir infodir libexecdir localedir localstatedir mandir
19665 @c  LocalWords:  oldincludedir pdfdir PDF psdir PostScript sbindir sysconfdir
19666 @c  LocalWords:  sharedstatedir DDATADIR sed tmp pkgdatadir VPATH conf unistd
19667 @c  LocalWords:  undef endif builtin FUNCS ifndef STACKSEG getb GETB YMP fubar
19668 @c  LocalWords:  PRE dest SUBDIRS subdirs fi struct STDC stdlib stddef INTTYPES
19669 @c  LocalWords:  inttypes STDINT stdint AWK AIX Solaris NeXT env EGREP FGREP yy
19670 @c  LocalWords:  LEXLIB YYTEXT lfl nonportable Automake's LN RANLIB byacc INETD
19671 @c  LocalWords:  inetd prog PROGS progs ranlib lmp lXt lX nsl gethostbyname UX
19672 @c  LocalWords:  NextStep isinf isnan glibc IRIX sunmath lm lsunmath pre sizeof
19673 @c  LocalWords:  ld inline malloc putenv setenv FreeBSD realloc SunOS MinGW
19674 @c  LocalWords:  snprintf vsnprintf sprintf vsprintf sscanf gcc strerror ifdef
19675 @c  LocalWords:  strnlen sysconf PAGESIZE unsetenv va fallback memcpy dst FUNC
19676 @c  LocalWords:  PowerPC GNUC libPW pragma Olibcalls CHOWN chown CLOSEDIR VFORK
19677 @c  LocalWords:  closedir FNMATCH fnmatch vfork FSEEKO LARGEFILE fseeko SVR sc
19678 @c  LocalWords:  largefile GETGROUPS getgroups GETLOADAVG DGUX UMAX NLIST KMEM
19679 @c  LocalWords:  SETGID getloadavg nlist GETMNTENT irix
19680 @c  LocalWords:  getmntent UnixWare GETPGRP getpgid getpgrp Posix's pid LSTAT
19681 @c  LocalWords:  lstat rpl MEMCMP memcmp OpenStep MBRTOWC mbrtowc MKTIME mktime
19682 @c  LocalWords:  localtime MMAP mmap OBSTACK obstack obstacks ARGTYPES timeval
19683 @c  LocalWords:  SETPGRP setpgrp defmacx Hurd SETVBUF setvbuf STRCOLL strcoll
19684 @c  LocalWords:  STRTOD strtod DECL STRFTIME strftime SCO UTIME utime VPRINTF
19685 @c  LocalWords:  DOPRNT vprintf doprnt sp unfixable LIBSOURCE LIBSOURCES Eggert
19686 @c  LocalWords:  linux netinet ia Tru XFree DIRENT NDIR dirent ndir multitable
19687 @c  LocalWords:  NAMLEN strlen namlen MKDEV SYSMACROS makedev RESOLV resolv DNS
19688 @c  LocalWords:  inet structs NAMESER arpa NETDB netdb UTekV UTS GCC's kB
19689 @c  LocalWords:  STDBOOL BOOL stdbool conformant cplusplus bool Bool stdarg tm
19690 @c  LocalWords:  ctype strchr strrchr rindex bcopy memmove memchr WEXITSTATUS
19691 @c  LocalWords:  WIFEXITED TIOCGWINSZ GWINSZ termios preprocess preprocessable
19692 @c  LocalWords:  DECLS strdup calloc BLKSIZE blksize RDEV rdev TZNAME tzname pw
19693 @c  LocalWords:  passwd gecos pwd MBSTATE mbstate wchar RETSIGTYPE hup UID uid
19694 @c  LocalWords:  gid ptrdiff uintmax EXEEXT OBJEXT Ae conftest AXP str
19695 @c  LocalWords:  ALIGNOF WERROR Werror cpp HP's WorkShop egcs un fied stdc CXX
19696 @c  LocalWords:  varargs BIGENDIAN Endianness SPARC endianness grep'ed CONST FC
19697 @c  LocalWords:  const STRINGIZE stringizing PARAMS unprotoize protos KCC cxx
19698 @c  LocalWords:  xlC aCC CXXCPP FREEFORM xlf FLIBS FCLIBS ish SRCEXT XTRA LFS
19699 @c  LocalWords:  ISC lcposix MINIX Minix conditionalized inlines hw dD confdefs
19700 @c  LocalWords:  fputs stdout PREPROC ar UFS HFS QNX realtime fstype STATVFS se
19701 @c  LocalWords:  statvfs STATFS statfs func machfile hdr lelf raboof DEFUN GTK
19702 @c  LocalWords:  GTKMM Grmph ified ine defn baz EOF qar Ahhh changecom algol io
19703 @c  LocalWords:  changeword quadrigraphs quadrigraph dnl SGI atoi overquoting
19704 @c  LocalWords:  Aas Wcross sep args namespace undefine bpatsubst popdef dquote
19705 @c  LocalWords:  bregexp Overquote overquotation meisch maisch meische maische
19706 @c  LocalWords:  miscian DIRNAME dirname MKDIR CATFILE XMKMF TRAVOLTA celsius
19707 @c  LocalWords:  EMX emxos Emacsen Korn DYNIX subshell posix Ksh ksh Pdksh Zsh
19708 @c  LocalWords:  pdksh zsh Allbery Lipe Kubota UWS zorglub stderr eval esac lfn
19709 @c  LocalWords:  drivespec Posixy DJGPP doschk prettybird LPT pfew Zsh's yu yaa
19710 @c  LocalWords:  yM uM aM firebird IP subdir misparses ok Unpatched abc bc zA
19711 @c  LocalWords:  CDPATH DUALCASE LINENO prepass Subshells lineno NULLCMD cmp wc
19712 @c  LocalWords:  MAILPATH scanset arg NetBSD Almquist printf expr cp
19713 @c  LocalWords:  Oliva awk Aaaaarg cmd regex xfoo GNV OpenVMS VM
19714 @c  LocalWords:  sparc Proulx nbar nfoo maxdepth acdilrtu TWG mc
19715 @c  LocalWords:  mkdir exe uname OpenBSD Fileutils mktemp umask TMPDIR guid os
19716 @c  LocalWords:  fooXXXXXX Unicos utimes hpux hppa unescaped
19717 @c  LocalWords:  pmake DOS's gmake ifoo DESTDIR autoconfiscated pc coff mips gg
19718 @c  LocalWords:  dec ultrix cpu wildcards rpcc rdtsc powerpc readline
19719 @c  LocalWords:  withval vxworks gless localcache usr LOFF loff CYGWIN Cygwin
19720 @c  LocalWords:  cygwin SIGLIST siglist SYSNDIR SYSDIR ptx lseq rusage elif MSC
19721 @c  LocalWords:  lfoo POUNDBANG lsun NIS getpwnam SYSCALLS RSH INTL lintl aix
19722 @c  LocalWords:  intl lx ldir syslog bsd EPI toolchain netbsd objext de KNR nn
19723 @c  LocalWords:  fication LTLIBOBJS Wdiff TESTDIR atconfig atlocal akim XFAIL
19724 @c  LocalWords:  ChangeLog prepended errexit smallexample TESTSUITEFLAGS GPL er
19725 @c  LocalWords:  installcheck autotest indir Pixley Bothner Eichin Kerberos adl
19726 @c  LocalWords:  DISTCLEANFILES preprocessor's fileutils Stallman Murphey Stenn
19727 @c  LocalWords:  Manfredi Autoconfig TCL FSP david zuhn Blandy MACRODIR Raeburn
19728 @c  LocalWords:  autoconfiscate Savoye Haertel Avera Meyering fdl appendixsec
19729 @c  LocalWords:  printindex american LIBOBJDIR LibdirTest ERLCFLAGS OBJCFLAGS
19730 @c  LocalWords:  VER Gnulib online xyes strcpy TYPEOF typeof OBJC objcc objc ln
19731 @c  LocalWords:  GOBJC OTP ERLC erl valloc decr dumpdef errprint incr
19732 @c  LocalWords:  esyscmd len maketemp pushdef substr syscmd sysval translit txt
19733 @c  LocalWords:  sinclude foreach myvar tolower toupper uniq BASENAME STDIN
19734 @c  LocalWords:  Dynix descrips basename aname cname macroexpands xno xcheck
19735 @c  LocalWords:  LIBREADLINE lreadline lncurses libreadline
19737 @c Local Variables:
19738 @c fill-column: 72
19739 @c ispell-local-dictionary: "american"
19740 @c indent-tabs-mode: nil
19741 @c whitespace-check-buffer-indent: nil
19742 @c End: