* NEWS: Recommend M4 1.4.7 instead of 1.4.6.
[autoconf/tsuna.git] / doc / autoconf.texi
blobb155edff68a449f3582e3e271a56a1f148601ebf
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 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: (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 configure.ac::        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 * configure.ac 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 Substitutions::         Variable and command expansions
477 * Assignments::                 Varying side effects of assignments
478 * Parentheses::                 Parentheses in shell scripts
479 * Slashes::                     Slashes in shell scripts
480 * Special Shell Variables::     Variables you should not change
481 * Limitations of Builtins::     Portable use of not so portable /bin/sh
482 * Limitations of Usual Tools::  Portable use of portable tools
484 Portable Make Programming
486 * $< in Ordinary Make Rules::   $< in ordinary rules
487 * Failure in Make Rules::       Failing portably in rules
488 * Special Chars in Names::      Special Characters in Macro Names
489 * Backslash-Newline-Newline::   Empty last lines in macro definitions
490 * Backslash-Newline Comments::  Spanning comments across line boundaries
491 * Long Lines in Makefiles::     Line length limitations
492 * Macros and Submakes::         @code{make macro=value} and submakes
493 * The Make Macro MAKEFLAGS::    @code{$(MAKEFLAGS)} portability issues
494 * The Make Macro SHELL::        @code{$(SHELL)} portability issues
495 * Comments in Make Rules::      Other problems with Make comments
496 * obj/ and Make::               Don't name a subdirectory @file{obj}
497 * make -k Status::              Exit status of @samp{make -k}
498 * VPATH and Make::              @code{VPATH} woes
499 * Single Suffix Rules::         Single suffix rules and separated dependencies
500 * Timestamps and Make::         Subsecond timestamp resolution
502 @code{VPATH} and Make
504 * VPATH and Double-colon::      Problems with @samp{::} on ancient hosts
505 * $< in Explicit Rules::        @code{$<} does not work in ordinary rules
506 * Automatic Rule Rewriting::    @code{VPATH} goes wild on Solaris
507 * Tru64 Directory Magic::       @command{mkdir} goes wild on Tru64
508 * Make Target Lookup::          More details about @code{VPATH} lookup
510 Portable C and C++ Programming
512 * Varieties of Unportability::  How to make your programs unportable
513 * Integer Overflow::            When integers get too large
514 * Null Pointers::               Properties of null pointers
515 * Buffer Overruns::             Subscript errors and the like
516 * Volatile Objects::            @code{volatile} and signals
517 * Floating Point Portability::  Portable floating-point arithmetic
518 * Exiting Portably::            Exiting and the exit status
520 Manual Configuration
522 * Specifying Names::            Specifying the system type
523 * Canonicalizing::              Getting the canonical system type
524 * Using System Type::           What to do with the system type
526 Site Configuration
528 * Help Formatting::             Customizing @samp{configure --help}
529 * External Software::           Working with other optional software
530 * Package Options::             Selecting optional features
531 * Pretty Help Strings::         Formatting help string
532 * Site Details::                Configuring site details
533 * Transforming Names::          Changing program names when installing
534 * Site Defaults::               Giving @command{configure} local defaults
536 Transforming Program Names When Installing
538 * Transformation Options::      @command{configure} options to transform names
539 * Transformation Examples::     Sample uses of transforming names
540 * Transformation Rules::        Makefile uses of transforming names
542 Running @command{configure} Scripts
544 * Basic Installation::          Instructions for typical cases
545 * Compilers and Options::       Selecting compilers and optimization
546 * Multiple Architectures::      Compiling for multiple architectures at once
547 * Installation Names::          Installing in different directories
548 * Optional Features::           Selecting optional features
549 * System Type::                 Specifying the system type
550 * Sharing Defaults::            Setting site-wide defaults for @command{configure}
551 * Defining Variables::          Specifying the compiler etc.
552 * configure Invocation::        Changing how @command{configure} runs
554 Obsolete Constructs
556 * Obsolete config.status Use::  Different calling convention
557 * acconfig.h::                  Additional entries in @file{config.h.in}
558 * autoupdate Invocation::       Automatic update of @file{configure.ac}
559 * Obsolete Macros::             Backward compatibility macros
560 * Autoconf 1::                  Tips for upgrading your files
561 * Autoconf 2.13::               Some fresher tips
563 Upgrading From Version 1
565 * Changed File Names::          Files you might rename
566 * Changed Makefiles::           New things to put in @file{Makefile.in}
567 * Changed Macros::              Macro calls you might replace
568 * Changed Results::             Changes in how to check test results
569 * Changed Macro Writing::       Better ways to write your own macros
571 Upgrading From Version 2.13
573 * Changed Quotation::           Broken code which used to work
574 * New Macros::                  Interaction with foreign macros
575 * Hosts and Cross-Compilation::  Bugward compatibility kludges
576 * AC_LIBOBJ vs LIBOBJS::        LIBOBJS is a forbidden token
577 * AC_FOO_IFELSE vs AC_TRY_FOO::  A more generic scheme for testing sources
579 Generating Test Suites with Autotest
581 * Using an Autotest Test Suite::  Autotest and the user
582 * Writing testsuite.at::        Autotest macros
583 * testsuite Invocation::        Running @command{testsuite} scripts
584 * Making testsuite Scripts::    Using autom4te to create @command{testsuite}
586 Using an Autotest Test Suite
588 * testsuite Scripts::           The concepts of Autotest
589 * Autotest Logs::               Their contents
591 Frequent Autoconf Questions, with answers
593 * Distributing::                Distributing @command{configure} scripts
594 * Why GNU M4::                  Why not use the standard M4?
595 * Bootstrapping::               Autoconf and @acronym{GNU} M4 require each other?
596 * Why Not Imake::               Why @acronym{GNU} uses @command{configure} instead of Imake
597 * Defining Directories::        Passing @code{datadir} to program
598 * autom4te.cache::              What is it?  Can I remove it?
599 * Present But Cannot Be Compiled::  Compiler and Preprocessor Disagree
601 History of Autoconf
603 * Genesis::                     Prehistory and naming of @command{configure}
604 * Exodus::                      The plagues of M4 and Perl
605 * Leviticus::                   The priestly code of portability arrives
606 * Numbers::                     Growth and contributors
607 * Deuteronomy::                 Approaching the promises of easy configuration
609 Copying This Manual
611 * GNU Free Documentation License::  License for copying this manual
613 Indices
615 * Environment Variable Index::  Index of environment variables used
616 * Output Variable Index::       Index of variables set in output files
617 * Preprocessor Symbol Index::   Index of C preprocessor symbols defined
618 * Autoconf Macro Index::        Index of Autoconf macros
619 * M4 Macro Index::              Index of M4, M4sugar, and M4sh macros
620 * Autotest Macro Index::        Index of Autotest macros
621 * Program & Function Index::    Index of those with portability problems
622 * Concept Index::               General index
624 @end detailmenu
625 @end menu
627 @c ============================================================= Introduction.
629 @node Introduction
630 @chapter Introduction
631 @cindex Introduction
633 @flushright
634 A physicist, an engineer, and a computer scientist were discussing the
635 nature of God.  ``Surely a Physicist,'' said the physicist, ``because
636 early in the Creation, God made Light; and you know, Maxwell's
637 equations, the dual nature of electromagnetic waves, the relativistic
638 consequences@dots{}'' ``An Engineer!,'' said the engineer, ``because
639 before making Light, God split the Chaos into Land and Water; it takes a
640 hell of an engineer to handle that big amount of mud, and orderly
641 separation of solids from liquids@dots{}'' The computer scientist
642 shouted: ``And the Chaos, where do you think it was coming from, hmm?''
644 ---Anonymous
645 @end flushright
646 @c (via Franc,ois Pinard)
648 Autoconf is a tool for producing shell scripts that automatically
649 configure software source code packages to adapt to many kinds of
650 Posix-like systems.  The configuration scripts produced by Autoconf
651 are independent of Autoconf when they are run, so their users do not
652 need to have Autoconf.
654 The configuration scripts produced by Autoconf require no manual user
655 intervention when run; they do not normally even need an argument
656 specifying the system type.  Instead, they individually test for the
657 presence of each feature that the software package they are for might need.
658 (Before each check, they print a one-line message stating what they are
659 checking for, so the user doesn't get too bored while waiting for the
660 script to finish.)  As a result, they deal well with systems that are
661 hybrids or customized from the more common Posix variants.  There is
662 no need to maintain files that list the features supported by each
663 release of each variant of Posix.
665 For each software package that Autoconf is used with, it creates a
666 configuration script from a template file that lists the system features
667 that the package needs or can use.  After the shell code to recognize
668 and respond to a system feature has been written, Autoconf allows it to
669 be shared by many software packages that can use (or need) that feature.
670 If it later turns out that the shell code needs adjustment for some
671 reason, it needs to be changed in only one place; all of the
672 configuration scripts can be regenerated automatically to take advantage
673 of the updated code.
675 The Metaconfig package is similar in purpose to Autoconf, but the
676 scripts it produces require manual user intervention, which is quite
677 inconvenient when configuring large source trees.  Unlike Metaconfig
678 scripts, Autoconf scripts can support cross-compiling, if some care is
679 taken in writing them.
681 Autoconf does not solve all problems related to making portable
682 software packages---for a more complete solution, it should be used in
683 concert with other @acronym{GNU} build tools like Automake and
684 Libtool.  These other tools take on jobs like the creation of a
685 portable, recursive makefile with all of the standard targets,
686 linking of shared libraries, and so on.  @xref{The GNU Build System},
687 for more information.
689 Autoconf imposes some restrictions on the names of macros used with
690 @code{#if} in C programs (@pxref{Preprocessor Symbol Index}).
692 Autoconf requires @acronym{GNU} M4 in order to generate the scripts.  It uses
693 features that some versions of M4, including @acronym{GNU} M4 1.3,
694 do not have.  You should use version 1.4.7 or later of @acronym{GNU} M4.
696 @xref{Autoconf 1}, for information about upgrading from version 1.
697 @xref{History}, for the story of Autoconf's development.  @xref{FAQ},
698 for answers to some common questions about Autoconf.
700 See the @uref{http://www.gnu.org/software/autoconf/,
701 Autoconf web page} for up-to-date information, details on the mailing
702 lists, pointers to a list of known bugs, etc.
704 Mail suggestions to @email{autoconf@@gnu.org, the Autoconf mailing
705 list}.  Past suggestions are
706 @uref{http://lists.gnu.org/archive/html/autoconf/, archived}.
708 Mail bug reports to @email{bug-autoconf@@gnu.org, the
709 Autoconf Bugs mailing list}.  Past bug reports are
710 @uref{http://lists.gnu.org/archive/html/bug-autoconf/, archived}.
712 If possible, first check that your bug is
713 not already solved in current development versions, and that it has not
714 been reported yet.  Be sure to include all the needed information and a
715 short @file{configure.ac} that demonstrates the problem.
717 Autoconf's development tree is accessible via anonymous @acronym{CVS}; see the
718 @uref{http://savannah.gnu.org/projects/autoconf/, Autoconf
719 Summary} for details.  Patches relative to the
720 current @acronym{CVS} version can be sent for review to the
721 @email{autoconf-patches@@gnu.org, Autoconf Patches mailing list}.
722 Past patches are
723 @uref{http://lists.gnu.org/@/archive/@/html/@/autoconf-patches/, archived}.
725 Because of its mission, the Autoconf package itself
726 includes only a set of often-used
727 macros that have already demonstrated their usefulness.  Nevertheless,
728 if you wish to share your macros, or find existing ones, see the
729 @uref{http://autoconf-archive.cryp.to/, Autoconf Macro
730 Archive}, which is kindly run by @email{simons@@cryp.to,
731 Peter Simons}.
734 @c ================================================= The GNU Build System
736 @node The GNU Build System
737 @chapter The @acronym{GNU} Build System
738 @cindex @acronym{GNU} build system
740 Autoconf solves an important problem---reliable discovery of
741 system-specific build and runtime information---but this is only one
742 piece of the puzzle for the development of portable software.  To this
743 end, the @acronym{GNU} project has developed a suite of integrated
744 utilities to finish the job Autoconf started: the @acronym{GNU} build
745 system, whose most important components are Autoconf, Automake, and
746 Libtool.  In this chapter, we introduce you to those tools, point you
747 to sources of more information, and try to convince you to use the
748 entire @acronym{GNU} build system for your software.
750 @menu
751 * Automake::                    Escaping makefile hell
752 * Gnulib::                      The @acronym{GNU} portability library
753 * Libtool::                     Building libraries portably
754 * Pointers::                    More info on the @acronym{GNU} build system
755 @end menu
757 @node Automake
758 @section Automake
760 The ubiquity of @command{make} means that a makefile is almost the
761 only viable way to distribute automatic build rules for software, but
762 one quickly runs into its numerous limitations.  Its lack of
763 support for automatic dependency tracking, recursive builds in
764 subdirectories, reliable timestamps (e.g., for network file systems), and
765 so on, mean that developers must painfully (and often incorrectly)
766 reinvent the wheel for each project.  Portability is non-trivial, thanks
767 to the quirks of @command{make} on many systems.  On top of all this is the
768 manual labor required to implement the many standard targets that users
769 have come to expect (@code{make install}, @code{make distclean},
770 @code{make uninstall}, etc.).  Since you are, of course, using Autoconf,
771 you also have to insert repetitive code in your @code{Makefile.in} to
772 recognize @code{@@CC@@}, @code{@@CFLAGS@@}, and other substitutions
773 provided by @command{configure}.  Into this mess steps @dfn{Automake}.
774 @cindex Automake
776 Automake allows you to specify your build needs in a @code{Makefile.am}
777 file with a vastly simpler and more powerful syntax than that of a plain
778 makefile, and then generates a portable @code{Makefile.in} for
779 use with Autoconf.  For example, the @code{Makefile.am} to build and
780 install a simple ``Hello world'' program might look like:
782 @example
783 bin_PROGRAMS = hello
784 hello_SOURCES = hello.c
785 @end example
787 @noindent
788 The resulting @code{Makefile.in} (~400 lines) automatically supports all
789 the standard targets, the substitutions provided by Autoconf, automatic
790 dependency tracking, @code{VPATH} building, and so on.  @command{make}
791 builds the @code{hello} program, and @code{make install} installs it
792 in @file{/usr/local/bin} (or whatever prefix was given to
793 @command{configure}, if not @file{/usr/local}).
795 The benefits of Automake increase for larger packages (especially ones
796 with subdirectories), but even for small programs the added convenience
797 and portability can be substantial.  And that's not all@enddots{}
799 @node Gnulib
800 @section Gnulib
802 @acronym{GNU} software has a well-deserved reputation for running on
803 many different types of systems.  While our primary goal is to write
804 software for the @acronym{GNU} system, many users and developers have
805 been introduced to us through the systems that they were already using.
807 @cindex Gnulib
808 Gnulib is a central location for common @acronym{GNU} code, intended to
809 be shared among free software packages.  Its components are typically
810 shared at the source level, rather than being a library that gets built,
811 installed, and linked against.  The idea is to copy files from Gnulib
812 into your own source tree.  There is no distribution tarball; developers
813 should just grab source modules from the repository.  The source files
814 are available online, under various licenses, mostly @acronym{GNU}
815 @acronym{GPL} or @acronym{GNU} @acronym{LGPL}.
817 Gnulib modules typically contain C source code along with Autoconf
818 macros used to configure the source code.  For example, the Gnulib
819 @code{stdbool} module implements a @file{stdbool.h} header that nearly
820 conforms to C99, even on old-fashioned hosts that lack @file{stdbool.h}.
821 This module contains a source file for the replacement header, along
822 with an Autoconf macro that arranges to use the replacement header on
823 old-fashioned systems.
825 @node Libtool
826 @section Libtool
828 Often, one wants to build not only programs, but libraries, so that
829 other programs can benefit from the fruits of your labor.  Ideally, one
830 would like to produce @emph{shared} (dynamically linked) libraries,
831 which can be used by multiple programs without duplication on disk or in
832 memory and can be updated independently of the linked programs.
833 Producing shared libraries portably, however, is the stuff of
834 nightmares---each system has its own incompatible tools, compiler flags,
835 and magic incantations.  Fortunately, @acronym{GNU} provides a solution:
836 @dfn{Libtool}.
837 @cindex Libtool
839 Libtool handles all the requirements of building shared libraries for
840 you, and at this time seems to be the @emph{only} way to do so with any
841 portability.  It also handles many other headaches, such as: the
842 interaction of Make rules with the variable suffixes of
843 shared libraries, linking reliably with shared libraries before they are
844 installed by the superuser, and supplying a consistent versioning system
845 (so that different versions of a library can be installed or upgraded
846 without breaking binary compatibility).  Although Libtool, like
847 Autoconf, can be used without Automake, it is most simply utilized in
848 conjunction with Automake---there, Libtool is used automatically
849 whenever shared libraries are needed, and you need not know its syntax.
851 @node Pointers
852 @section Pointers
854 Developers who are used to the simplicity of @command{make} for small
855 projects on a single system might be daunted at the prospect of
856 learning to use Automake and Autoconf.  As your software is
857 distributed to more and more users, however, you otherwise
858 quickly find yourself putting lots of effort into reinventing the
859 services that the @acronym{GNU} build tools provide, and making the
860 same mistakes that they once made and overcame.  (Besides, since
861 you're already learning Autoconf, Automake is a piece of cake.)
863 There are a number of places that you can go to for more information on
864 the @acronym{GNU} build tools.
866 @itemize @minus
868 @item Web
870 The home pages for
871 @uref{http://www.gnu.org/@/software/@/autoconf/, Autoconf},
872 @uref{http://www.gnu.org/@/software/@/automake/, Automake},
873 @uref{http://www.gnu.org/@/software/@/gnulib/, Gnulib}, and
874 @uref{http://www.gnu.org/@/software/@/libtool/, Libtool}.
876 @item Automake Manual
878 @xref{Top, , Automake, automake, @acronym{GNU} Automake}, for more
879 information on Automake.
881 @item Books
883 The book @cite{@acronym{GNU} Autoconf, Automake and
884 Libtool}@footnote{@cite{@acronym{GNU} Autoconf, Automake and Libtool},
885 by G. V. Vaughan, B. Elliston, T. Tromey, and I. L. Taylor.  SAMS (originally
886 New Riders), 2000, ISBN 1578701902.} describes the complete @acronym{GNU}
887 build environment.  You can also find
888 @uref{http://sources.redhat.com/@/autobook/, the entire book on-line}.
890 @end itemize
892 @c ================================================= Making configure Scripts.
894 @node Making configure Scripts
895 @chapter Making @command{configure} Scripts
896 @cindex @file{aclocal.m4}
897 @cindex @command{configure}
899 The configuration scripts that Autoconf produces are by convention
900 called @command{configure}.  When run, @command{configure} creates several
901 files, replacing configuration parameters in them with appropriate
902 values.  The files that @command{configure} creates are:
904 @itemize @minus
905 @item
906 one or more @file{Makefile} files, usually one in each subdirectory of the
907 package (@pxref{Makefile Substitutions});
909 @item
910 optionally, a C header file, the name of which is configurable,
911 containing @code{#define} directives (@pxref{Configuration Headers});
913 @item
914 a shell script called @file{config.status} that, when run, recreates
915 the files listed above (@pxref{config.status Invocation});
917 @item
918 an optional shell script normally called @file{config.cache}
919 (created when using @samp{configure --config-cache}) that
920 saves the results of running many of the tests (@pxref{Cache Files});
922 @item
923 a file called @file{config.log} containing any messages produced by
924 compilers, to help debugging if @command{configure} makes a mistake.
925 @end itemize
927 @cindex @file{configure.in}
928 @cindex @file{configure.ac}
929 To create a @command{configure} script with Autoconf, you need to write an
930 Autoconf input file @file{configure.ac} (or @file{configure.in}) and run
931 @command{autoconf} on it.  If you write your own feature tests to
932 supplement those that come with Autoconf, you might also write files
933 called @file{aclocal.m4} and @file{acsite.m4}.  If you use a C header
934 file to contain @code{#define} directives, you might also run
935 @command{autoheader}, and you can distribute the generated file
936 @file{config.h.in} with the package.
938 Here is a diagram showing how the files that can be used in
939 configuration are produced.  Programs that are executed are suffixed by
940 @samp{*}.  Optional files are enclosed in square brackets (@samp{[]}).
941 @command{autoconf} and @command{autoheader} also read the installed Autoconf
942 macro files (by reading @file{autoconf.m4}).
944 @noindent
945 Files used in preparing a software package for distribution:
946 @example
947 your source files --> [autoscan*] --> [configure.scan] --> configure.ac
949 @group
950 configure.ac --.
951                |   .------> autoconf* -----> configure
952 [aclocal.m4] --+---+
953                |   `-----> [autoheader*] --> [config.h.in]
954 [acsite.m4] ---'
955 @end group
957 Makefile.in -------------------------------> Makefile.in
958 @end example
960 @noindent
961 Files used in configuring a software package:
962 @example
963 @group
964                        .-------------> [config.cache]
965 configure* ------------+-------------> config.log
966                        |
967 [config.h.in] -.       v            .-> [config.h] -.
968                +--> config.status* -+               +--> make*
969 Makefile.in ---'                    `-> Makefile ---'
970 @end group
971 @end example
973 @menu
974 * Writing configure.ac::        What to put in an Autoconf input file
975 * autoscan Invocation::         Semi-automatic @file{configure.ac} writing
976 * ifnames Invocation::          Listing the conditionals in source code
977 * autoconf Invocation::         How to create configuration scripts
978 * autoreconf Invocation::       Remaking multiple @command{configure} scripts
979 @end menu
981 @node Writing configure.ac
982 @section Writing @file{configure.ac}
984 To produce a @command{configure} script for a software package, create a
985 file called @file{configure.ac} that contains invocations of the
986 Autoconf macros that test the system features your package needs or can
987 use.  Autoconf macros already exist to check for many features; see
988 @ref{Existing Tests}, for their descriptions.  For most other features,
989 you can use Autoconf template macros to produce custom checks; see
990 @ref{Writing Tests}, for information about them.  For especially tricky
991 or specialized features, @file{configure.ac} might need to contain some
992 hand-crafted shell commands; see @ref{Portable Shell}.  The
993 @command{autoscan} program can give you a good start in writing
994 @file{configure.ac} (@pxref{autoscan Invocation}, for more information).
996 Previous versions of Autoconf promoted the name @file{configure.in},
997 which is somewhat ambiguous (the tool needed to process this file is not
998 described by its extension), and introduces a slight confusion with
999 @file{config.h.in} and so on (for which @samp{.in} means ``to be
1000 processed by @command{configure}'').  Using @file{configure.ac} is now
1001 preferred.
1003 @menu
1004 * Shell Script Compiler::       Autoconf as solution of a problem
1005 * Autoconf Language::           Programming in Autoconf
1006 * configure.ac Layout::         Standard organization of @file{configure.ac}
1007 @end menu
1009 @node Shell Script Compiler
1010 @subsection A Shell Script Compiler
1012 Just as for any other computer language, in order to properly program
1013 @file{configure.ac} in Autoconf you must understand @emph{what} problem
1014 the language tries to address and @emph{how} it does so.
1016 The problem Autoconf addresses is that the world is a mess.  After all,
1017 you are using Autoconf in order to have your package compile easily on
1018 all sorts of different systems, some of them being extremely hostile.
1019 Autoconf itself bears the price for these differences: @command{configure}
1020 must run on all those systems, and thus @command{configure} must limit itself
1021 to their lowest common denominator of features.
1023 Naturally, you might then think of shell scripts; who needs
1024 @command{autoconf}?  A set of properly written shell functions is enough to
1025 make it easy to write @command{configure} scripts by hand.  Sigh!
1026 Unfortunately, shell functions do not belong to the least common
1027 denominator; therefore, where you would like to define a function and
1028 use it ten times, you would instead need to copy its body ten times.
1030 So, what is really needed is some kind of compiler, @command{autoconf},
1031 that takes an Autoconf program, @file{configure.ac}, and transforms it
1032 into a portable shell script, @command{configure}.
1034 How does @command{autoconf} perform this task?
1036 There are two obvious possibilities: creating a brand new language or
1037 extending an existing one.  The former option is attractive: all
1038 sorts of optimizations could easily be implemented in the compiler and
1039 many rigorous checks could be performed on the Autoconf program
1040 (e.g., rejecting any non-portable construct).  Alternatively, you can
1041 extend an existing language, such as the @code{sh} (Bourne shell)
1042 language.
1044 Autoconf does the latter: it is a layer on top of @code{sh}.  It was
1045 therefore most convenient to implement @command{autoconf} as a macro
1046 expander: a program that repeatedly performs @dfn{macro expansions} on
1047 text input, replacing macro calls with macro bodies and producing a pure
1048 @code{sh} script in the end.  Instead of implementing a dedicated
1049 Autoconf macro expander, it is natural to use an existing
1050 general-purpose macro language, such as M4, and implement the extensions
1051 as a set of M4 macros.
1054 @node Autoconf Language
1055 @subsection The Autoconf Language
1056 @cindex quotation
1058 The Autoconf language differs from many other computer
1059 languages because it treats actual code the same as plain text.  Whereas
1060 in C, for instance, data and instructions have different syntactic
1061 status, in Autoconf their status is rigorously the same.  Therefore, we
1062 need a means to distinguish literal strings from text to be expanded:
1063 quotation.
1065 When calling macros that take arguments, there must not be any white
1066 space between the macro name and the open parenthesis.  Arguments should
1067 be enclosed within the M4 quote characters @samp{[} and @samp{]}, and be
1068 separated by commas.  Any leading blanks or newlines in arguments are ignored,
1069 unless they are quoted.  You should always quote an argument that
1070 might contain a macro name, comma, parenthesis, or a leading blank or
1071 newline.  This rule applies recursively for every macro
1072 call, including macros called from other macros.
1074 For instance:
1076 @example
1077 AC_CHECK_HEADER([stdio.h],
1078                 [AC_DEFINE([HAVE_STDIO_H], [1],
1079                    [Define to 1 if you have <stdio.h>.])],
1080                 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1081 @end example
1083 @noindent
1084 is quoted properly.  You may safely simplify its quotation to:
1086 @example
1087 AC_CHECK_HEADER([stdio.h],
1088                 [AC_DEFINE([HAVE_STDIO_H], 1,
1089                    [Define to 1 if you have <stdio.h>.])],
1090                 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1091 @end example
1093 @noindent
1094 because @samp{1} cannot contain a macro call.  Here, the argument of
1095 @code{AC_MSG_ERROR} must be quoted; otherwise, its comma would be
1096 interpreted as an argument separator.  Also, the second and third arguments
1097 of @samp{AC_CHECK_HEADER} must be quoted, since they contain
1098 macro calls.  The three arguments @samp{HAVE_STDIO_H}, @samp{stdio.h},
1099 and @samp{Define to 1 if you have <stdio.h>.} do not need quoting, but
1100 if you unwisely defined a macro with a name like @samp{Define} or
1101 @samp{stdio} then they would need quoting.  Cautious Autoconf users
1102 would keep the quotes, but many Autoconf users find such precautions
1103 annoying, and would rewrite the example as follows:
1105 @example
1106 AC_CHECK_HEADER(stdio.h,
1107                 [AC_DEFINE(HAVE_STDIO_H, 1,
1108                    [Define to 1 if you have <stdio.h>.])],
1109                 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1110 @end example
1112 @noindent
1113 This is safe, so long as you adopt good naming conventions and do not
1114 define macros with names like @samp{HAVE_STDIO_H}, @samp{stdio}, or
1115 @samp{h}.  Though it is also safe here to omit the quotes around
1116 @samp{Define to 1 if you have <stdio.h>.} this is not recommended, as
1117 message strings are more likely to inadvertently contain commas.
1119 The following example is wrong and dangerous, as it is underquoted:
1121 @example
1122 AC_CHECK_HEADER(stdio.h,
1123                 AC_DEFINE(HAVE_STDIO_H, 1,
1124                    Define to 1 if you have <stdio.h>.),
1125                 AC_MSG_ERROR([Sorry, can't do anything for you]))
1126 @end example
1128 In other cases, you may have to use text that also resembles a macro
1129 call.  You must quote that text even when it is not passed as a macro
1130 argument:
1132 @example
1133 echo "Hard rock was here!  --[AC_DC]"
1134 @end example
1136 @noindent
1137 which results in:
1139 @example
1140 echo "Hard rock was here!  --AC_DC"
1141 @end example
1143 @noindent
1144 When you use the same text in a macro argument, you must therefore have
1145 an extra quotation level (since one is stripped away by the macro
1146 substitution).  In general, then, it is a good idea to @emph{use double
1147 quoting for all literal string arguments}:
1149 @example
1150 AC_MSG_WARN([[AC_DC stinks  --Iron Maiden]])
1151 @end example
1153 You are now able to understand one of the constructs of Autoconf that
1154 has been continually misunderstood@dots{}  The rule of thumb is that
1155 @emph{whenever you expect macro expansion, expect quote expansion};
1156 i.e., expect one level of quotes to be lost.  For instance:
1158 @example
1159 AC_COMPILE_IFELSE([char b[10];], [], [AC_MSG_ERROR([you lose])])
1160 @end example
1162 @noindent
1163 is incorrect: here, the first argument of @code{AC_COMPILE_IFELSE} is
1164 @samp{char b[10];} and is expanded once, which results in
1165 @samp{char b10;}.  (There was an idiom common in Autoconf's past to
1166 address this issue via the M4 @code{changequote} primitive, but do not
1167 use it!)  Let's take a closer look: the author meant the first argument
1168 to be understood as a literal, and therefore it must be quoted twice:
1170 @example
1171 AC_COMPILE_IFELSE([[char b[10];]], [], [AC_MSG_ERROR([you lose])])
1172 @end example
1174 @noindent
1175 Voil@`a, you actually produce @samp{char b[10];} this time!
1177 On the other hand, descriptions (e.g., the last parameter of
1178 @code{AC_DEFINE} or @code{AS_HELP_STRING}) are not literals---they
1179 are subject to line breaking, for example---and should not be double quoted.
1180 Even if these descriptions are short and are not actually broken, double
1181 quoting them yields weird results.
1183 Some macros take optional arguments, which this documentation represents
1184 as @ovar{arg} (not to be confused with the quote characters).  You may
1185 just leave them empty, or use @samp{[]} to make the emptiness of the
1186 argument explicit, or you may simply omit the trailing commas.  The
1187 three lines below are equivalent:
1189 @example
1190 AC_CHECK_HEADERS([stdio.h], [], [], [])
1191 AC_CHECK_HEADERS([stdio.h],,,)
1192 AC_CHECK_HEADERS([stdio.h])
1193 @end example
1195 It is best to put each macro call on its own line in
1196 @file{configure.ac}.  Most of the macros don't add extra newlines; they
1197 rely on the newline after the macro call to terminate the commands.
1198 This approach makes the generated @command{configure} script a little
1199 easier to read by not inserting lots of blank lines.  It is generally
1200 safe to set shell variables on the same line as a macro call, because
1201 the shell allows assignments without intervening newlines.
1203 You can include comments in @file{configure.ac} files by starting them
1204 with the @samp{#}.  For example, it is helpful to begin
1205 @file{configure.ac} files with a line like this:
1207 @example
1208 # Process this file with autoconf to produce a configure script.
1209 @end example
1211 @node configure.ac Layout
1212 @subsection Standard @file{configure.ac} Layout
1214 The order in which @file{configure.ac} calls the Autoconf macros is not
1215 important, with a few exceptions.  Every @file{configure.ac} must
1216 contain a call to @code{AC_INIT} before the checks, and a call to
1217 @code{AC_OUTPUT} at the end (@pxref{Output}).  Additionally, some macros
1218 rely on other macros having been called first, because they check
1219 previously set values of some variables to decide what to do.  These
1220 macros are noted in the individual descriptions (@pxref{Existing
1221 Tests}), and they also warn you when @command{configure} is created if they
1222 are called out of order.
1224 To encourage consistency, here is a suggested order for calling the
1225 Autoconf macros.  Generally speaking, the things near the end of this
1226 list are those that could depend on things earlier in it.  For example,
1227 library functions could be affected by types and libraries.
1229 @display
1230 @group
1231 Autoconf requirements
1232 @code{AC_INIT(@var{package}, @var{version}, @var{bug-report-address})}
1233 information on the package
1234 checks for programs
1235 checks for libraries
1236 checks for header files
1237 checks for types
1238 checks for structures
1239 checks for compiler characteristics
1240 checks for library functions
1241 checks for system services
1242 @code{AC_CONFIG_FILES(@r{[}@var{file@dots{}}@r{]})}
1243 @code{AC_OUTPUT}
1244 @end group
1245 @end display
1248 @node autoscan Invocation
1249 @section Using @command{autoscan} to Create @file{configure.ac}
1250 @cindex @command{autoscan}
1252 The @command{autoscan} program can help you create and/or maintain a
1253 @file{configure.ac} file for a software package.  @command{autoscan}
1254 examines source files in the directory tree rooted at a directory given
1255 as a command line argument, or the current directory if none is given.
1256 It searches the source files for common portability problems and creates
1257 a file @file{configure.scan} which is a preliminary @file{configure.ac}
1258 for that package, and checks a possibly existing @file{configure.ac} for
1259 completeness.
1261 When using @command{autoscan} to create a @file{configure.ac}, you
1262 should manually examine @file{configure.scan} before renaming it to
1263 @file{configure.ac}; it probably needs some adjustments.
1264 Occasionally, @command{autoscan} outputs a macro in the wrong order
1265 relative to another macro, so that @command{autoconf} produces a warning;
1266 you need to move such macros manually.  Also, if you want the package to
1267 use a configuration header file, you must add a call to
1268 @code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers}).  You might
1269 also have to change or add some @code{#if} directives to your program in
1270 order to make it work with Autoconf (@pxref{ifnames Invocation}, for
1271 information about a program that can help with that job).
1273 When using @command{autoscan} to maintain a @file{configure.ac}, simply
1274 consider adding its suggestions.  The file @file{autoscan.log}
1275 contains detailed information on why a macro is requested.
1277 @command{autoscan} uses several data files (installed along with Autoconf)
1278 to determine which macros to output when it finds particular symbols in
1279 a package's source files.  These data files all have the same format:
1280 each line consists of a symbol, one or more blanks, and the Autoconf macro to
1281 output if that symbol is encountered.  Lines starting with @samp{#} are
1282 comments.
1284 @command{autoscan} accepts the following options:
1286 @table @option
1287 @item --help
1288 @itemx -h
1289 Print a summary of the command line options and exit.
1291 @item --version
1292 @itemx -V
1293 Print the version number of Autoconf and exit.
1295 @item --verbose
1296 @itemx -v
1297 Print the names of the files it examines and the potentially interesting
1298 symbols it finds in them.  This output can be voluminous.
1300 @item --include=@var{dir}
1301 @itemx -I @var{dir}
1302 Append @var{dir} to the include path.  Multiple invocations accumulate.
1304 @item --prepend-include=@var{dir}
1305 @item -B @var{dir}
1306 Prepend @var{dir} to the include path.  Multiple invocations accumulate.
1307 @end table
1309 @node ifnames Invocation
1310 @section Using @command{ifnames} to List Conditionals
1311 @cindex @command{ifnames}
1313 @command{ifnames} can help you write @file{configure.ac} for a software
1314 package.  It prints the identifiers that the package already uses in C
1315 preprocessor conditionals.  If a package has already been set up to have
1316 some portability, @command{ifnames} can thus help you figure out what its
1317 @command{configure} needs to check for.  It may help fill in some gaps in a
1318 @file{configure.ac} generated by @command{autoscan} (@pxref{autoscan
1319 Invocation}).
1321 @command{ifnames} scans all of the C source files named on the command line
1322 (or the standard input, if none are given) and writes to the standard
1323 output a sorted list of all the identifiers that appear in those files
1324 in @code{#if}, @code{#elif}, @code{#ifdef}, or @code{#ifndef}
1325 directives.  It prints each identifier on a line, followed by a
1326 space-separated list of the files in which that identifier occurs.
1328 @noindent
1329 @command{ifnames} accepts the following options:
1331 @table @option
1332 @item --help
1333 @itemx -h
1334 Print a summary of the command line options and exit.
1336 @item --version
1337 @itemx -V
1338 Print the version number of Autoconf and exit.
1339 @end table
1341 @node autoconf Invocation
1342 @section Using @command{autoconf} to Create @command{configure}
1343 @cindex @command{autoconf}
1345 To create @command{configure} from @file{configure.ac}, run the
1346 @command{autoconf} program with no arguments.  @command{autoconf} processes
1347 @file{configure.ac} with the M4 macro processor, using the
1348 Autoconf macros.  If you give @command{autoconf} an argument, it reads that
1349 file instead of @file{configure.ac} and writes the configuration script
1350 to the standard output instead of to @command{configure}.  If you give
1351 @command{autoconf} the argument @option{-}, it reads from the standard
1352 input instead of @file{configure.ac} and writes the configuration script
1353 to the standard output.
1355 The Autoconf macros are defined in several files.  Some of the files are
1356 distributed with Autoconf; @command{autoconf} reads them first.  Then it
1357 looks for the optional file @file{acsite.m4} in the directory that
1358 contains the distributed Autoconf macro files, and for the optional file
1359 @file{aclocal.m4} in the current directory.  Those files can contain
1360 your site's or the package's own Autoconf macro definitions
1361 (@pxref{Writing Autoconf Macros}, for more information).  If a macro is
1362 defined in more than one of the files that @command{autoconf} reads, the
1363 last definition it reads overrides the earlier ones.
1365 @command{autoconf} accepts the following options:
1367 @table @option
1368 @item --help
1369 @itemx -h
1370 Print a summary of the command line options and exit.
1372 @item --version
1373 @itemx -V
1374 Print the version number of Autoconf and exit.
1376 @item --verbose
1377 @itemx -v
1378 Report processing steps.
1380 @item --debug
1381 @itemx -d
1382 Don't remove the temporary files.
1384 @item --force
1385 @itemx -f
1386 Remake @file{configure} even if newer than its input files.
1388 @item --include=@var{dir}
1389 @itemx -I @var{dir}
1390 Append @var{dir} to the include path.  Multiple invocations accumulate.
1392 @item --prepend-include=@var{dir}
1393 @item -B @var{dir}
1394 Prepend @var{dir} to the include path.  Multiple invocations accumulate.
1396 @item --output=@var{file}
1397 @itemx -o @var{file}
1398 Save output (script or trace) to @var{file}.  The file @option{-} stands
1399 for the standard output.
1401 @item --warnings=@var{category}
1402 @itemx -W @var{category}
1403 @evindex WARNINGS
1404 Report the warnings related to @var{category} (which can actually be a
1405 comma separated list).  @xref{Reporting Messages}, macro
1406 @code{AC_DIAGNOSE}, for a comprehensive list of categories.  Special
1407 values include:
1409 @table @samp
1410 @item all
1411 report all the warnings
1413 @item none
1414 report none
1416 @item error
1417 treats warnings as errors
1419 @item no-@var{category}
1420 disable warnings falling into @var{category}
1421 @end table
1423 Warnings about @samp{syntax} are enabled by default, and the environment
1424 variable @env{WARNINGS}, a comma separated list of categories, is
1425 honored as well.  Passing @option{-W @var{category}} actually behaves as if
1426 you had passed @option{--warnings=syntax,$WARNINGS,@var{category}}.  If
1427 you want to disable the defaults and @env{WARNINGS}, but (for example)
1428 enable the warnings about obsolete constructs, you would use @option{-W
1429 none,obsolete}.
1431 @cindex Back trace
1432 @cindex Macro invocation stack
1433 Because @command{autoconf} uses @command{autom4te} behind the scenes, it
1434 displays a back trace for errors, but not for warnings; if you want
1435 them, just pass @option{-W error}.  @xref{autom4te Invocation}, for some
1436 examples.
1438 @item --trace=@var{macro}[:@var{format}]
1439 @itemx -t @var{macro}[:@var{format}]
1440 Do not create the @command{configure} script, but list the calls to
1441 @var{macro} according to the @var{format}.  Multiple @option{--trace}
1442 arguments can be used to list several macros.  Multiple @option{--trace}
1443 arguments for a single macro are not cumulative; instead, you should
1444 just make @var{format} as long as needed.
1446 The @var{format} is a regular string, with newlines if desired, and
1447 several special escape codes.  It defaults to @samp{$f:$l:$n:$%}; see
1448 @ref{autom4te Invocation}, for details on the @var{format}.
1450 @item --initialization
1451 @itemx -i
1452 By default, @option{--trace} does not trace the initialization of the
1453 Autoconf macros (typically the @code{AC_DEFUN} definitions).  This
1454 results in a noticeable speedup, but can be disabled by this option.
1455 @end table
1458 It is often necessary to check the content of a @file{configure.ac}
1459 file, but parsing it yourself is extremely fragile and error-prone.  It
1460 is suggested that you rely upon @option{--trace} to scan
1461 @file{configure.ac}.  For instance, to find the list of variables that
1462 are substituted, use:
1464 @example
1465 @group
1466 $ @kbd{autoconf -t AC_SUBST}
1467 configure.ac:2:AC_SUBST:ECHO_C
1468 configure.ac:2:AC_SUBST:ECHO_N
1469 configure.ac:2:AC_SUBST:ECHO_T
1470 @i{More traces deleted}
1471 @end group
1472 @end example
1474 @noindent
1475 The example below highlights the difference between @samp{$@@},
1476 @samp{$*}, and @samp{$%}.
1478 @example
1479 @group
1480 $ @kbd{cat configure.ac}
1481 AC_DEFINE(This, is, [an
1482 [example]])
1483 $ @kbd{autoconf -t 'AC_DEFINE:@@: $@@}
1484 *: $*
1485 %: $%'
1486 @@: [This],[is],[an
1487 [example]]
1488 *: This,is,an
1489 [example]
1490 %: This:is:an [example]
1491 @end group
1492 @end example
1494 @noindent
1495 The @var{format} gives you a lot of freedom:
1497 @example
1498 @group
1499 $ @kbd{autoconf -t 'AC_SUBST:$$ac_subst@{"$1"@} = "$f:$l";'}
1500 $ac_subst@{"ECHO_C"@} = "configure.ac:2";
1501 $ac_subst@{"ECHO_N"@} = "configure.ac:2";
1502 $ac_subst@{"ECHO_T"@} = "configure.ac:2";
1503 @i{More traces deleted}
1504 @end group
1505 @end example
1507 @noindent
1508 A long @var{separator} can be used to improve the readability of complex
1509 structures, and to ease their parsing (for instance when no single
1510 character is suitable as a separator):
1512 @example
1513 @group
1514 $ @kbd{autoconf -t 'AM_MISSING_PROG:$@{|:::::|@}*'}
1515 ACLOCAL|:::::|aclocal|:::::|$missing_dir
1516 AUTOCONF|:::::|autoconf|:::::|$missing_dir
1517 AUTOMAKE|:::::|automake|:::::|$missing_dir
1518 @i{More traces deleted}
1519 @end group
1520 @end example
1522 @node autoreconf Invocation
1523 @section Using @command{autoreconf} to Update @command{configure} Scripts
1524 @cindex @command{autoreconf}
1526 Installing the various components of the @acronym{GNU} Build System can be
1527 tedious: running @command{autopoint} for Gettext, @command{automake} for
1528 @file{Makefile.in} etc.@: in each directory.  It may be needed either
1529 because some tools such as @command{automake} have been updated on your
1530 system, or because some of the sources such as @file{configure.ac} have
1531 been updated, or finally, simply in order to install the @acronym{GNU} Build
1532 System in a fresh tree.
1534 @command{autoreconf} runs @command{autoconf}, @command{autoheader},
1535 @command{aclocal}, @command{automake}, @command{libtoolize}, and
1536 @command{autopoint} (when appropriate) repeatedly to update the
1537 @acronym{GNU} Build System in the specified directories and their
1538 subdirectories (@pxref{Subdirectories}).  By default, it only remakes
1539 those files that are older than their sources.
1541 If you install a new version of some tool, you can make
1542 @command{autoreconf} remake @emph{all} of the files by giving it the
1543 @option{--force} option.
1545 @xref{Automatic Remaking}, for Make rules to automatically
1546 remake @command{configure} scripts when their source files change.  That
1547 method handles the timestamps of configuration header templates
1548 properly, but does not pass @option{--autoconf-dir=@var{dir}} or
1549 @option{--localdir=@var{dir}}.
1551 @cindex Gettext
1552 @cindex @command{autopoint}
1553 Gettext supplies the @command{autopoint} command to add translation
1554 infrastructure to a source package.  If you use @command{autopoint},
1555 your @file{configure.ac} should invoke both @code{AM_GNU_GETTEXT} and
1556 @code{AM_GNU_GETTEXT_VERSION(@var{gettext-version})}.  @xref{autopoint
1557 Invocation, , Invoking the @code{autopoint} Program, gettext,
1558 @acronym{GNU} @code{gettext} utilities}, for further details.
1560 @noindent
1561 @command{autoreconf} accepts the following options:
1563 @table @option
1564 @item --help
1565 @itemx -h
1566 Print a summary of the command line options and exit.
1568 @item --version
1569 @itemx -V
1570 Print the version number of Autoconf and exit.
1572 @item --verbose
1573 Print the name of each directory @command{autoreconf} examines and the
1574 commands it runs.  If given two or more times, pass @option{--verbose}
1575 to subordinate tools that support it.
1577 @item --debug
1578 @itemx -d
1579 Don't remove the temporary files.
1581 @item --force
1582 @itemx -f
1583 Remake even @file{configure} scripts and configuration headers that are
1584 newer than their input files (@file{configure.ac} and, if present,
1585 @file{aclocal.m4}).
1587 @item --install
1588 @itemx -i
1589 Install the missing auxiliary files in the package.  By default, files
1590 are copied; this can be changed with @option{--symlink}.
1592 If deemed appropriate, this option triggers calls to
1593 @samp{automake --add-missing},
1594 @samp{libtoolize}, @samp{autopoint}, etc.
1596 @item --no-recursive
1597 Do not rebuild files in subdirectories to configure (see @ref{Subdirectories},
1598 macro @code{AC_CONFIG_SUBDIRS}).
1600 @item --symlink
1601 @itemx -s
1602 When used with @option{--install}, install symbolic links to the missing
1603 auxiliary files instead of copying them.
1605 @item --make
1606 @itemx -m
1607 When the directories were configured, update the configuration by
1608 running @samp{./config.status --recheck && ./config.status}, and then
1609 run @samp{make}.
1611 @item --include=@var{dir}
1612 @itemx -I @var{dir}
1613 Append @var{dir} to the include path.  Multiple invocations accumulate.
1614 Passed on to @command{autoconf} and @command{autoheader} internally.
1616 @item --prepend-include=@var{dir}
1617 @item -B @var{dir}
1618 Prepend @var{dir} to the include path.  Multiple invocations accumulate.
1619 Passed on to @command{autoconf} and @command{autoheader} internally.
1621 @item --warnings=@var{category}
1622 @itemx -W @var{category}
1623 @evindex WARNINGS
1624 Report the warnings related to @var{category} (which can actually be a
1625 comma separated list).
1627 @table @samp
1628 @item cross
1629 related to cross compilation issues.
1631 @item obsolete
1632 report the uses of obsolete constructs.
1634 @item portability
1635 portability issues
1637 @item syntax
1638 dubious syntactic constructs.
1640 @item all
1641 report all the warnings
1643 @item none
1644 report none
1646 @item error
1647 treats warnings as errors
1649 @item no-@var{category}
1650 disable warnings falling into @var{category}
1651 @end table
1653 Warnings about @samp{syntax} are enabled by default, and the environment
1654 variable @env{WARNINGS}, a comma separated list of categories, is
1655 honored as well.  Passing @option{-W @var{category}} actually behaves as if
1656 you had passed @option{--warnings=syntax,$WARNINGS,@var{category}}.  If
1657 you want to disable the defaults and @env{WARNINGS}, but (for example)
1658 enable the warnings about obsolete constructs, you would use @option{-W
1659 none,obsolete}.
1660 @end table
1662 If you want @command{autoreconf} to pass flags that are not listed here
1663 on to @command{aclocal}, set @code{ACLOCAL_AMFLAGS} in your @file{Makefile.am}.
1665 @c ========================================= Initialization and Output Files.
1667 @node Setup
1668 @chapter Initialization and Output Files
1670 Autoconf-generated @command{configure} scripts need some information about
1671 how to initialize, such as how to find the package's source files and
1672 about the output files to produce.  The following sections describe the
1673 initialization and the creation of output files.
1675 @menu
1676 * Initializing configure::      Option processing etc.
1677 * Notices::                     Copyright, version numbers in @command{configure}
1678 * Input::                       Where Autoconf should find files
1679 * Output::                      Outputting results from the configuration
1680 * Configuration Actions::       Preparing the output based on results
1681 * Configuration Files::         Creating output files
1682 * Makefile Substitutions::      Using output variables in makefiles
1683 * Configuration Headers::       Creating a configuration header file
1684 * Configuration Commands::      Running arbitrary instantiation commands
1685 * Configuration Links::         Links depending on the configuration
1686 * Subdirectories::              Configuring independent packages together
1687 * Default Prefix::              Changing the default installation prefix
1688 @end menu
1690 @node Initializing configure
1691 @section Initializing @command{configure}
1693 Every @command{configure} script must call @code{AC_INIT} before doing
1694 anything else.  The only other required macro is @code{AC_OUTPUT}
1695 (@pxref{Output}).
1697 @defmac AC_INIT (@var{package}, @var{version}, @ovar{bug-report}, @ovar{tarname})
1698 @acindex{INIT}
1699 Process any command-line arguments and perform various initializations
1700 and verifications.
1702 Set the name of the @var{package} and its @var{version}.  These are
1703 typically used in @option{--version} support, including that of
1704 @command{configure}.  The optional argument @var{bug-report} should be
1705 the email to which users should send bug reports.  The package
1706 @var{tarname} differs from @var{package}: the latter designates the full
1707 package name (e.g., @samp{GNU Autoconf}), while the former is meant for
1708 distribution tar ball names (e.g., @samp{autoconf}).  It defaults to
1709 @var{package} with @samp{GNU } stripped, lower-cased, and all characters
1710 other than alphanumerics and underscores are changed to @samp{-}.
1712 It is preferable that the arguments of @code{AC_INIT} be static, i.e.,
1713 there should not be any shell computation, but they can be computed by
1716 The following M4 macros (e.g., @code{AC_PACKAGE_NAME}), output variables
1717 (e.g., @code{PACKAGE_NAME}), and preprocessor symbols (e.g.,
1718 @code{PACKAGE_NAME}) are defined by @code{AC_INIT}:
1720 @table @asis
1721 @item @code{AC_PACKAGE_NAME}, @code{PACKAGE_NAME}
1722 @acindex{PACKAGE_NAME}
1723 @ovindex PACKAGE_NAME
1724 @cvindex PACKAGE_NAME
1725 Exactly @var{package}.
1727 @item @code{AC_PACKAGE_TARNAME}, @code{PACKAGE_TARNAME}
1728 @acindex{PACKAGE_TARNAME}
1729 @ovindex PACKAGE_TARNAME
1730 @cvindex PACKAGE_TARNAME
1731 Exactly @var{tarname}.
1733 @item @code{AC_PACKAGE_VERSION}, @code{PACKAGE_VERSION}
1734 @acindex{PACKAGE_VERSION}
1735 @ovindex PACKAGE_VERSION
1736 @cvindex PACKAGE_VERSION
1737 Exactly @var{version}.
1739 @item @code{AC_PACKAGE_STRING}, @code{PACKAGE_STRING}
1740 @acindex{PACKAGE_STRING}
1741 @ovindex PACKAGE_STRING
1742 @cvindex PACKAGE_STRING
1743 Exactly @samp{@var{package} @var{version}}.
1745 @item @code{AC_PACKAGE_BUGREPORT}, @code{PACKAGE_BUGREPORT}
1746 @acindex{PACKAGE_BUGREPORT}
1747 @ovindex PACKAGE_BUGREPORT
1748 @cvindex PACKAGE_BUGREPORT
1749 Exactly @var{bug-report}.
1750 @end table
1751 @end defmac
1753 If your @command{configure} script does its own option processing, it
1754 should inspect @samp{$@@} or @samp{$*} immediately after calling
1755 @code{AC_INIT}, because other Autoconf macros liberally use the
1756 @command{set} command to process strings, and this has the side effect
1757 of updating @samp{$@@} and @samp{$*}.  However, we suggest that you use
1758 standard macros like @code{AC_ARG_ENABLE} instead of attempting to
1759 implement your own option processing.  @xref{Site Configuration}.
1762 @node Notices
1763 @section Notices in @command{configure}
1764 @cindex Notices in @command{configure}
1766 The following macros manage version numbers for @command{configure}
1767 scripts.  Using them is optional.
1769 @c FIXME: AC_PREREQ should not be here
1770 @defmac AC_PREREQ (@var{version})
1771 @acindex{PREREQ}
1772 @cindex Version
1773 Ensure that a recent enough version of Autoconf is being used.  If the
1774 version of Autoconf being used to create @command{configure} is
1775 earlier than @var{version}, print an error message to the standard
1776 error output and exit with failure (exit status is 63).  For example:
1778 @example
1779 AC_PREREQ([@value{VERSION}])
1780 @end example
1782 This macro is the only macro that may be used before @code{AC_INIT}, but
1783 for consistency, you are invited not to do so.
1784 @end defmac
1786 @defmac AC_COPYRIGHT (@var{copyright-notice})
1787 @acindex{COPYRIGHT}
1788 @cindex Copyright Notice
1789 State that, in addition to the Free Software Foundation's copyright on
1790 the Autoconf macros, parts of your @command{configure} are covered by the
1791 @var{copyright-notice}.
1793 The @var{copyright-notice} shows up in both the head of
1794 @command{configure} and in @samp{configure --version}.
1795 @end defmac
1798 @defmac AC_REVISION (@var{revision-info})
1799 @acindex{REVISION}
1800 @cindex Revision
1801 Copy revision stamp @var{revision-info} into the @command{configure}
1802 script, with any dollar signs or double-quotes removed.  This macro lets
1803 you put a revision stamp from @file{configure.ac} into @command{configure}
1804 without @acronym{RCS} or @acronym{CVS} changing it when you check in
1805 @command{configure}.  That way, you can determine easily which revision of
1806 @file{configure.ac} a particular @command{configure} corresponds to.
1808 For example, this line in @file{configure.ac}:
1810 @c The asis prevents RCS from changing the example in the manual.
1811 @example
1812 AC_REVISION([$@asis{Revision: 1.30 }$])
1813 @end example
1815 @noindent
1816 produces this in @command{configure}:
1818 @example
1819 #!/bin/sh
1820 # From configure.ac Revision: 1.30
1821 @end example
1822 @end defmac
1825 @node Input
1826 @section Finding @command{configure} Input
1829 @defmac AC_CONFIG_SRCDIR (@var{unique-file-in-source-dir})
1830 @acindex{CONFIG_SRCDIR}
1831 @var{unique-file-in-source-dir} is some file that is in the package's
1832 source directory; @command{configure} checks for this file's existence to
1833 make sure that the directory that it is told contains the source code in
1834 fact does.  Occasionally people accidentally specify the wrong directory
1835 with @option{--srcdir}; this is a safety check.  @xref{configure
1836 Invocation}, for more information.
1837 @end defmac
1840 @c FIXME: Remove definitively once --install explained.
1842 @c Small packages may store all their macros in @code{aclocal.m4}.  As the
1843 @c set of macros grows, or for maintenance reasons, a maintainer may prefer
1844 @c to split the macros in several files.  In this case, Autoconf must be
1845 @c told which files to load, and in which order.
1847 @c @defmac AC_INCLUDE (@var{file}@dots{})
1848 @c @acindex{INCLUDE}
1849 @c @c FIXME: There is no longer shell globbing.
1850 @c Read the macro definitions that appear in the listed files.  A list of
1851 @c space-separated file names or shell globbing patterns is expected.  The
1852 @c files are read in the order they're listed.
1854 @c Because the order of definition of macros is important (only the last
1855 @c definition of a macro is used), beware that it is @code{AC_INIT} that
1856 @c loads @file{acsite.m4} and @file{aclocal.m4}.  Note that
1857 @c @code{AC_INCLUDE}ing a file before @code{AC_INIT} or within
1858 @c @file{aclocal.m4} is different from doing so after @code{AC_INIT}: in
1859 @c the latter case, non-macro lines from included files may end up in the
1860 @c @file{configure} script, whereas in the former case, they'd be discarded
1861 @c just like any text that appear before @code{AC_INIT}.
1862 @c @end defmac
1864 Packages that do manual configuration or use the @command{install} program
1865 might need to tell @command{configure} where to find some other shell
1866 scripts by calling @code{AC_CONFIG_AUX_DIR}, though the default places
1867 it looks are correct for most cases.
1869 @defmac AC_CONFIG_AUX_DIR (@var{dir})
1870 @acindex{CONFIG_AUX_DIR}
1871 Use the auxiliary build tools (e.g., @file{install-sh},
1872 @file{config.sub}, @file{config.guess}, Cygnus @command{configure},
1873 Automake and Libtool scripts, etc.)@: that are in directory @var{dir}.
1874 These are auxiliary files used in configuration.  @var{dir} can be
1875 either absolute or relative to @file{@var{srcdir}}.  The default is
1876 @file{@var{srcdir}} or @file{@var{srcdir}/..} or
1877 @file{@var{srcdir}/../..}, whichever is the first that contains
1878 @file{install-sh}.  The other files are not checked for, so that using
1879 @code{AC_PROG_INSTALL} does not automatically require distributing the
1880 other auxiliary files.  It checks for @file{install.sh} also, but that
1881 name is obsolete because some @code{make} have a rule that creates
1882 @file{install} from it if there is no makefile.
1884 The auxiliary directory is commonly named @file{build-aux}.
1885 If you need portability to @acronym{DOS} variants, do not name the
1886 auxiliary directory @file{aux}.  @xref{File System Conventions}.
1887 @end defmac
1889 @defmac AC_REQUIRE_AUX_FILE (@var{file})
1890 @acindex{REQUIRE_AUX_FILE}
1891 Declares that @var{file} is expected in the directory defined above.  In
1892 Autoconf proper, this macro does nothing: its sole purpose is to be
1893 traced by third-party tools to produce a list of expected auxiliary
1894 files.  For instance it is called by macros like @code{AC_PROG_INSTALL}
1895 (@pxref{Particular Programs}) or @code{AC_CANONICAL_BUILD}
1896 (@pxref{Canonicalizing}) to register the auxiliary files they need.
1897 @end defmac
1899 Similarly, packages that use @command{aclocal} should declare where
1900 local macros can be found using @code{AC_CONFIG_MACRO_DIR}.
1902 @defmac AC_CONFIG_MACRO_DIR (@var{dir})
1903 @acindex{CONFIG_MACRO_DIR}
1904 Specify @var{dir} as the location of additional local Autoconf macros.
1905 This macro is intended for use by future versions of commands like
1906 @command{autoreconf} that trace macro calls.  It should be called
1907 directly from @file{configure.ac} so that tools that install macros for
1908 @command{aclocal} can find the macros' declarations.
1909 @end defmac
1912 @node Output
1913 @section Outputting Files
1914 @cindex Outputting files
1916 Every Autoconf script, e.g., @file{configure.ac}, should finish by
1917 calling @code{AC_OUTPUT}.  That is the macro that generates and runs
1918 @file{config.status}, which in turn creates the makefiles and any
1919 other files resulting from configuration.  This is the only required
1920 macro besides @code{AC_INIT} (@pxref{Input}).
1922 @defmac AC_OUTPUT
1923 @acindex{OUTPUT}
1924 @cindex Instantiation
1925 Generate @file{config.status} and launch it.  Call this macro once, at
1926 the end of @file{configure.ac}.
1928 @file{config.status} performs all the configuration actions: all the
1929 output files (see @ref{Configuration Files}, macro
1930 @code{AC_CONFIG_FILES}), header files (see @ref{Configuration Headers},
1931 macro @code{AC_CONFIG_HEADERS}), commands (see @ref{Configuration
1932 Commands}, macro @code{AC_CONFIG_COMMANDS}), links (see
1933 @ref{Configuration Links}, macro @code{AC_CONFIG_LINKS}), subdirectories
1934 to configure (see @ref{Subdirectories}, macro @code{AC_CONFIG_SUBDIRS})
1935 are honored.
1937 The location of your @code{AC_OUTPUT} invocation is the exact point
1938 where configuration actions are taken: any code afterwards is
1939 executed by @code{configure} once @command{config.status} was run.  If
1940 you want to bind actions to @command{config.status} itself
1941 (independently of whether @command{configure} is being run), see
1942 @ref{Configuration Commands, , Running Arbitrary Configuration
1943 Commands}.
1944 @end defmac
1946 Historically, the usage of @code{AC_OUTPUT} was somewhat different.
1947 @xref{Obsolete Macros}, for a description of the arguments that
1948 @code{AC_OUTPUT} used to support.
1951 If you run @command{make} in subdirectories, you should run it using the
1952 @code{make} variable @code{MAKE}.  Most versions of @command{make} set
1953 @code{MAKE} to the name of the @command{make} program plus any options it
1954 was given.  (But many do not include in it the values of any variables
1955 set on the command line, so those are not passed on automatically.)
1956 Some old versions of @command{make} do not set this variable.  The
1957 following macro allows you to use it even with those versions.
1959 @defmac AC_PROG_MAKE_SET
1960 @acindex{PROG_MAKE_SET}
1961 @ovindex SET_MAKE
1962 If the Make command, @code{$MAKE} if set or else @samp{make}, predefines
1963 @code{$(MAKE)}, define output variable @code{SET_MAKE} to be empty.
1964 Otherwise, define @code{SET_MAKE} to a macro definition that sets
1965 @code{$(MAKE)}, such as @samp{MAKE=make}.  Calls @code{AC_SUBST} for
1966 @code{SET_MAKE}.
1967 @end defmac
1969 If you use this macro, place a line like this in each @file{Makefile.in}
1970 that runs @code{MAKE} on other directories:
1972 @example
1973 @@SET_MAKE@@
1974 @end example
1978 @node Configuration Actions
1979 @section Performing Configuration Actions
1980 @cindex Configuration actions
1982 @file{configure} is designed so that it appears to do everything itself,
1983 but there is actually a hidden slave: @file{config.status}.
1984 @file{configure} is in charge of examining your system, but it is
1985 @file{config.status} that actually takes the proper actions based on the
1986 results of @file{configure}.  The most typical task of
1987 @file{config.status} is to @emph{instantiate} files.
1989 This section describes the common behavior of the four standard
1990 instantiating macros: @code{AC_CONFIG_FILES}, @code{AC_CONFIG_HEADERS},
1991 @code{AC_CONFIG_COMMANDS} and @code{AC_CONFIG_LINKS}.  They all
1992 have this prototype:
1994 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
1995 @c awful.
1996 @example
1997 AC_CONFIG_FOOS(@var{tag}@dots{}, [@var{commands}], [@var{init-cmds}])
1998 @end example
2000 @noindent
2001 where the arguments are:
2003 @table @var
2004 @item tag@dots{}
2005 A blank-or-newline-separated list of tags, which are typically the names of
2006 the files to instantiate.
2008 You are encouraged to use literals as @var{tags}.  In particular, you
2009 should avoid
2011 @example
2012 @dots{} && my_foos="$my_foos fooo"
2013 @dots{} && my_foos="$my_foos foooo"
2014 AC_CONFIG_FOOS([$my_foos])
2015 @end example
2017 @noindent
2018 and use this instead:
2020 @example
2021 @dots{} && AC_CONFIG_FOOS([fooo])
2022 @dots{} && AC_CONFIG_FOOS([foooo])
2023 @end example
2025 The macros @code{AC_CONFIG_FILES} and @code{AC_CONFIG_HEADERS} use
2026 special @var{tag} values: they may have the form @samp{@var{output}} or
2027 @samp{@var{output}:@var{inputs}}.  The file @var{output} is instantiated
2028 from its templates, @var{inputs} (defaulting to @samp{@var{output}.in}).
2030 @samp{AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk)]},
2031 for example, asks for
2032 the creation of the file @file{Makefile} that contains the expansion of the
2033 output variables in the concatenation of @file{boiler/top.mk} and
2034 @file{boiler/bot.mk}.
2036 The special value @samp{-} might be used to denote the standard output
2037 when used in @var{output}, or the standard input when used in the
2038 @var{inputs}.  You most probably don't need to use this in
2039 @file{configure.ac}, but it is convenient when using the command line
2040 interface of @file{./config.status}, see @ref{config.status Invocation},
2041 for more details.
2043 The @var{inputs} may be absolute or relative file names.  In the latter
2044 case they are first looked for in the build tree, and then in the source
2045 tree.
2047 @item commands
2048 Shell commands output literally into @file{config.status}, and
2049 associated with a tag that the user can use to tell @file{config.status}
2050 which the commands to run.  The commands are run each time a @var{tag}
2051 request is given to @file{config.status}, typically each time the file
2052 @file{@var{tag}} is created.
2054 The variables set during the execution of @command{configure} are
2055 @emph{not} available here: you first need to set them via the
2056 @var{init-cmds}.  Nonetheless the following variables are precomputed:
2058 @table @code
2059 @item srcdir
2060 The name of the top source directory, assuming that the working
2061 directory is the top build directory.  This
2062 is what the @command{configure} option @option{--srcdir} sets.
2064 @item ac_top_srcdir
2065 The name of the top source directory, assuming that the working
2066 directory is the current build directory.
2069 @item ac_top_build_prefix
2070 The name of the top build directory, assuming that the working
2071 directory is the current build directory.
2072 It can be empty, or else ends with a slash, so that you may concatenate
2075 @item ac_srcdir
2076 The name of the corresponding source directory, assuming that the
2077 working directory is the current build directory.
2078 @end table
2080 @noindent
2081 The @dfn{current} directory refers to the directory (or
2082 pseudo-directory) containing the input part of @var{tags}.  For
2083 instance, running
2085 @example
2086 AC_CONFIG_COMMANDS([deep/dir/out:in/in.in], [@dots{}], [@dots{}])
2087 @end example
2089 @noindent
2090  with @option{--srcdir=../package} produces the following values:
2092 @example
2093 # Argument of --srcdir
2094 srcdir='../package'
2095 # Reversing deep/dir
2096 ac_top_build_prefix='../../'
2097 # Concatenation of $ac_top_build_prefix and srcdir
2098 ac_top_srcdir='../../../package'
2099 # Concatenation of $ac_top_srcdir and deep/dir
2100 ac_srcdir='../../../package/deep/dir'
2101 @end example
2103 @noindent
2104 independently of @samp{in/in.in}.
2106 @item init-cmds
2107 Shell commands output @emph{unquoted} near the beginning of
2108 @file{config.status}, and executed each time @file{config.status} runs
2109 (regardless of the tag).  Because they are unquoted, for example,
2110 @samp{$var} is output as the value of @code{var}.  @var{init-cmds}
2111 is typically used by @file{configure} to give @file{config.status} some
2112 variables it needs to run the @var{commands}.
2114 You should be extremely cautious in your variable names: all the
2115 @var{init-cmds} share the same name space and may overwrite each other
2116 in unpredictable ways.  Sorry@enddots{}
2117 @end table
2119 All these macros can be called multiple times, with different
2120 @var{tag} values, of course!
2123 @node Configuration Files
2124 @section Creating Configuration Files
2125 @cindex Creating configuration files
2126 @cindex Configuration file creation
2128 Be sure to read the previous section, @ref{Configuration Actions}.
2130 @defmac AC_CONFIG_FILES (@var{file}@dots{}, @ovar{cmds}, @ovar{init-cmds})
2131 @acindex{CONFIG_FILES}
2132 Make @code{AC_OUTPUT} create each @file{@var{file}} by copying an input
2133 file (by default @file{@var{file}.in}), substituting the output variable
2134 values.
2135 @c Before we used to have this feature, which was later rejected
2136 @c because it complicates the writing of makefiles:
2137 @c If the file would be unchanged, it is left untouched, to preserve
2138 @c timestamp.
2139 This macro is one of the instantiating macros; see @ref{Configuration
2140 Actions}.  @xref{Makefile Substitutions}, for more information on using
2141 output variables.  @xref{Setting Output Variables}, for more information
2142 on creating them.  This macro creates the directory that the file is in
2143 if it doesn't exist.  Usually, makefiles are created this way,
2144 but other files, such as @file{.gdbinit}, can be specified as well.
2146 Typical calls to @code{AC_CONFIG_FILES} look like this:
2148 @example
2149 AC_CONFIG_FILES([Makefile src/Makefile man/Makefile X/Imakefile])
2150 AC_CONFIG_FILES([autoconf], [chmod +x autoconf])
2151 @end example
2153 You can override an input file name by appending to @var{file} a
2154 colon-separated list of input files.  Examples:
2156 @example
2157 AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk]
2158                 [lib/Makefile:boiler/lib.mk])
2159 @end example
2161 @noindent
2162 Doing this allows you to keep your file names acceptable to
2163 @acronym{DOS} variants, or
2164 to prepend and/or append boilerplate to the file.
2165 @end defmac
2169 @node Makefile Substitutions
2170 @section Substitutions in Makefiles
2171 @cindex Substitutions in makefiles
2172 @cindex Makefile substitutions
2174 Each subdirectory in a distribution that contains something to be
2175 compiled or installed should come with a file @file{Makefile.in}, from
2176 which @command{configure} creates a file @file{Makefile} in that directory.
2177 To create @file{Makefile}, @command{configure} performs a simple variable
2178 substitution, replacing occurrences of @samp{@@@var{variable}@@} in
2179 @file{Makefile.in} with the value that @command{configure} has determined
2180 for that variable.  Variables that are substituted into output files in
2181 this way are called @dfn{output variables}.  They are ordinary shell
2182 variables that are set in @command{configure}.  To make @command{configure}
2183 substitute a particular variable into the output files, the macro
2184 @code{AC_SUBST} must be called with that variable name as an argument.
2185 Any occurrences of @samp{@@@var{variable}@@} for other variables are
2186 left unchanged.  @xref{Setting Output Variables}, for more information
2187 on creating output variables with @code{AC_SUBST}.
2189 A software package that uses a @command{configure} script should be
2190 distributed with a file @file{Makefile.in}, but no makefile; that
2191 way, the user has to properly configure the package for the local system
2192 before compiling it.
2194 @xref{Makefile Conventions, , Makefile Conventions, standards, The
2195 @acronym{GNU} Coding Standards}, for more information on what to put in
2196 makefiles.
2198 @menu
2199 * Preset Output Variables::     Output variables that are always set
2200 * Installation Directory Variables::  Other preset output variables
2201 * Changed Directory Variables:: Warnings about @file{datarootdir}
2202 * Build Directories::           Supporting multiple concurrent compiles
2203 * Automatic Remaking::          Makefile rules for configuring
2204 @end menu
2206 @node Preset Output Variables
2207 @subsection Preset Output Variables
2208 @cindex Output variables
2210 Some output variables are preset by the Autoconf macros.  Some of the
2211 Autoconf macros set additional output variables, which are mentioned in
2212 the descriptions for those macros.  @xref{Output Variable Index}, for a
2213 complete list of output variables.  @xref{Installation Directory
2214 Variables}, for the list of the preset ones related to installation
2215 directories.  Below are listed the other preset ones.  They all are
2216 precious variables (@pxref{Setting Output Variables},
2217 @code{AC_ARG_VAR}).
2219 @c Just say no to ASCII sorting!  We're humans, not computers.
2220 @c These variables are listed as they would be in a dictionary:
2221 @c actor
2222 @c Actress
2223 @c actress
2225 @defvar CFLAGS
2226 @ovindex CFLAGS
2227 Debugging and optimization options for the C compiler.  If it is not set
2228 in the environment when @command{configure} runs, the default value is set
2229 when you call @code{AC_PROG_CC} (or empty if you don't).  @command{configure}
2230 uses this variable when compiling or linking programs to test for C features.
2232 If a compiler option affects only the behavior of the preprocessor
2233 (e.g., @option{-D @var{name}}), it should be put into @code{CPPFLAGS}
2234 instead.  If it affects only the linker (e.g., @option{-L
2235 @var{directory}}), it should be put into @code{LDFLAGS} instead.  If it
2236 affects only the compiler proper, @code{CFLAGS} is the natural home for
2237 it.  If an option affects multiple phases of the compiler, though,
2238 matters get tricky.  One approach to put such options directly into
2239 @code{CC}, e.g., @code{CC='gcc -m64'}.  Another is to put them into both
2240 @code{CPPFLAGS} and @code{LDFLAGS}, but not into @code{CFLAGS}.
2242 @end defvar
2244 @defvar configure_input
2245 @ovindex configure_input
2246 A comment saying that the file was generated automatically by
2247 @command{configure} and giving the name of the input file.
2248 @code{AC_OUTPUT} adds a comment line containing this variable to the top
2249 of every makefile it creates.  For other files, you should
2250 reference this variable in a comment at the top of each input file.  For
2251 example, an input shell script should begin like this:
2253 @example
2254 #!/bin/sh
2255 # @@configure_input@@
2256 @end example
2258 @noindent
2259 The presence of that line also reminds people editing the file that it
2260 needs to be processed by @command{configure} in order to be used.
2261 @end defvar
2263 @defvar CPPFLAGS
2264 @ovindex CPPFLAGS
2265 Preprocessor options for the C, C++, and Objective C preprocessors and
2266 compilers.  If
2267 it is not set in the environment when @command{configure} runs, the default
2268 value is empty.  @command{configure} uses this variable when preprocessing
2269 or compiling programs to test for C, C++, and Objective C features.
2271 This variable's contents should contain options like @option{-I},
2272 @option{-D}, and @option{-U} that affect only the behavior of the
2273 preprocessor.  Please see the explanation of @code{CFLAGS} for what you
2274 can do if an option affects other phases of the compiler as well.
2276 Currently, @command{configure} always links as part of a single
2277 invocation of the compiler that also preprocesses and compiles, so it
2278 uses this variable also when linking programs.  However, it is unwise to
2279 depend on this behavior because the @acronym{GNU} coding standards do
2280 not require it and many packages do not use @code{CPPFLAGS} when linking
2281 programs.
2283 @xref{Special Chars in Variables}, for limitations that @code{CPPFLAGS}
2284 might run into.
2285 @end defvar
2287 @defvar CXXFLAGS
2288 @ovindex CXXFLAGS
2289 Debugging and optimization options for the C++ compiler.  It acts like
2290 @code{CFLAGS}, but for C++ instead of C.
2291 @end defvar
2293 @defvar DEFS
2294 @ovindex DEFS
2295 @option{-D} options to pass to the C compiler.  If @code{AC_CONFIG_HEADERS}
2296 is called, @command{configure} replaces @samp{@@DEFS@@} with
2297 @option{-DHAVE_CONFIG_H} instead (@pxref{Configuration Headers}).  This
2298 variable is not defined while @command{configure} is performing its tests,
2299 only when creating the output files.  @xref{Setting Output Variables}, for
2300 how to check the results of previous tests.
2301 @end defvar
2303 @defvar ECHO_C
2304 @defvarx ECHO_N
2305 @defvarx ECHO_T
2306 @ovindex ECHO_C
2307 @ovindex ECHO_N
2308 @ovindex ECHO_T
2309 How does one suppress the trailing newline from @command{echo} for
2310 question-answer message pairs?  These variables provide a way:
2312 @example
2313 echo $ECHO_N "And the winner is... $ECHO_C"
2314 sleep 100000000000
2315 echo "$@{ECHO_T@}dead."
2316 @end example
2318 @noindent
2319 Some old and uncommon @command{echo} implementations offer no means to
2320 achieve this, in which case @code{ECHO_T} is set to tab.  You might not
2321 want to use it.
2322 @end defvar
2324 @defvar ERLCFLAGS
2325 @ovindex ERLCFLAGS
2326 Debugging and optimization options for the Erlang compiler.  If it is not set
2327 in the environment when @command{configure} runs, the default value is empty.
2328 @command{configure} uses this variable when compiling
2329 programs to test for Erlang features.
2330 @end defvar
2332 @defvar FCFLAGS
2333 @ovindex FCFLAGS
2334 Debugging and optimization options for the Fortran compiler.  If it
2335 is not set in the environment when @command{configure} runs, the default
2336 value is set when you call @code{AC_PROG_FC} (or empty if you don't).
2337 @command{configure} uses this variable when compiling or linking
2338 programs to test for Fortran features.
2339 @end defvar
2341 @defvar FFLAGS
2342 @ovindex FFLAGS
2343 Debugging and optimization options for the Fortran 77 compiler.  If it
2344 is not set in the environment when @command{configure} runs, the default
2345 value is set when you call @code{AC_PROG_F77} (or empty if you don't).
2346 @command{configure} uses this variable when compiling or linking
2347 programs to test for Fortran 77 features.
2348 @end defvar
2350 @defvar LDFLAGS
2351 @ovindex LDFLAGS
2352 Options for the linker.  If it is not set
2353 in the environment when @command{configure} runs, the default value is empty.
2354 @command{configure} uses this variable when linking programs to test for
2355 C, C++, Objective C, and Fortran features.
2357 This variable's contents should contain options like @option{-s} and
2358 @option{-L} that affect only the behavior of the linker.  Please see the
2359 explanation of @code{CFLAGS} for what you can do if an option also
2360 affects other phases of the compiler.
2362 Don't use this variable to pass library names
2363 (@option{-l}) to the linker; use @code{LIBS} instead.
2364 @end defvar
2366 @defvar LIBS
2367 @ovindex LIBS
2368 @option{-l} options to pass to the linker.  The default value is empty,
2369 but some Autoconf macros may prepend extra libraries to this variable if
2370 those libraries are found and provide necessary functions, see
2371 @ref{Libraries}.  @command{configure} uses this variable when linking
2372 programs to test for C, C++, and Fortran features.
2373 @end defvar
2375 @defvar OBJCFLAGS
2376 @ovindex OBJCFLAGS
2377 Debugging and optimization options for the Objective C compiler.  It
2378 acts like @code{CFLAGS}, but for Objective C instead of C.
2379 @end defvar
2381 @defvar builddir
2382 @ovindex builddir
2383 Rigorously equal to @samp{.}.  Added for symmetry only.
2384 @end defvar
2386 @defvar abs_builddir
2387 @ovindex abs_builddir
2388 Absolute name of @code{builddir}.
2389 @end defvar
2391 @defvar top_builddir
2392 @ovindex top_builddir
2393 The relative name of the top level of the current build tree.  In the
2394 top-level directory, this is the same as @code{builddir}.
2395 @end defvar
2397 @defvar abs_top_builddir
2398 @ovindex abs_top_builddir
2399 Absolute name of @code{top_builddir}.
2400 @end defvar
2402 @defvar srcdir
2403 @ovindex srcdir
2404 The name of the directory that contains the source code for
2405 that makefile.
2406 @end defvar
2408 @defvar abs_srcdir
2409 @ovindex abs_srcdir
2410 Absolute name of @code{srcdir}.
2411 @end defvar
2413 @defvar top_srcdir
2414 @ovindex top_srcdir
2415 The name of the top-level source code directory for the
2416 package.  In the top-level directory, this is the same as @code{srcdir}.
2417 @end defvar
2419 @defvar abs_top_srcdir
2420 @ovindex abs_top_srcdir
2421 Absolute name of @code{top_srcdir}.
2422 @end defvar
2424 @node Installation Directory Variables
2425 @subsection Installation Directory Variables
2426 @cindex Installation directories
2427 @cindex Directories, installation
2429 The following variables specify the directories for
2430 package installation, see @ref{Directory Variables, , Variables for
2431 Installation Directories, standards, The @acronym{GNU} Coding
2432 Standards}, for more information.  See the end of this section for
2433 details on when and how to use these variables.
2435 @defvar bindir
2436 @ovindex bindir
2437 The directory for installing executables that users run.
2438 @end defvar
2440 @defvar datadir
2441 @ovindex datadir
2442 The directory for installing idiosyncratic read-only
2443 architecture-independent data.
2444 @end defvar
2446 @defvar datarootdir
2447 @ovindex datarootdir
2448 The root of the directory tree for read-only architecture-independent
2449 data files.
2450 @end defvar
2452 @defvar docdir
2453 @ovindex docdir
2454 The directory for installing documentation files (other than Info and
2455 man).
2456 @end defvar
2458 @defvar dvidir
2459 @ovindex dvidir
2460 The directory for installing documentation files in DVI format.
2461 @end defvar
2463 @defvar exec_prefix
2464 @ovindex exec_prefix
2465 The installation prefix for architecture-dependent files.  By default
2466 it's the same as @var{prefix}.  You should avoid installing anything
2467 directly to @var{exec_prefix}.  However, the default value for
2468 directories containing architecture-dependent files should be relative
2469 to @var{exec_prefix}.
2470 @end defvar
2472 @defvar htmldir
2473 @ovindex htmldir
2474 The directory for installing HTML documentation.
2475 @end defvar
2477 @defvar includedir
2478 @ovindex includedir
2479 The directory for installing C header files.
2480 @end defvar
2482 @defvar infodir
2483 @ovindex infodir
2484 The directory for installing documentation in Info format.
2485 @end defvar
2487 @defvar libdir
2488 @ovindex libdir
2489 The directory for installing object code libraries.
2490 @end defvar
2492 @defvar libexecdir
2493 @ovindex libexecdir
2494 The directory for installing executables that other programs run.
2495 @end defvar
2497 @defvar localedir
2498 @ovindex localedir
2499 The directory for installing locale-dependent but
2500 architecture-independent data, such as message catalogs.  This directory
2501 usually has a subdirectory per locale.
2502 @end defvar
2504 @defvar localstatedir
2505 @ovindex localstatedir
2506 The directory for installing modifiable single-machine data.
2507 @end defvar
2509 @defvar mandir
2510 @ovindex mandir
2511 The top-level directory for installing documentation in man format.
2512 @end defvar
2514 @defvar oldincludedir
2515 @ovindex oldincludedir
2516 The directory for installing C header files for non-@acronym{GCC} compilers.
2517 @end defvar
2519 @defvar pdfdir
2520 @ovindex pdfdir
2521 The directory for installing PDF documentation.
2522 @end defvar
2524 @defvar prefix
2525 @ovindex prefix
2526 The common installation prefix for all files.  If @var{exec_prefix}
2527 is defined to a different value, @var{prefix} is used only for
2528 architecture-independent files.
2529 @end defvar
2531 @defvar psdir
2532 @ovindex psdir
2533 The directory for installing PostScript documentation.
2534 @end defvar
2536 @defvar sbindir
2537 @ovindex sbindir
2538 The directory for installing executables that system
2539 administrators run.
2540 @end defvar
2542 @defvar sharedstatedir
2543 @ovindex sharedstatedir
2544 The directory for installing modifiable architecture-independent data.
2545 @end defvar
2547 @defvar sysconfdir
2548 @ovindex sysconfdir
2549 The directory for installing read-only single-machine data.
2550 @end defvar
2553 Most of these variables have values that rely on @code{prefix} or
2554 @code{exec_prefix}.  It is deliberate that the directory output
2555 variables keep them unexpanded: typically @samp{@@datarootdir@@} is
2556 replaced by @samp{$@{prefix@}/share}, not @samp{/usr/local/share}, and
2557 @samp{@@datadir@@} is replaced by @samp{$@{datarootdir@}}.
2559 This behavior is mandated by the @acronym{GNU} coding standards, so that when
2560 the user runs:
2562 @table @samp
2563 @item make
2564 she can still specify a different prefix from the one specified to
2565 @command{configure}, in which case, if needed, the package should hard
2566 code dependencies corresponding to the make-specified prefix.
2568 @item make install
2569 she can specify a different installation location, in which case the
2570 package @emph{must} still depend on the location which was compiled in
2571 (i.e., never recompile when @samp{make install} is run).  This is an
2572 extremely important feature, as many people may decide to install all
2573 the files of a package grouped together, and then install links from
2574 the final locations to there.
2575 @end table
2577 In order to support these features, it is essential that
2578 @code{datarootdir} remains being defined as @samp{$@{prefix@}/share} to
2579 depend upon the current value of @code{prefix}.
2581 A corollary is that you should not use these variables except in
2582 makefiles.  For instance, instead of trying to evaluate @code{datadir}
2583 in @file{configure} and hard-coding it in makefiles using
2584 e.g., @samp{AC_DEFINE_UNQUOTED([DATADIR], ["$datadir"], [Data directory.])},
2585 you should add
2586 @option{-DDATADIR='$(datadir)'} to your makefile's definition of
2587 @code{CPPFLAGS} (@code{AM_CPPFLAGS} if you are also using Automake).
2589 Similarly, you should not rely on @code{AC_CONFIG_FILES} to replace
2590 @code{datadir} and friends in your shell scripts and other files; instead,
2591 let @command{make} manage their replacement.  For instance Autoconf
2592 ships templates of its shell scripts ending with @samp{.in}, and uses a
2593 makefile snippet similar to the following to build scripts like
2594 @command{autoheader} and @command{autom4te}:
2596 @example
2597 @group
2598 edit = sed \
2599         -e 's|@@datadir[@@]|$(pkgdatadir)|g' \
2600         -e 's|@@prefix[@@]|$(prefix)|g'
2601 @end group
2603 @group
2604 autoheader autom4te: Makefile
2605         rm -f $@@ $@@.tmp
2606         $(edit) '$(srcdir)/$@@.in' >$@@.tmp
2607         chmod +x $@@.tmp
2608         chmod a-w $@@.tmp
2609         mv $@@.tmp $@@
2610 @end group
2612 @group
2613 autoheader: $(srcdir)/autoheader.in
2614 autom4te: $(srcdir)/autom4te.in
2615 @end group
2616 @end example
2618 Some details are noteworthy:
2620 @table @asis
2621 @item @samp{@@datadir[@@]}
2622 The brackets prevent @command{configure} from replacing
2623 @samp{@@datadir@@} in the Sed expression itself.
2624 Brackets are preferable to a backslash here, since
2625 Posix says @samp{\@@} is not portable.
2627 @item @samp{$(pkgdatadir)}
2628 Don't use @samp{@@pkgdatadir@@}!  Use the matching makefile variable
2629 instead.
2631 @item @samp{/}
2632 Don't use @samp{/} in the Sed expressions that replace file names since
2633 most likely the
2634 variables you use, such as @samp{$(pkgdatadir)}, contain @samp{/}.
2635 Use a shell metacharacter instead, such as @samp{|}.
2637 @item special characters
2638 File names, file name components, and the value of @code{VPATH} should
2639 not contain shell metacharacters or white
2640 space.  @xref{Special Chars in Variables}.
2642 @item dependency on @file{Makefile}
2643 Since @code{edit} uses values that depend on the configuration specific
2644 values (@code{prefix}, etc.)@: and not only on @code{VERSION} and so forth,
2645 the output depends on @file{Makefile}, not @file{configure.ac}.
2647 @item @samp{$@@}
2648 The main rule is generic, and uses @samp{$@@} extensively to
2649 avoid the need for multiple copies of the rule.
2651 @item Separated dependencies and single suffix rules
2652 You can't use them!  The above snippet cannot be (portably) rewritten
2655 @example
2656 autoconf autoheader: Makefile
2657 @group
2658 .in:
2659         rm -f $@@ $@@.tmp
2660         $(edit) $< >$@@.tmp
2661         chmod +x $@@.tmp
2662         mv $@@.tmp $@@
2663 @end group
2664 @end example
2666 @xref{Single Suffix Rules}, for details.
2668 @item @samp{$(srcdir)}
2669 Be sure to specify the name of the source directory,
2670 otherwise the package won't support separated builds.
2671 @end table
2673 For the more specific installation of Erlang libraries, the following variables
2674 are defined:
2676 @defvar ERLANG_INSTALL_LIB_DIR
2677 @ovindex ERLANG_INSTALL_LIB_DIR
2678 @acindex{ERLANG_SUBST_INSTALL_LIB_DIR}
2679 The common parent directory of Erlang library installation directories.
2680 This variable is set by calling the @code{AC_ERLANG_SUBST_INSTALL_LIB_DIR}
2681 macro in @file{configure.ac}.
2682 @end defvar
2684 @defvar ERLANG_INSTALL_LIB_DIR_@var{library}
2685 @ovindex ERLANG_INSTALL_LIB_DIR_@var{library}
2686 @acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR}
2687 The installation directory for Erlang library @var{library}.
2688 This variable is set by calling the
2689 @samp{AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR(@var{library}, @var{version}}
2690 macro in @file{configure.ac}.
2691 @end defvar
2693 @xref{Erlang Libraries}, for details.
2696 @node Changed Directory Variables
2697 @subsection Changed Directory Variables
2698 @cindex @file{datarootdir}
2700 In Autoconf 2.60, the set of directory variables has changed, and the
2701 defaults of some variables have been adjusted
2702 (@pxref{Installation Directory Variables}) to changes in the
2703 @acronym{GNU} Coding Standards.  Notably, @file{datadir}, @file{infodir}, and
2704 @file{mandir} are now expressed in terms of @file{datarootdir}.  If you are
2705 upgrading from an earlier Autoconf version, you may need to adjust your files
2706 to ensure that the directory variables are substituted correctly
2707 (@pxref{Defining Directories}), and that a definition of @file{datarootdir} is
2708 in place.  For example, in a @file{Makefile.in}, adding
2710 @example
2711 datarootdir = @@datarootdir@@
2712 @end example
2714 @noindent
2715 is usually sufficient.  If you use Automake to create @file{Makefile.in},
2716 it will add this for you.
2718 To help with the transition, Autoconf warns about files that seem to use
2719 @code{datarootdir} without defining it.  In some cases, it then expands
2720 the value of @code{$datarootdir} in substitutions of the directory
2721 variables.  The following example shows such a warning:
2723 @example
2724 $ @kbd{cat configure.ac}
2725 AC_INIT
2726 AC_CONFIG_FILES([Makefile])
2727 AC_OUTPUT
2728 $ @kbd{cat Makefile.in}
2729 prefix = @@prefix@@
2730 datadir = @@datadir@@
2731 $ @kbd{autoconf}
2732 $ @kbd{configure}
2733 configure: creating ./config.status
2734 config.status: creating Makefile
2735 config.status: WARNING:
2736                Makefile.in seems to ignore the --datarootdir setting
2737 $ @kbd{cat Makefile}
2738 prefix = /usr/local
2739 datadir = $@{prefix@}/share
2740 @end example
2742 Usually one can easily change the file to accommodate both older and newer
2743 Autoconf releases:
2745 @example
2746 $ @kbd{cat Makefile.in}
2747 prefix = @@prefix@@
2748 datarootdir = @@datarootdir@@
2749 datadir = @@datadir@@
2750 $ @kbd{configure}
2751 configure: creating ./config.status
2752 config.status: creating Makefile
2753 $ @kbd{cat Makefile}
2754 prefix = /usr/local
2755 datarootdir = $@{prefix@}/share
2756 datadir = $@{datarootdir@}
2757 @end example
2759 @acindex{DATAROOTDIR_CHECKED}
2760 In some cases, however, the checks may not be able to detect that a suitable
2761 initialization of @code{datarootdir} is in place, or they may fail to detect
2762 that such an initialization is necessary in the output file.  If, after
2763 auditing your package, there are still spurious @file{configure} warnings about
2764 @code{datarootdir}, you may add the line
2766 @example
2767 AC_DEFUN([AC_DATAROOTDIR_CHECKED])
2768 @end example
2770 @noindent
2771 to your @file{configure.ac} to disable the warnings.  This is an exception
2772 to the usual rule that you should not define a macro whose name begins with
2773 @code{AC_} (@pxref{Macro Names}).
2777 @node Build Directories
2778 @subsection Build Directories
2779 @cindex Build directories
2780 @cindex Directories, build
2782 You can support compiling a software package for several architectures
2783 simultaneously from the same copy of the source code.  The object files
2784 for each architecture are kept in their own directory.
2786 To support doing this, @command{make} uses the @code{VPATH} variable to
2787 find the files that are in the source directory.  @acronym{GNU} Make
2788 and most other recent @command{make} programs can do this.  Older
2789 @command{make} programs do not support @code{VPATH}; when using them, the
2790 source code must be in the same directory as the object files.
2792 To support @code{VPATH}, each @file{Makefile.in} should contain two
2793 lines that look like:
2795 @example
2796 srcdir = @@srcdir@@
2797 VPATH = @@srcdir@@
2798 @end example
2800 Do not set @code{VPATH} to the value of another variable, for example
2801 @samp{VPATH = $(srcdir)}, because some versions of @command{make} do not do
2802 variable substitutions on the value of @code{VPATH}.
2804 @command{configure} substitutes the correct value for @code{srcdir} when
2805 it produces @file{Makefile}.
2807 Do not use the @code{make} variable @code{$<}, which expands to the
2808 file name of the file in the source directory (found with @code{VPATH}),
2809 except in implicit rules.  (An implicit rule is one such as @samp{.c.o},
2810 which tells how to create a @file{.o} file from a @file{.c} file.)  Some
2811 versions of @command{make} do not set @code{$<} in explicit rules; they
2812 expand it to an empty value.
2814 Instead, Make command lines should always refer to source
2815 files by prefixing them with @samp{$(srcdir)/}.  For example:
2817 @example
2818 time.info: time.texinfo
2819         $(MAKEINFO) '$(srcdir)/time.texinfo'
2820 @end example
2822 @node Automatic Remaking
2823 @subsection Automatic Remaking
2824 @cindex Automatic remaking
2825 @cindex Remaking automatically
2827 You can put rules like the following in the top-level @file{Makefile.in}
2828 for a package to automatically update the configuration information when
2829 you change the configuration files.  This example includes all of the
2830 optional files, such as @file{aclocal.m4} and those related to
2831 configuration header files.  Omit from the @file{Makefile.in} rules for
2832 any of these files that your package does not use.
2834 The @samp{$(srcdir)/} prefix is included because of limitations in the
2835 @code{VPATH} mechanism.
2837 The @file{stamp-} files are necessary because the timestamps of
2838 @file{config.h.in} and @file{config.h} are not changed if remaking
2839 them does not change their contents.  This feature avoids unnecessary
2840 recompilation.  You should include the file @file{stamp-h.in} your
2841 package's distribution, so that @command{make} considers
2842 @file{config.h.in} up to date.  Don't use @command{touch}
2843 (@pxref{Limitations of Usual Tools}); instead, use @command{echo} (using
2844 @command{date} would cause needless differences, hence @acronym{CVS}
2845 conflicts, etc.).
2847 @example
2848 @group
2849 $(srcdir)/configure: configure.ac aclocal.m4
2850         cd '$(srcdir)' && autoconf
2852 # autoheader might not change config.h.in, so touch a stamp file.
2853 $(srcdir)/config.h.in: stamp-h.in
2854 $(srcdir)/stamp-h.in: configure.ac aclocal.m4
2855         cd '$(srcdir)' && autoheader
2856         echo timestamp > '$(srcdir)/stamp-h.in'
2858 config.h: stamp-h
2859 stamp-h: config.h.in config.status
2860         ./config.status
2862 Makefile: Makefile.in config.status
2863         ./config.status
2865 config.status: configure
2866         ./config.status --recheck
2867 @end group
2868 @end example
2870 @noindent
2871 (Be careful if you copy these lines directly into your makefile, as you
2872 need to convert the indented lines to start with the tab character.)
2874 In addition, you should use
2876 @example
2877 AC_CONFIG_FILES([stamp-h], [echo timestamp > stamp-h])
2878 @end example
2880 @noindent
2881 so @file{config.status} ensures that @file{config.h} is considered up to
2882 date.  @xref{Output}, for more information about @code{AC_OUTPUT}.
2884 @xref{config.status Invocation}, for more examples of handling
2885 configuration-related dependencies.
2887 @node Configuration Headers
2888 @section Configuration Header Files
2889 @cindex Configuration Header
2890 @cindex @file{config.h}
2892 When a package contains more than a few tests that define C preprocessor
2893 symbols, the command lines to pass @option{-D} options to the compiler
2894 can get quite long.  This causes two problems.  One is that the
2895 @command{make} output is hard to visually scan for errors.  More
2896 seriously, the command lines can exceed the length limits of some
2897 operating systems.  As an alternative to passing @option{-D} options to
2898 the compiler, @command{configure} scripts can create a C header file
2899 containing @samp{#define} directives.  The @code{AC_CONFIG_HEADERS}
2900 macro selects this kind of output.  Though it can be called anywhere
2901 between @code{AC_INIT} and @code{AC_OUTPUT}, it is customary to call
2902 it right after @code{AC_INIT}.
2904 The package should @samp{#include} the configuration header file before
2905 any other header files, to prevent inconsistencies in declarations (for
2906 example, if it redefines @code{const}).
2908 To provide for VPATH builds, remember to pass the C compiler a @option{-I.}
2909 option (or @option{-I..}; whichever directory contains @file{config.h}).
2910 Even if you use @samp{#include "config.h"}, the preprocessor searches only
2911 the directory of the currently read file, i.e., the source directory, not
2912 the build directory.
2914 With the appropriate @option{-I} option, you can use
2915 @samp{#include <config.h>}.  Actually, it's a good habit to use it,
2916 because in the rare case when the source directory contains another
2917 @file{config.h}, the build directory should be searched first.
2920 @defmac AC_CONFIG_HEADERS (@var{header} @dots{}, @ovar{cmds}, @ovar{init-cmds})
2921 @acindex{CONFIG_HEADERS}
2922 @cvindex HAVE_CONFIG_H
2923 This macro is one of the instantiating macros; see @ref{Configuration
2924 Actions}.  Make @code{AC_OUTPUT} create the file(s) in the
2925 blank-or-newline-separated list @var{header} containing C preprocessor
2926 @code{#define} statements, and replace @samp{@@DEFS@@} in generated
2927 files with @option{-DHAVE_CONFIG_H} instead of the value of @code{DEFS}.
2928 The usual name for @var{header} is @file{config.h}.
2930 If @var{header} already exists and its contents are identical to what
2931 @code{AC_OUTPUT} would put in it, it is left alone.  Doing this allows
2932 making some changes in the configuration without needlessly causing
2933 object files that depend on the header file to be recompiled.
2935 Usually the input file is named @file{@var{header}.in}; however, you can
2936 override the input file name by appending to @var{header} a
2937 colon-separated list of input files.  Examples:
2939 @example
2940 AC_CONFIG_HEADERS([config.h:config.hin])
2941 AC_CONFIG_HEADERS([defines.h:defs.pre:defines.h.in:defs.post])
2942 @end example
2944 @noindent
2945 Doing this allows you to keep your file names acceptable to
2946 @acronym{DOS} variants, or
2947 to prepend and/or append boilerplate to the file.
2948 @end defmac
2950 @defmac AH_HEADER
2951 @ahindex{HEADER}
2952 This macro is defined as the name of the first declared config header
2953 and undefined if no config headers have been declared up to this point.
2954 A third-party macro may, for example, require use of a config header
2955 without invoking AC_CONFIG_HEADERS twice, like this:
2957 @example
2958 AC_CONFIG_COMMANDS_PRE(
2959         [m4_ifndef([AH_HEADER], [AC_CONFIG_HEADERS([config.h])])])
2960 @end example
2962 @end defmac
2964 @xref{Configuration Actions}, for more details on @var{header}.
2966 @menu
2967 * Header Templates::            Input for the configuration headers
2968 * autoheader Invocation::       How to create configuration templates
2969 * Autoheader Macros::           How to specify CPP templates
2970 @end menu
2972 @node Header Templates
2973 @subsection Configuration Header Templates
2974 @cindex Configuration Header Template
2975 @cindex Header templates
2976 @cindex @file{config.h.in}
2978 Your distribution should contain a template file that looks as you want
2979 the final header file to look, including comments, with @code{#undef}
2980 statements which are used as hooks.  For example, suppose your
2981 @file{configure.ac} makes these calls:
2983 @example
2984 AC_CONFIG_HEADERS([conf.h])
2985 AC_CHECK_HEADERS([unistd.h])
2986 @end example
2988 @noindent
2989 Then you could have code like the following in @file{conf.h.in}.  On
2990 systems that have @file{unistd.h}, @command{configure} defines
2991 @samp{HAVE_UNISTD_H} to 1.  On other systems, the whole line is
2992 commented out (in case the system predefines that symbol).
2994 @example
2995 @group
2996 /* Define as 1 if you have unistd.h.  */
2997 #undef HAVE_UNISTD_H
2998 @end group
2999 @end example
3001 Pay attention that @samp{#undef} is in the first column, and there is
3002 nothing after @samp{HAVE_UNISTD_H}, not even white space.  You can
3003 then decode the configuration header using the preprocessor directives:
3005 @example
3006 @group
3007 #include <conf.h>
3009 #ifdef HAVE_UNISTD_H
3010 # include <unistd.h>
3011 #else
3012 /* We are in trouble.  */
3013 #endif
3014 @end group
3015 @end example
3017 The use of old form templates, with @samp{#define} instead of
3018 @samp{#undef} is strongly discouraged.  Similarly with old templates
3019 with comments on the same line as the @samp{#undef}.  Anyway, putting
3020 comments in preprocessor macros has never been a good idea.
3022 Since it is a tedious task to keep a template header up to date, you may
3023 use @command{autoheader} to generate it, see @ref{autoheader Invocation}.
3026 @node autoheader Invocation
3027 @subsection Using @command{autoheader} to Create @file{config.h.in}
3028 @cindex @command{autoheader}
3030 The @command{autoheader} program can create a template file of C
3031 @samp{#define} statements for @command{configure} to use.  If
3032 @file{configure.ac} invokes @code{AC_CONFIG_HEADERS(@var{file})},
3033 @command{autoheader} creates @file{@var{file}.in}; if multiple file
3034 arguments are given, the first one is used.  Otherwise,
3035 @command{autoheader} creates @file{config.h.in}.
3037 In order to do its job, @command{autoheader} needs you to document all
3038 of the symbols that you might use.  Typically this is done via an
3039 @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED} call whose first argument
3040 is a literal symbol and whose third argument describes the symbol
3041 (@pxref{Defining Symbols}).  Alternatively, you can use
3042 @code{AH_TEMPLATE} (@pxref{Autoheader Macros}), or you can supply a
3043 suitable input file for a subsequent configuration header file.
3044 Symbols defined by Autoconf's builtin tests are already documented properly;
3045 you need to document only those that you
3046 define yourself.
3048 You might wonder why @command{autoheader} is needed: after all, why
3049 would @command{configure} need to ``patch'' a @file{config.h.in} to
3050 produce a @file{config.h} instead of just creating @file{config.h} from
3051 scratch?  Well, when everything rocks, the answer is just that we are
3052 wasting our time maintaining @command{autoheader}: generating
3053 @file{config.h} directly is all that is needed.  When things go wrong,
3054 however, you'll be thankful for the existence of @command{autoheader}.
3056 The fact that the symbols are documented is important in order to
3057 @emph{check} that @file{config.h} makes sense.  The fact that there is a
3058 well-defined list of symbols that should be defined (or not) is
3059 also important for people who are porting packages to environments where
3060 @command{configure} cannot be run: they just have to @emph{fill in the
3061 blanks}.
3063 But let's come back to the point: the invocation of @command{autoheader}@dots{}
3065 If you give @command{autoheader} an argument, it uses that file instead
3066 of @file{configure.ac} and writes the header file to the standard output
3067 instead of to @file{config.h.in}.  If you give @command{autoheader} an
3068 argument of @option{-}, it reads the standard input instead of
3069 @file{configure.ac} and writes the header file to the standard output.
3071 @command{autoheader} accepts the following options:
3073 @table @option
3074 @item --help
3075 @itemx -h
3076 Print a summary of the command line options and exit.
3078 @item --version
3079 @itemx -V
3080 Print the version number of Autoconf and exit.
3082 @item --verbose
3083 @itemx -v
3084 Report processing steps.
3086 @item --debug
3087 @itemx -d
3088 Don't remove the temporary files.
3090 @item --force
3091 @itemx -f
3092 Remake the template file even if newer than its input files.
3094 @item --include=@var{dir}
3095 @itemx -I @var{dir}
3096 Append @var{dir} to the include path.  Multiple invocations accumulate.
3098 @item --prepend-include=@var{dir}
3099 @item -B @var{dir}
3100 Prepend @var{dir} to the include path.  Multiple invocations accumulate.
3102 @item --warnings=@var{category}
3103 @itemx -W @var{category}
3104 @evindex WARNINGS
3105 Report the warnings related to @var{category} (which can actually be a
3106 comma separated list).  Current categories include:
3108 @table @samp
3109 @item obsolete
3110 report the uses of obsolete constructs
3112 @item all
3113 report all the warnings
3115 @item none
3116 report none
3118 @item error
3119 treats warnings as errors
3121 @item no-@var{category}
3122 disable warnings falling into @var{category}
3123 @end table
3125 @end table
3129 @node Autoheader Macros
3130 @subsection Autoheader Macros
3131 @cindex Autoheader macros
3133 @command{autoheader} scans @file{configure.ac} and figures out which C
3134 preprocessor symbols it might define.  It knows how to generate
3135 templates for symbols defined by @code{AC_CHECK_HEADERS},
3136 @code{AC_CHECK_FUNCS} etc., but if you @code{AC_DEFINE} any additional
3137 symbol, you must define a template for it.  If there are missing
3138 templates, @command{autoheader} fails with an error message.
3140 The simplest way to create a template for a @var{symbol} is to supply
3141 the @var{description} argument to an @samp{AC_DEFINE(@var{symbol})}; see
3142 @ref{Defining Symbols}.  You may also use one of the following macros.
3144 @defmac AH_VERBATIM (@var{key}, @var{template})
3145 @ahindex{VERBATIM}
3146 Tell @command{autoheader} to include the @var{template} as-is in the header
3147 template file.  This @var{template} is associated with the @var{key},
3148 which is used to sort all the different templates and guarantee their
3149 uniqueness.  It should be a symbol that can be defined via @code{AC_DEFINE}.
3151 For example:
3153 @example
3154 AH_VERBATIM([_GNU_SOURCE],
3155 [/* Enable GNU extensions on systems that have them.  */
3156 #ifndef _GNU_SOURCE
3157 # define _GNU_SOURCE
3158 #endif])
3159 @end example
3160 @end defmac
3163 @defmac AH_TEMPLATE (@var{key}, @var{description})
3164 @ahindex{TEMPLATE}
3165 Tell @command{autoheader} to generate a template for @var{key}.  This macro
3166 generates standard templates just like @code{AC_DEFINE} when a
3167 @var{description} is given.
3169 For example:
3171 @example
3172 AH_TEMPLATE([CRAY_STACKSEG_END],
3173             [Define to one of _getb67, GETB67, getb67
3174              for Cray-2 and Cray-YMP systems.  This
3175              function is required for alloca.c support
3176              on those systems.])
3177 @end example
3179 @noindent
3180 generates the following template, with the description properly
3181 justified.
3183 @example
3184 /* Define to one of _getb67, GETB67, getb67 for Cray-2 and
3185    Cray-YMP systems.  This function is required for alloca.c
3186    support on those systems.  */
3187 #undef CRAY_STACKSEG_END
3188 @end example
3189 @end defmac
3192 @defmac AH_TOP (@var{text})
3193 @ahindex{TOP}
3194 Include @var{text} at the top of the header template file.
3195 @end defmac
3198 @defmac AH_BOTTOM (@var{text})
3199 @ahindex{BOTTOM}
3200 Include @var{text} at the bottom of the header template file.
3201 @end defmac
3204 @node Configuration Commands
3205 @section Running Arbitrary Configuration Commands
3206 @cindex Configuration commands
3207 @cindex Commands for configuration
3209 You can execute arbitrary commands before, during, and after
3210 @file{config.status} is run.  The three following macros accumulate the
3211 commands to run when they are called multiple times.
3212 @code{AC_CONFIG_COMMANDS} replaces the obsolete macro
3213 @code{AC_OUTPUT_COMMANDS}; see @ref{Obsolete Macros}, for details.
3215 @defmac AC_CONFIG_COMMANDS (@var{tag}@dots{}, @ovar{cmds}, @ovar{init-cmds})
3216 @acindex{CONFIG_COMMANDS}
3217 Specify additional shell commands to run at the end of
3218 @file{config.status}, and shell commands to initialize any variables
3219 from @command{configure}.  Associate the commands with @var{tag}.
3220 Since typically the @var{cmds} create a file, @var{tag} should
3221 naturally be the name of that file.  If needed, the directory hosting
3222 @var{tag} is created.  This macro is one of the instantiating macros;
3223 see @ref{Configuration Actions}.
3225 Here is an unrealistic example:
3226 @example
3227 fubar=42
3228 AC_CONFIG_COMMANDS([fubar],
3229                    [echo this is extra $fubar, and so on.],
3230                    [fubar=$fubar])
3231 @end example
3233 Here is a better one:
3234 @example
3235 AC_CONFIG_COMMANDS([timestamp], [date >timestamp])
3236 @end example
3237 @end defmac
3239 The following two macros look similar, but in fact they are not of the same
3240 breed: they are executed directly by @file{configure}, so you cannot use
3241 @file{config.status} to rerun them.
3243 @c Yet it is good to leave them here.  The user sees them together and
3244 @c decides which best fits their needs.
3246 @defmac AC_CONFIG_COMMANDS_PRE (@var{cmds})
3247 @acindex{CONFIG_COMMANDS_PRE}
3248 Execute the @var{cmds} right before creating @file{config.status}.
3250 This macro presents the last opportunity to call @code{AC_SUBST},
3251 @code{AC_DEFINE}, or @code{AC_CONFIG_FOOS} macros.
3252 @end defmac
3254 @defmac AC_CONFIG_COMMANDS_POST (@var{cmds})
3255 @acindex{CONFIG_COMMANDS_POST}
3256 Execute the @var{cmds} right after creating @file{config.status}.
3257 @end defmac
3262 @node Configuration Links
3263 @section Creating Configuration Links
3264 @cindex Configuration links
3265 @cindex Links for configuration
3267 You may find it convenient to create links whose destinations depend upon
3268 results of tests.  One can use @code{AC_CONFIG_COMMANDS} but the
3269 creation of relative symbolic links can be delicate when the package is
3270 built in a directory different from the source directory.
3272 @defmac AC_CONFIG_LINKS (@var{dest}:@var{source}@dots{}, @ovar{cmds}, @ovar{init-cmds})
3273 @acindex{CONFIG_LINKS}
3274 @cindex Links
3275 Make @code{AC_OUTPUT} link each of the existing files @var{source} to
3276 the corresponding link name @var{dest}.  Makes a symbolic link if
3277 possible, otherwise a hard link if possible, otherwise a copy.  The
3278 @var{dest} and @var{source} names should be relative to the top level
3279 source or build directory.  This macro is one of the instantiating
3280 macros; see @ref{Configuration Actions}.
3282 For example, this call:
3284 @example
3285 AC_CONFIG_LINKS([host.h:config/$machine.h
3286                 object.h:config/$obj_format.h])
3287 @end example
3289 @noindent
3290 creates in the current directory @file{host.h} as a link to
3291 @file{@var{srcdir}/config/$machine.h}, and @file{object.h} as a
3292 link to @file{@var{srcdir}/config/$obj_format.h}.
3294 The tempting value @samp{.} for @var{dest} is invalid: it makes it
3295 impossible for @samp{config.status} to guess the links to establish.
3297 One can then run:
3298 @example
3299 ./config.status host.h object.h
3300 @end example
3301 @noindent
3302 to create the links.
3303 @end defmac
3307 @node Subdirectories
3308 @section Configuring Other Packages in Subdirectories
3309 @cindex Configure subdirectories
3310 @cindex Subdirectory configure
3312 In most situations, calling @code{AC_OUTPUT} is sufficient to produce
3313 makefiles in subdirectories.  However, @command{configure} scripts
3314 that control more than one independent package can use
3315 @code{AC_CONFIG_SUBDIRS} to run @command{configure} scripts for other
3316 packages in subdirectories.
3318 @defmac AC_CONFIG_SUBDIRS (@var{dir} @dots{})
3319 @acindex{CONFIG_SUBDIRS}
3320 @ovindex subdirs
3321 Make @code{AC_OUTPUT} run @command{configure} in each subdirectory
3322 @var{dir} in the given blank-or-newline-separated list.  Each @var{dir} should
3323 be a literal, i.e., please do not use:
3325 @example
3326 if test "$package_foo_enabled" = yes; then
3327   $my_subdirs="$my_subdirs foo"
3329 AC_CONFIG_SUBDIRS([$my_subdirs])
3330 @end example
3332 @noindent
3333 because this prevents @samp{./configure --help=recursive} from
3334 displaying the options of the package @code{foo}.  Instead, you should
3335 write:
3337 @example
3338 if test "$package_foo_enabled" = yes; then
3339   AC_CONFIG_SUBDIRS([foo])
3341 @end example
3343 If a given @var{dir} is not found, an error is reported: if the
3344 subdirectory is optional, write:
3346 @example
3347 if test -d "$srcdir/foo"; then
3348   AC_CONFIG_SUBDIRS([foo])
3350 @end example
3352 @c NB: Yes, below we mean configure.in, not configure.ac.
3353 If a given @var{dir} contains @command{configure.gnu}, it is run instead
3354 of @command{configure}.  This is for packages that might use a
3355 non-Autoconf script @command{Configure}, which can't be called through a
3356 wrapper @command{configure} since it would be the same file on
3357 case-insensitive file systems.  Likewise, if a @var{dir} contains
3358 @file{configure.in} but no @command{configure}, the Cygnus
3359 @command{configure} script found by @code{AC_CONFIG_AUX_DIR} is used.
3361 The subdirectory @command{configure} scripts are given the same command
3362 line options that were given to this @command{configure} script, with minor
3363 changes if needed, which include:
3365 @itemize @minus
3366 @item
3367 adjusting a relative name for the cache file;
3369 @item
3370 adjusting a relative name for the source directory;
3372 @item
3373 propagating the current value of @code{$prefix}, including if it was
3374 defaulted, and if the default values of the top level and of the subdirectory
3375 @file{configure} differ.
3376 @end itemize
3378 This macro also sets the output variable @code{subdirs} to the list of
3379 directories @samp{@var{dir} @dots{}}.  Make rules can use
3380 this variable to determine which subdirectories to recurse into.
3382 This macro may be called multiple times.
3383 @end defmac
3385 @node Default Prefix
3386 @section Default Prefix
3387 @cindex Install prefix
3388 @cindex Prefix for install
3390 By default, @command{configure} sets the prefix for files it installs to
3391 @file{/usr/local}.  The user of @command{configure} can select a different
3392 prefix using the @option{--prefix} and @option{--exec-prefix} options.
3393 There are two ways to change the default: when creating
3394 @command{configure}, and when running it.
3396 Some software packages might want to install in a directory other than
3397 @file{/usr/local} by default.  To accomplish that, use the
3398 @code{AC_PREFIX_DEFAULT} macro.
3400 @defmac AC_PREFIX_DEFAULT (@var{prefix})
3401 @acindex{PREFIX_DEFAULT}
3402 Set the default installation prefix to @var{prefix} instead of
3403 @file{/usr/local}.
3404 @end defmac
3406 It may be convenient for users to have @command{configure} guess the
3407 installation prefix from the location of a related program that they
3408 have already installed.  If you wish to do that, you can call
3409 @code{AC_PREFIX_PROGRAM}.
3411 @defmac AC_PREFIX_PROGRAM (@var{program})
3412 @acindex{PREFIX_PROGRAM}
3413 If the user did not specify an installation prefix (using the
3414 @option{--prefix} option), guess a value for it by looking for
3415 @var{program} in @env{PATH}, the way the shell does.  If @var{program}
3416 is found, set the prefix to the parent of the directory containing
3417 @var{program}, else default the prefix as described above
3418 (@file{/usr/local} or @code{AC_PREFIX_DEFAULT}).  For example, if
3419 @var{program} is @code{gcc} and the @env{PATH} contains
3420 @file{/usr/local/gnu/bin/gcc}, set the prefix to @file{/usr/local/gnu}.
3421 @end defmac
3425 @c ======================================================== Existing tests
3427 @node Existing Tests
3428 @chapter Existing Tests
3430 These macros test for particular system features that packages might
3431 need or want to use.  If you need to test for a kind of feature that
3432 none of these macros check for, you can probably do it by calling
3433 primitive test macros with appropriate arguments (@pxref{Writing
3434 Tests}).
3436 These tests print messages telling the user which feature they're
3437 checking for, and what they find.  They cache their results for future
3438 @command{configure} runs (@pxref{Caching Results}).
3440 Some of these macros set output variables.  @xref{Makefile
3441 Substitutions}, for how to get their values.  The phrase ``define
3442 @var{name}'' is used below as a shorthand to mean ``define the C
3443 preprocessor symbol @var{name} to the value 1''.  @xref{Defining
3444 Symbols}, for how to get those symbol definitions into your program.
3446 @menu
3447 * Common Behavior::             Macros' standard schemes
3448 * Alternative Programs::        Selecting between alternative programs
3449 * Files::                       Checking for the existence of files
3450 * Libraries::                   Library archives that might be missing
3451 * Library Functions::           C library functions that might be missing
3452 * Header Files::                Header files that might be missing
3453 * Declarations::                Declarations that may be missing
3454 * Structures::                  Structures or members that might be missing
3455 * Types::                       Types that might be missing
3456 * Compilers and Preprocessors::  Checking for compiling programs
3457 * System Services::             Operating system services
3458 * Posix Variants::              Special kludges for specific Posix variants
3459 * Erlang Libraries::            Checking for the existence of Erlang libraries
3460 @end menu
3462 @node Common Behavior
3463 @section Common Behavior
3464 @cindex Common autoconf behavior
3466 Much effort has been expended to make Autoconf easy to learn.  The most
3467 obvious way to reach this goal is simply to enforce standard interfaces
3468 and behaviors, avoiding exceptions as much as possible.  Because of
3469 history and inertia, unfortunately, there are still too many exceptions
3470 in Autoconf; nevertheless, this section describes some of the common
3471 rules.
3473 @menu
3474 * Standard Symbols::            Symbols defined by the macros
3475 * Default Includes::            Includes used by the generic macros
3476 @end menu
3478 @node Standard Symbols
3479 @subsection Standard Symbols
3480 @cindex Standard symbols
3482 All the generic macros that @code{AC_DEFINE} a symbol as a result of
3483 their test transform their @var{argument} values to a standard alphabet.
3484 First, @var{argument} is converted to upper case and any asterisks
3485 (@samp{*}) are each converted to @samp{P}.  Any remaining characters
3486 that are not alphanumeric are converted to underscores.
3488 For instance,
3490 @example
3491 AC_CHECK_TYPES([struct $Expensive*])
3492 @end example
3494 @noindent
3495 defines the symbol @samp{HAVE_STRUCT__EXPENSIVEP} if the check
3496 succeeds.
3499 @node Default Includes
3500 @subsection Default Includes
3501 @cindex Default includes
3502 @cindex Includes, default
3504 Several tests depend upon a set of header files.  Since these headers
3505 are not universally available, tests actually have to provide a set of
3506 protected includes, such as:
3508 @example
3509 @group
3510 #ifdef TIME_WITH_SYS_TIME
3511 # include <sys/time.h>
3512 # include <time.h>
3513 #else
3514 # ifdef HAVE_SYS_TIME_H
3515 #  include <sys/time.h>
3516 # else
3517 #  include <time.h>
3518 # endif
3519 #endif
3520 @end group
3521 @end example
3523 @noindent
3524 Unless you know exactly what you are doing, you should avoid using
3525 unconditional includes, and check the existence of the headers you
3526 include beforehand (@pxref{Header Files}).
3528 Most generic macros use the following macro to provide the default set
3529 of includes:
3531 @defmac AC_INCLUDES_DEFAULT (@ovar{include-directives})
3532 @acindex{INCLUDES_DEFAULT}
3533 Expand to @var{include-directives} if defined, otherwise to:
3535 @example
3536 @group
3537 #include <stdio.h>
3538 #ifdef HAVE_SYS_TYPES_H
3539 # include <sys/types.h>
3540 #endif
3541 #ifdef HAVE_SYS_STAT_H
3542 # include <sys/stat.h>
3543 #endif
3544 #ifdef STDC_HEADERS
3545 # include <stdlib.h>
3546 # include <stddef.h>
3547 #else
3548 # ifdef HAVE_STDLIB_H
3549 #  include <stdlib.h>
3550 # endif
3551 #endif
3552 #ifdef HAVE_STRING_H
3553 # if !defined STDC_HEADERS && defined HAVE_MEMORY_H
3554 #  include <memory.h>
3555 # endif
3556 # include <string.h>
3557 #endif
3558 #ifdef HAVE_STRINGS_H
3559 # include <strings.h>
3560 #endif
3561 #ifdef HAVE_INTTYPES_H
3562 # include <inttypes.h>
3563 #endif
3564 #ifdef HAVE_STDINT_H
3565 # include <stdint.h>
3566 #endif
3567 #ifdef HAVE_UNISTD_H
3568 # include <unistd.h>
3569 #endif
3570 @end group
3571 @end example
3573 If the default includes are used, then check for the presence of these
3574 headers and their compatibility, i.e., you don't need to run
3575 @code{AC_HEADER_STDC}, nor check for @file{stdlib.h} etc.
3577 These headers are checked for in the same order as they are included.
3578 For instance, on some systems @file{string.h} and @file{strings.h} both
3579 exist, but conflict.  Then @code{HAVE_STRING_H} is defined, not
3580 @code{HAVE_STRINGS_H}.
3581 @end defmac
3583 @node Alternative Programs
3584 @section Alternative Programs
3585 @cindex Programs, checking
3587 These macros check for the presence or behavior of particular programs.
3588 They are used to choose between several alternative programs and to
3589 decide what to do once one has been chosen.  If there is no macro
3590 specifically defined to check for a program you need, and you don't need
3591 to check for any special properties of it, then you can use one of the
3592 general program-check macros.
3594 @menu
3595 * Particular Programs::         Special handling to find certain programs
3596 * Generic Programs::            How to find other programs
3597 @end menu
3599 @node Particular Programs
3600 @subsection Particular Program Checks
3602 These macros check for particular programs---whether they exist, and
3603 in some cases whether they support certain features.
3605 @defmac AC_PROG_AWK
3606 @acindex{PROG_AWK}
3607 @ovindex AWK
3608 Check for @code{gawk}, @code{mawk}, @code{nawk}, and @code{awk}, in that
3609 order, and set output variable @code{AWK} to the first one that is found.
3610 It tries @code{gawk} first because that is reported to be the
3611 best implementation.
3612 @end defmac
3614 @defmac AC_PROG_GREP
3615 @acindex{PROG_GREP}
3616 @ovindex GREP
3617 Look for the best available @code{grep} or @code{ggrep} that accepts the
3618 longest input lines possible, and that supports multiple @option{-e} options.
3619 Set the output variable @code{GREP} to whatever is chosen.
3620 @xref{Limitations of Usual Tools}, for more information about
3621 portability problems with the @command{grep} command family.
3622 @end defmac
3624 @defmac AC_PROG_EGREP
3625 @acindex{PROG_EGREP}
3626 @ovindex EGREP
3627 Check whether @code{$GREP -E} works, or else look for the best available
3628 @code{egrep} or @code{gegrep} that accepts the longest input lines possible.
3629 Set the output variable @code{EGREP} to whatever is chosen.
3630 @end defmac
3632 @defmac AC_PROG_FGREP
3633 @acindex{PROG_FGREP}
3634 @ovindex FGREP
3635 Check whether @code{$GREP -F} works, or else look for the best available
3636 @code{fgrep} or @code{gfgrep} that accepts the longest input lines possible.
3637 Set the output variable @code{FGREP} to whatever is chosen.
3638 @end defmac
3640 @defmac AC_PROG_INSTALL
3641 @acindex{PROG_INSTALL}
3642 @ovindex INSTALL
3643 @ovindex INSTALL_PROGRAM
3644 @ovindex INSTALL_DATA
3645 @ovindex INSTALL_SCRIPT
3646 Set output variable @code{INSTALL} to the name of a @acronym{BSD}-compatible
3647 @command{install} program, if one is found in the current @env{PATH}.
3648 Otherwise, set @code{INSTALL} to @samp{@var{dir}/install-sh -c},
3649 checking the directories specified to @code{AC_CONFIG_AUX_DIR} (or its
3650 default directories) to determine @var{dir} (@pxref{Output}).  Also set
3651 the variables @code{INSTALL_PROGRAM} and @code{INSTALL_SCRIPT} to
3652 @samp{$@{INSTALL@}} and @code{INSTALL_DATA} to @samp{$@{INSTALL@} -m 644}.
3654 @samp{@@INSTALL@@} is special, as its value may vary for different
3655 configuration files.
3657 This macro screens out various instances of @command{install} known not to
3658 work.  It prefers to find a C program rather than a shell script, for
3659 speed.  Instead of @file{install-sh}, it can also use @file{install.sh},
3660 but that name is obsolete because some @command{make} programs have a rule
3661 that creates @file{install} from it if there is no makefile.
3663 Autoconf comes with a copy of @file{install-sh} that you can use.  If
3664 you use @code{AC_PROG_INSTALL}, you must include either
3665 @file{install-sh} or @file{install.sh} in your distribution; otherwise
3666 @command{configure} produces an error message saying it can't find
3667 them---even if the system you're on has a good @command{install} program.
3668 This check is a safety measure to prevent you from accidentally leaving
3669 that file out, which would prevent your package from installing on
3670 systems that don't have a @acronym{BSD}-compatible @command{install} program.
3672 If you need to use your own installation program because it has features
3673 not found in standard @command{install} programs, there is no reason to use
3674 @code{AC_PROG_INSTALL}; just put the file name of your program into your
3675 @file{Makefile.in} files.
3676 @end defmac
3678 @defmac AC_PROG_MKDIR_P
3679 @acindex{AC_PROG_MKDIR_P}
3680 @ovindex MKDIR_P
3681 Set output variable @code{MKDIR_P} to a program that ensures that for
3682 each argument, a directory named by this argument exists, creating it
3683 and its parent directories if needed, and without race conditions when
3684 two instances of the program attempt to make the same directory at
3685 nearly the same time.
3687 This macro uses the @samp{mkdir -p} command if possible.  Otherwise, it
3688 falls back on invoking @command{install-sh} with the @option{-d} option,
3689 so your package should
3690 contain @file{install-sh} as described under @code{AC_PROG_INSTALL}.
3691 An @file{install-sh} file that predates Autoconf 2.60 or Automake 1.10
3692 is vulnerable to race conditions, so if you want to support parallel
3693 installs from
3694 different packages into the same directory you need to make sure you
3695 have an up-to-date @file{install-sh}.  In particular, be careful about
3696 using @samp{autoreconf -if} if your Automake predates Automake 1.10.
3698 This macro is related to the @code{AS_MKDIR_P} macro (@pxref{Programming
3699 in M4sh}), but it sets an output variable intended for use in other
3700 files, whereas @code{AS_MKDIR_P} is intended for use in scripts like
3701 @command{configure}.  Also, @code{AS_MKDIR_P} does not accept options,
3702 but @code{MKDIR_P} supports the @option{-m} option, e.g., a makefile
3703 might invoke @code{$(MKDIR_P) -m 0 dir} to create an inaccessible
3704 directory, and conversely a makefile should use @code{$(MKDIR_P) --
3705 $(FOO)} if @var{FOO} might yield a value that begins with @samp{-}.
3706 Finally, @code{AS_MKDIR_P} does not check for race condition
3707 vulnerability, whereas @code{AC_PROG_MKDIR_P} does.
3709 @samp{@@MKDIR_P@@} is special, as its value may vary for different
3710 configuration files.
3711 @end defmac
3713 @defmac AC_PROG_LEX
3714 @acindex{PROG_LEX}
3715 @ovindex LEX
3716 @ovindex LEXLIB
3717 @cvindex YYTEXT_POINTER
3718 @ovindex LEX_OUTPUT_ROOT
3719 If @code{flex} is found, set output variable @code{LEX} to @samp{flex}
3720 and @code{LEXLIB} to @option{-lfl}, if that library is in a standard
3721 place.  Otherwise set @code{LEX} to @samp{lex} and @code{LEXLIB} to
3722 @option{-ll}.
3724 Define @code{YYTEXT_POINTER} if @code{yytext} defaults to @samp{char *} instead
3725 of to @samp{char []}.  Also set output variable @code{LEX_OUTPUT_ROOT} to
3726 the base of the file name that the lexer generates; usually
3727 @file{lex.yy}, but sometimes something else.  These results vary
3728 according to whether @code{lex} or @code{flex} is being used.
3730 You are encouraged to use Flex in your sources, since it is both more
3731 pleasant to use than plain Lex and the C source it produces is portable.
3732 In order to ensure portability, however, you must either provide a
3733 function @code{yywrap} or, if you don't use it (e.g., your scanner has
3734 no @samp{#include}-like feature), simply include a @samp{%noyywrap}
3735 statement in the scanner's source.  Once this done, the scanner is
3736 portable (unless @emph{you} felt free to use nonportable constructs) and
3737 does not depend on any library.  In this case, and in this case only, it
3738 is suggested that you use this Autoconf snippet:
3740 @example
3741 AC_PROG_LEX
3742 if test "$LEX" != flex; then
3743   LEX="$SHELL $missing_dir/missing flex"
3744   AC_SUBST([LEX_OUTPUT_ROOT], [lex.yy])
3745   AC_SUBST([LEXLIB], [''])
3747 @end example
3749 The shell script @command{missing} can be found in the Automake
3750 distribution.
3752 To ensure backward compatibility, Automake's @code{AM_PROG_LEX} invokes
3753 (indirectly) this macro twice, which causes an annoying but benign
3754 ``@code{AC_PROG_LEX} invoked multiple times'' warning.  Future versions
3755 of Automake will fix this issue; meanwhile, just ignore this message.
3757 As part of running the test, this macro may delete any file in the
3758 configuration directory named @file{lex.yy.c} or @file{lexyy.c}.
3759 @end defmac
3761 @defmac AC_PROG_LN_S
3762 @acindex{PROG_LN_S}
3763 @ovindex LN_S
3764 If @samp{ln -s} works on the current file system (the operating system
3765 and file system support symbolic links), set the output variable
3766 @code{LN_S} to @samp{ln -s}; otherwise, if @samp{ln} works, set
3767 @code{LN_S} to @samp{ln}, and otherwise set it to @samp{cp -p}.
3769 If you make a link in a directory other than the current directory, its
3770 meaning depends on whether @samp{ln} or @samp{ln -s} is used.  To safely
3771 create links using @samp{$(LN_S)}, either find out which form is used
3772 and adjust the arguments, or always invoke @code{ln} in the directory
3773 where the link is to be created.
3775 In other words, it does not work to do:
3776 @example
3777 $(LN_S) foo /x/bar
3778 @end example
3780 Instead, do:
3782 @example
3783 (cd /x && $(LN_S) foo bar)
3784 @end example
3785 @end defmac
3787 @defmac AC_PROG_RANLIB
3788 @acindex{PROG_RANLIB}
3789 @ovindex RANLIB
3790 Set output variable @code{RANLIB} to @samp{ranlib} if @code{ranlib}
3791 is found, and otherwise to @samp{:} (do nothing).
3792 @end defmac
3794 @defmac AC_PROG_SED
3795 @acindex{PROG_SED}
3796 @ovindex SED
3797 Set output variable @code{SED} to a Sed implementation that conforms to
3798 Posix and does not have arbitrary length limits.  Report an error if no
3799 acceptable Sed is found.  @xref{Limitations of Usual Tools}, for more
3800 information about portability problems with Sed.
3801 @end defmac
3803 @defmac AC_PROG_YACC
3804 @acindex{PROG_YACC}
3805 @ovindex YACC
3806 If @code{bison} is found, set output variable @code{YACC} to @samp{bison
3807 -y}.  Otherwise, if @code{byacc} is found, set @code{YACC} to
3808 @samp{byacc}.  Otherwise set @code{YACC} to @samp{yacc}.
3809 @end defmac
3811 @node Generic Programs
3812 @subsection Generic Program and File Checks
3814 These macros are used to find programs not covered by the ``particular''
3815 test macros.  If you need to check the behavior of a program as well as
3816 find out whether it is present, you have to write your own test for it
3817 (@pxref{Writing Tests}).  By default, these macros use the environment
3818 variable @env{PATH}.  If you need to check for a program that might not
3819 be in the user's @env{PATH}, you can pass a modified path to use
3820 instead, like this:
3822 @example
3823 AC_PATH_PROG([INETD], [inetd], [/usr/libexec/inetd],
3824              [$PATH:/usr/libexec:/usr/sbin:/usr/etc:/etc])
3825 @end example
3827 You are strongly encouraged to declare the @var{variable} passed to
3828 @code{AC_CHECK_PROG} etc.@: as precious, @xref{Setting Output Variables},
3829 @code{AC_ARG_VAR}, for more details.
3831 @defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @var{value-if-found}, @ovar{value-if-not-found}, @ovar{path},  @ovar{reject})
3832 @acindex{CHECK_PROG}
3833 Check whether program @var{prog-to-check-for} exists in @env{PATH}.  If
3834 it is found, set @var{variable} to @var{value-if-found}, otherwise to
3835 @var{value-if-not-found}, if given.  Always pass over @var{reject} (an
3836 absolute file name) even if it is the first found in the search path; in
3837 that case, set @var{variable} using the absolute file name of the
3838 @var{prog-to-check-for} found that is not @var{reject}.  If
3839 @var{variable} was already set, do nothing.  Calls @code{AC_SUBST} for
3840 @var{variable}.
3841 @end defmac
3843 @defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3844 @acindex{CHECK_PROGS}
3845 Check for each program in the blank-separated list
3846 @var{progs-to-check-for} existing in the @env{PATH}.  If one is found, set
3847 @var{variable} to the name of that program.  Otherwise, continue
3848 checking the next program in the list.  If none of the programs in the
3849 list are found, set @var{variable} to @var{value-if-not-found}; if
3850 @var{value-if-not-found} is not specified, the value of @var{variable}
3851 is not changed.  Calls @code{AC_SUBST} for @var{variable}.
3852 @end defmac
3854 @defmac AC_CHECK_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3855 @acindex{CHECK_TARGET_TOOL}
3856 Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
3857 with a prefix of the target type as determined by
3858 @code{AC_CANONICAL_TARGET}, followed by a dash (@pxref{Canonicalizing}).
3859 If the tool cannot be found with a prefix, and if the build and target
3860 types are equal, then it is also searched for without a prefix.
3862 As noted in @ref{Specifying Names, , Specifying the system type}, the
3863 target is rarely specified, because most of the time it is the same
3864 as the host: it is the type of system for which any compiler tool in
3865 the package produces code.  What this macro looks for is,
3866 for example, @emph{a tool @r{(assembler, linker, etc.)}@: that the
3867 compiler driver @r{(@command{gcc} for the @acronym{GNU} C Compiler)}
3868 uses to produce objects, archives or executables}.
3869 @end defmac
3871 @defmac AC_CHECK_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3872 @acindex{CHECK_TOOL}
3873 Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
3874 with a prefix of the host type as determined by
3875 @code{AC_CANONICAL_HOST}, followed by a dash (@pxref{Canonicalizing}).
3876 For example, if the user runs @samp{configure --host=i386-gnu}, then
3877 this call:
3878 @example
3879 AC_CHECK_TOOL([RANLIB], [ranlib], [:])
3880 @end example
3881 @noindent
3882 sets @code{RANLIB} to @file{i386-gnu-ranlib} if that program exists in
3883 @env{PATH}, or otherwise to @samp{ranlib} if that program exists in
3884 @env{PATH}, or to @samp{:} if neither program exists.
3886 In the future, when cross-compiling this macro will @emph{only}
3887 accept program names that are prefixed with the host type.
3888 For more information, see @ref{Specifying Names, , Specifying the
3889 system type}.
3890 @end defmac
3892 @defmac AC_CHECK_TARGET_TOOLS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3893 @acindex{CHECK_TARGET_TOOLS}
3894 Like @code{AC_CHECK_TARGET_TOOL}, each of the tools in the list
3895 @var{progs-to-check-for} are checked with a prefix of the target type as
3896 determined by @code{AC_CANONICAL_TARGET}, followed by a dash
3897 (@pxref{Canonicalizing}).  If none of the tools can be found with a
3898 prefix, and if the build and target types are equal, then the first one
3899 without a prefix is used.  If a tool is found, set @var{variable} to
3900 the name of that program.  If none of the tools in the list are found,
3901 set @var{variable} to @var{value-if-not-found}; if @var{value-if-not-found}
3902 is not specified, the value of @var{variable} is not changed.  Calls
3903 @code{AC_SUBST} for @var{variable}.
3904 @end defmac
3906 @defmac AC_CHECK_TOOLS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3907 @acindex{CHECK_TOOLS}
3908 Like @code{AC_CHECK_TOOL}, each of the tools in the list
3909 @var{progs-to-check-for} are checked with a prefix of the host type as
3910 determined by @code{AC_CANONICAL_HOST}, followed by a dash
3911 (@pxref{Canonicalizing}).  If none of the tools can be found with a
3912 prefix, then the first one without a prefix is used.  If a tool is found,
3913 set @var{variable} to the name of that program.  If none of the tools in
3914 the list are found, set @var{variable} to @var{value-if-not-found}; if
3915 @var{value-if-not-found} is not specified, the value of @var{variable}
3916 is not changed.  Calls @code{AC_SUBST} for @var{variable}.
3918 In the future, when cross-compiling this macro will @emph{not}
3919 accept program names that are not prefixed with the host type.
3920 @end defmac
3922 @defmac AC_PATH_PROG (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3923 @acindex{PATH_PROG}
3924 Like @code{AC_CHECK_PROG}, but set @var{variable} to the absolute
3925 name of @var{prog-to-check-for} if found.
3926 @end defmac
3928 @defmac AC_PATH_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3929 @acindex{PATH_PROGS}
3930 Like @code{AC_CHECK_PROGS}, but if any of @var{progs-to-check-for}
3931 are found, set @var{variable} to the absolute name of the program
3932 found.
3933 @end defmac
3935 @defmac AC_PATH_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3936 @acindex{PATH_TARGET_TOOL}
3937 Like @code{AC_CHECK_TARGET_TOOL}, but set @var{variable} to the absolute
3938 name of the program if it is found.
3939 @end defmac
3941 @defmac AC_PATH_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3942 @acindex{PATH_TOOL}
3943 Like @code{AC_CHECK_TOOL}, but set @var{variable} to the absolute
3944 name of the program if it is found.
3946 In the future, when cross-compiling this macro will @emph{not}
3947 accept program names that are not prefixed with the host type.
3948 @end defmac
3951 @node Files
3952 @section Files
3953 @cindex File, checking
3955 You might also need to check for the existence of files.  Before using
3956 these macros, ask yourself whether a runtime test might not be a better
3957 solution.  Be aware that, like most Autoconf macros, they test a feature
3958 of the host machine, and therefore, they die when cross-compiling.
3960 @defmac AC_CHECK_FILE (@var{file}, @ovar{action-if-found}, @ovar{action-if-not-found})
3961 @acindex{CHECK_FILE}
3962 Check whether file @var{file} exists on the native system.  If it is
3963 found, execute @var{action-if-found}, otherwise do
3964 @var{action-if-not-found}, if given.
3965 @end defmac
3967 @defmac AC_CHECK_FILES (@var{files}, @ovar{action-if-found}, @ovar{action-if-not-found})
3968 @acindex{CHECK_FILES}
3969 Executes @code{AC_CHECK_FILE} once for each file listed in @var{files}.
3970 Additionally, defines @samp{HAVE_@var{file}} (@pxref{Standard Symbols})
3971 for each file found.
3972 @end defmac
3975 @node Libraries
3976 @section Library Files
3977 @cindex Library, checking
3979 The following macros check for the presence of certain C, C++, or Fortran
3980 library archive files.
3982 @defmac AC_CHECK_LIB (@var{library}, @var{function}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
3983 @acindex{CHECK_LIB}
3984 Test whether the library @var{library} is available by trying to link
3985 a test program that calls function @var{function} with the library.
3986 @var{function} should be a function provided by the library.
3987 Use the base
3988 name of the library; e.g., to check for @option{-lmp}, use @samp{mp} as
3989 the @var{library} argument.
3991 @var{action-if-found} is a list of shell commands to run if the link
3992 with the library succeeds; @var{action-if-not-found} is a list of shell
3993 commands to run if the link fails.  If @var{action-if-found} is not
3994 specified, the default action prepends @option{-l@var{library}} to
3995 @code{LIBS} and defines @samp{HAVE_LIB@var{library}} (in all
3996 capitals).  This macro is intended to support building @code{LIBS} in
3997 a right-to-left (least-dependent to most-dependent) fashion such that
3998 library dependencies are satisfied as a natural side effect of
3999 consecutive tests.  Linkers are sensitive to library ordering
4000 so the order in which @code{LIBS} is generated is important to reliable
4001 detection of libraries.
4003 If linking with @var{library} results in unresolved symbols that would
4004 be resolved by linking with additional libraries, give those libraries
4005 as the @var{other-libraries} argument, separated by spaces:
4006 e.g., @option{-lXt -lX11}.  Otherwise, this macro fails to detect
4007 that @var{library} is present, because linking the test program
4008 always fails with unresolved symbols.  The @var{other-libraries} argument
4009 should be limited to cases where it is desirable to test for one library
4010 in the presence of another that is not already in @code{LIBS}.
4012 @code{AC_CHECK_LIB} requires some care in usage, and should be avoided
4013 in some common cases.  Many standard functions like @code{gethostbyname}
4014 appear the standard C library on some hosts, and in special libraries
4015 like @code{nsl} on other hosts.  On some hosts the special libraries
4016 contain variant implementations that you may not want to use.  These
4017 days it is normally better to use @code{AC_SEARCH_LIBS([gethostbyname],
4018 [nsl])} instead of @code{AC_CHECK_LIB([nsl], [gethostbyname])}.
4019 @end defmac
4022 @defmac AC_SEARCH_LIBS (@var{function}, @var{search-libs}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
4023 @acindex{SEARCH_LIBS}
4024 Search for a library defining @var{function} if it's not already
4025 available.  This equates to calling
4026 @samp{AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])])} first with
4027 no libraries, then for each library listed in @var{search-libs}.
4029 Add @option{-l@var{library}} to @code{LIBS} for the first library found
4030 to contain @var{function}, and run @var{action-if-found}.  If the
4031 function is not found, run @var{action-if-not-found}.
4033 If linking with @var{library} results in unresolved symbols that would
4034 be resolved by linking with additional libraries, give those libraries
4035 as the @var{other-libraries} argument, separated by spaces:
4036 e.g., @option{-lXt -lX11}.  Otherwise, this macro fails to detect
4037 that @var{function} is present, because linking the test program
4038 always fails with unresolved symbols.
4039 @end defmac
4043 @node Library Functions
4044 @section Library Functions
4046 The following macros check for particular C library functions.
4047 If there is no macro specifically defined to check for a function you need,
4048 and you don't need to check for any special properties of
4049 it, then you can use one of the general function-check macros.
4051 @menu
4052 * Function Portability::        Pitfalls with usual functions
4053 * Particular Functions::        Special handling to find certain functions
4054 * Generic Functions::           How to find other functions
4055 @end menu
4057 @node Function Portability
4058 @subsection Portability of C Functions
4059 @cindex Portability of C functions
4060 @cindex C function portability
4062 Most usual functions can either be missing, or be buggy, or be limited
4063 on some architectures.  This section tries to make an inventory of these
4064 portability issues.  By definition, this list always requires
4065 additions.  Please help us keeping it as complete as possible.
4067 @table @asis
4068 @item @code{exit}
4069 @c @fuindex exit
4070 @prindex @code{exit}
4071 On ancient hosts, @code{exit} returned @code{int}.
4072 This is because @code{exit} predates @code{void}, and there was a long
4073 tradition of it returning @code{int}.
4075 On current hosts, the problem more likely is that @code{exit} is not
4076 declared, due to C++ problems of some sort or another.  For this reason
4077 we suggest that test programs not invoke @code{exit}, but return from
4078 @code{main} instead.
4080 @item @code{free}
4081 @c @fuindex free
4082 @prindex @code{free}
4083 The C standard says a call @code{free (NULL)} does nothing, but
4084 some old systems don't support this (e.g., NextStep).
4086 @item @code{isinf}
4087 @itemx @code{isnan}
4088 @c @fuindex isinf
4089 @c @fuindex isnan
4090 @prindex @code{isinf}
4091 @prindex @code{isnan}
4092 The C99 standard says that @code{isinf} and @code{isnan} are
4093 macros.  On some systems just macros are available
4094 (e.g., @acronym{HP-UX} and Solaris 10), on
4095 some systems both macros and functions (e.g., glibc 2.3.2), and on some
4096 systems only functions (e.g., IRIX 6 and Solaris 9).  In some cases
4097 these functions are declared in nonstandard headers like
4098 @code{<sunmath.h>} and defined in non-default libraries like
4099 @option{-lm} or @option{-lsunmath}.
4101 The C99 @code{isinf} and @code{isnan} macros work correctly with
4102 @code{long double} arguments, but pre-C99 systems that use functions
4103 typically assume @code{double} arguments.  On such a system,
4104 @code{isinf} incorrectly returns true for a finite @code{long double}
4105 argument that is outside the range of @code{double}.
4107 To work around this porting mess, you can use code like the following.
4109 @smallexample
4110 #include <math.h>
4112 #ifndef isnan
4113 # define isnan(x) \
4114     (sizeof (x) == sizeof (long double) ? isnan_ld (x) \
4115      : sizeof (x) == sizeof (double) ? isnan_d (x) \
4116      : isnan_f (x))
4117 static inline int isnan_f  (float       x) @{ return x != x; @}
4118 static inline int isnan_d  (double      x) @{ return x != x; @}
4119 static inline int isnan_ld (long double x) @{ return x != x; @}
4120 #endif
4122 #ifndef isinf
4123 # define isinf(x) \
4124     (sizeof (x) == sizeof (long double) ? isinf_ld (x) \
4125      : sizeof (x) == sizeof (double) ? isinf_d (x) \
4126      : isinf_f (x))
4127 static inline int isinf_f  (float       x) @{ return isnan (x - x); @}
4128 static inline int isinf_d  (double      x) @{ return isnan (x - x); @}
4129 static inline int isinf_ld (long double x) @{ return isnan (x - x); @}
4130 #endif
4131 @end smallexample
4133 Use @code{AC_C_INLINE} (@pxref{C Compiler}) so that this code works on
4134 compilers that lack the @code{inline} keyword.  Some optimizing
4135 compilers mishandle these definitions, but systems with that bug
4136 typically have missing or broken @code{isnan} functions anyway, so it's
4137 probably not worth worrying about.
4139 @item @code{malloc}
4140 @c @fuindex malloc
4141 @prindex @code{malloc}
4142 The C standard says a call @code{malloc (0)} is implementation
4143 dependent.  It can return either @code{NULL} or a new non-null pointer.
4144 The latter is more common (e.g., the @acronym{GNU} C Library) but is by
4145 no means universal.  @code{AC_FUNC_MALLOC}
4146 can be used to insist on non-@code{NULL} (@pxref{Particular Functions}).
4148 @item @code{putenv}
4149 @c @fuindex putenv
4150 @prindex @code{putenv}
4151 Posix prefers @code{setenv} to @code{putenv}; among other things,
4152 @code{putenv} is not required of all Posix implementations, but
4153 @code{setenv} is.
4155 Posix specifies that @code{putenv} puts the given string directly in
4156 @code{environ}, but some systems make a copy of it instead (e.g.,
4157 glibc 2.0, or @acronym{BSD}).  And when a copy is made, @code{unsetenv} might
4158 not free it, causing a memory leak (e.g., Free@acronym{BSD} 4).
4160 On some systems @code{putenv ("FOO")} removes @samp{FOO} from the
4161 environment, but this is not standard usage and it dumps core
4162 on some systems (e.g., AIX).
4164 On MinGW, a call @code{putenv ("FOO=")} removes @samp{FOO} from the
4165 environment, rather than inserting it with an empty value.
4167 @item @code{realloc}
4168 @c @fuindex realloc
4169 @prindex @code{realloc}
4170 The C standard says a call @code{realloc (NULL, size)} is equivalent
4171 to @code{malloc (size)}, but some old systems don't support this (e.g.,
4172 NextStep).
4174 @item @code{signal} handler
4175 @c @fuindex signal
4176 @prindex @code{signal}
4177 Normally @code{signal} takes a handler function with a return type of
4178 @code{void}, but some old systems required @code{int} instead.  Any
4179 actual @code{int} value returned is not used; this is only a
4180 difference in the function prototype demanded.
4182 All systems we know of in current use return @code{void}.  The
4183 @code{int} was to support K&R C, where of course @code{void} is not
4184 available.  @code{AC_TYPE_SIGNAL} (@pxref{Particular Types}) can be
4185 used to establish the correct type in all cases.
4187 @item @code{snprintf}
4188 @c @fuindex snprintf
4189 @prindex @code{snprintf}
4190 @c @fuindex vsnprintf
4191 @prindex @code{vsnprintf}
4192 The C99 standard says that if the output array isn't big enough
4193 and if no other errors occur, @code{snprintf} and @code{vsnprintf}
4194 truncate the output and return the number of bytes that ought to have
4195 been produced.  Some older systems return the truncated length (e.g.,
4196 @acronym{GNU} C Library 2.0.x or @sc{irix} 6.5), some a negative value
4197 (e.g., earlier @acronym{GNU} C Library versions), and some the buffer
4198 length without truncation (e.g., 32-bit Solaris 7).  Also, some buggy
4199 older systems ignore the length and overrun the buffer (e.g., 64-bit
4200 Solaris 7).
4202 @item @code{sprintf}
4203 @c @fuindex sprintf
4204 @prindex @code{sprintf}
4205 @c @fuindex vsprintf
4206 @prindex @code{vsprintf}
4207 The C standard says @code{sprintf} and @code{vsprintf} return the
4208 number of bytes written.  On some ancient systems (SunOS 4 for
4209 instance) they return the buffer pointer instead, but these no
4210 longer need to be worried about.
4212 @item @code{sscanf}
4213 @c @fuindex sscanf
4214 @prindex @code{sscanf}
4215 On various old systems, e.g., @acronym{HP-UX} 9, @code{sscanf} requires that its
4216 input string be writable (though it doesn't actually change it).  This
4217 can be a problem when using @command{gcc} since it normally puts
4218 constant strings in read-only memory (@pxref{Incompatibilities,
4219 Incompatibilities of @acronym{GCC}, , gcc, Using and
4220 Porting the @acronym{GNU} Compiler Collection}).  Apparently in some cases even
4221 having format strings read-only can be a problem.
4223 @item @code{strerror_r}
4224 @c @fuindex strerror_r
4225 @prindex @code{strerror_r}
4226 Posix specifies that @code{strerror_r} returns an @code{int}, but many
4227 systems (e.g., @acronym{GNU} C Library version 2.2.4) provide a
4228 different version returning a @code{char *}.  @code{AC_FUNC_STRERROR_R}
4229 can detect which is in use (@pxref{Particular Functions}).
4231 @item @code{strnlen}
4232 @c @fuindex strnlen
4233 @prindex @code{strnlen}
4234 @acronym{AIX} 4.3 provides a broken version which produces the
4235 following results:
4237 @example
4238 strnlen ("foobar", 0) = 0
4239 strnlen ("foobar", 1) = 3
4240 strnlen ("foobar", 2) = 2
4241 strnlen ("foobar", 3) = 1
4242 strnlen ("foobar", 4) = 0
4243 strnlen ("foobar", 5) = 6
4244 strnlen ("foobar", 6) = 6
4245 strnlen ("foobar", 7) = 6
4246 strnlen ("foobar", 8) = 6
4247 strnlen ("foobar", 9) = 6
4248 @end example
4250 @item @code{sysconf}
4251 @c @fuindex sysconf
4252 @prindex @code{sysconf}
4253 @code{_SC_PAGESIZE} is standard, but some older systems (e.g., @acronym{HP-UX}
4254 9) have @code{_SC_PAGE_SIZE} instead.  This can be tested with
4255 @code{#ifdef}.
4257 @item @code{unlink}
4258 @c @fuindex unlink
4259 @prindex @code{unlink}
4260 The Posix spec says that @code{unlink} causes the given file to be
4261 removed only after there are no more open file handles for it.  Some
4262 non-Posix hosts have trouble with this requirement, though,
4263 and some @acronym{DOS} variants even corrupt the file system.
4265 @item @code{unsetenv}
4266 @c @fuindex unsetenv
4267 @prindex @code{unsetenv}
4268 On MinGW, @code{unsetenv} is not available, but a variable @samp{FOO}
4269 can be removed with a call @code{putenv ("FOO=")}, as described under
4270 @code{putenv} above.
4272 @item @code{va_copy}
4273 @c @fuindex va_copy
4274 @prindex @code{va_copy}
4275 The C99 standard provides @code{va_copy} for copying
4276 @code{va_list} variables.  It may be available in older environments
4277 too, though possibly as @code{__va_copy} (e.g., @command{gcc} in strict
4278 pre-C99 mode).  These can be tested with @code{#ifdef}.  A fallback to
4279 @code{memcpy (&dst, &src, sizeof (va_list))} gives maximum
4280 portability.
4282 @item @code{va_list}
4283 @c @fuindex va_list
4284 @prindex @code{va_list}
4285 @code{va_list} is not necessarily just a pointer.  It can be a
4286 @code{struct} (e.g., @command{gcc} on Alpha), which means @code{NULL} is
4287 not portable.  Or it can be an array (e.g., @command{gcc} in some
4288 PowerPC configurations), which means as a function parameter it can be
4289 effectively call-by-reference and library routines might modify the
4290 value back in the caller (e.g., @code{vsnprintf} in the @acronym{GNU} C Library
4291 2.1).
4293 @item Signed @code{>>}
4294 Normally the C @code{>>} right shift of a signed type replicates the
4295 high bit, giving a so-called ``arithmetic'' shift.  But care should be
4296 taken since Standard C doesn't require that behavior.  On those
4297 few processors without a native arithmetic shift (for instance Cray
4298 vector systems) zero bits may be shifted in, the same as a shift of an
4299 unsigned type.
4301 @item Integer @code{/}
4302 C divides signed integers by truncating their quotient toward zero,
4303 yielding the same result as Fortran.  However, before C99 the standard
4304 allowed C implementations to take the floor or ceiling of the quotient
4305 in some cases.  Hardly any implementations took advantage of this
4306 freedom, though, and it's probably not worth worrying about this issue
4307 nowadays.
4308 @end table
4311 @node Particular Functions
4312 @subsection Particular Function Checks
4313 @cindex Function, checking
4315 These macros check for particular C functions---whether they exist, and
4316 in some cases how they respond when given certain arguments.
4318 @defmac AC_FUNC_ALLOCA
4319 @acindex{FUNC_ALLOCA}
4320 @cvindex C_ALLOCA
4321 @cvindex HAVE_ALLOCA_H
4322 @ovindex ALLOCA
4323 @c @fuindex alloca
4324 @prindex @code{alloca}
4325 @hdrindex{alloca.h}
4326 Check how to get @code{alloca}.  Tries to get a builtin version by
4327 checking for @file{alloca.h} or the predefined C preprocessor macros
4328 @code{__GNUC__} and @code{_AIX}.  If this macro finds @file{alloca.h},
4329 it defines @code{HAVE_ALLOCA_H}.
4331 If those attempts fail, it looks for the function in the standard C
4332 library.  If any of those methods succeed, it defines
4333 @code{HAVE_ALLOCA}.  Otherwise, it sets the output variable
4334 @code{ALLOCA} to @samp{$@{LIBOBJDIR@}alloca.o} and defines
4335 @code{C_ALLOCA} (so programs can periodically call @samp{alloca (0)} to
4336 garbage collect).  This variable is separate from @code{LIBOBJS} so
4337 multiple programs can share the value of @code{ALLOCA} without needing
4338 to create an actual library, in case only some of them use the code in
4339 @code{LIBOBJS}.  The @samp{$@{LIBOBJDIR@}} prefix serves the same
4340 purpose as in @code{LIBOBJS} (@pxref{AC_LIBOBJ vs LIBOBJS}).
4342 This macro does not try to get @code{alloca} from the System V R3
4343 @file{libPW} or the System V R4 @file{libucb} because those libraries
4344 contain some incompatible functions that cause trouble.  Some versions
4345 do not even contain @code{alloca} or contain a buggy version.  If you
4346 still want to use their @code{alloca}, use @code{ar} to extract
4347 @file{alloca.o} from them instead of compiling @file{alloca.c}.
4349 Source files that use @code{alloca} should start with a piece of code
4350 like the following, to declare it properly.
4352 @example
4353 @group
4354 #ifdef HAVE_ALLOCA_H
4355 # include <alloca.h>
4356 #elif defined __GNUC__
4357 # define alloca __builtin_alloca
4358 #elif defined _AIX
4359 # define alloca __alloca
4360 #elif defined _MSC_VER
4361 # include <malloc.h>
4362 # define alloca _alloca
4363 #else
4364 # include <stddef.h>
4365 # ifdef  __cplusplus
4366 extern "C"
4367 # endif
4368 void *alloca (size_t);
4369 #endif
4370 @end group
4371 @end example
4372 @end defmac
4374 @defmac AC_FUNC_CHOWN
4375 @acindex{FUNC_CHOWN}
4376 @c @fuindex chown
4377 @prindex @code{chown}
4378 If the @code{chown} function is available and works (in particular, it
4379 should accept @option{-1} for @code{uid} and @code{gid}), define
4380 @code{HAVE_CHOWN}.
4381 @end defmac
4384 @defmac AC_FUNC_CLOSEDIR_VOID
4385 @acindex{FUNC_CLOSEDIR_VOID}
4386 @cvindex CLOSEDIR_VOID
4387 @c @fuindex closedir
4388 @prindex @code{closedir}
4389 If the @code{closedir} function does not return a meaningful value,
4390 define @code{CLOSEDIR_VOID}.  Otherwise, callers ought to check its
4391 return value for an error indicator.
4393 Currently this test is implemented by running a test program.  When
4394 cross compiling the pessimistic assumption that @code{closedir} does not
4395 return a meaningful value is made.
4397 This macro is obsolescent, as @code{closedir} returns a meaningful value
4398 on current systems.  New programs need not use this macro.
4399 @end defmac
4401 @defmac AC_FUNC_ERROR_AT_LINE
4402 @acindex{FUNC_ERROR_AT_LINE}
4403 @c @fuindex error_at_line
4404 @prindex @code{error_at_line}
4405 If the @code{error_at_line} function is not found, require an
4406 @code{AC_LIBOBJ} replacement of @samp{error}.
4407 @end defmac
4409 @defmac AC_FUNC_FNMATCH
4410 @acindex{FUNC_FNMATCH}
4411 @c @fuindex fnmatch
4412 @prindex @code{fnmatch}
4413 If the @code{fnmatch} function conforms to Posix, define
4414 @code{HAVE_FNMATCH}.  Detect common implementation bugs, for example,
4415 the bugs in Solaris 2.4.
4417 Unlike the other specific
4418 @code{AC_FUNC} macros, @code{AC_FUNC_FNMATCH} does not replace a
4419 broken/missing @code{fnmatch}.  This is for historical reasons.
4420 See @code{AC_REPLACE_FNMATCH} below.
4422 This macro is obsolescent.  New programs should use Gnulib's
4423 @code{fnmatch-posix} module.  @xref{Gnulib}.
4424 @end defmac
4426 @defmac AC_FUNC_FNMATCH_GNU
4427 @acindex{FUNC_FNMATCH_GNU}
4428 @c @fuindex fnmatch
4429 @prindex @code{fnmatch}
4430 Behave like @code{AC_REPLACE_FNMATCH} (@emph{replace}) but also test
4431 whether @code{fnmatch} supports @acronym{GNU} extensions.  Detect common
4432 implementation bugs, for example, the bugs in the @acronym{GNU} C
4433 Library 2.1.
4435 This macro is obsolescent.  New programs should use Gnulib's
4436 @code{fnmatch-gnu} module.  @xref{Gnulib}.
4437 @end defmac
4439 @defmac AC_FUNC_FORK
4440 @acindex{FUNC_FORK}
4441 @cvindex HAVE_VFORK_H
4442 @cvindex HAVE_WORKING_FORK
4443 @cvindex HAVE_WORKING_VFORK
4444 @cvindex vfork
4445 @c @fuindex fork
4446 @prindex @code{fork}
4447 @c @fuindex vfork
4448 @prindex @code{vfork}
4449 @hdrindex{vfork.h}
4450 This macro checks for the @code{fork} and @code{vfork} functions.  If a
4451 working @code{fork} is found, define @code{HAVE_WORKING_FORK}.  This macro
4452 checks whether @code{fork} is just a stub by trying to run it.
4454 If @file{vfork.h} is found, define @code{HAVE_VFORK_H}.  If a working
4455 @code{vfork} is found, define @code{HAVE_WORKING_VFORK}.  Otherwise,
4456 define @code{vfork} to be @code{fork} for backward compatibility with
4457 previous versions of @command{autoconf}.  This macro checks for several known
4458 errors in implementations of @code{vfork} and considers the system to not
4459 have a working @code{vfork} if it detects any of them.  It is not considered
4460 to be an implementation error if a child's invocation of @code{signal}
4461 modifies the parent's signal handler, since child processes rarely change
4462 their signal handlers.
4464 Since this macro defines @code{vfork} only for backward compatibility with
4465 previous versions of @command{autoconf} you're encouraged to define it
4466 yourself in new code:
4467 @example
4468 @group
4469 #ifndef HAVE_WORKING_VFORK
4470 # define vfork fork
4471 #endif
4472 @end group
4473 @end example
4474 @end defmac
4476 @defmac AC_FUNC_FSEEKO
4477 @acindex{FUNC_FSEEKO}
4478 @cvindex _LARGEFILE_SOURCE
4479 @c @fuindex fseeko
4480 @prindex @code{fseeko}
4481 If the @code{fseeko} function is available, define @code{HAVE_FSEEKO}.
4482 Define @code{_LARGEFILE_SOURCE} if necessary to make the prototype
4483 visible on some systems (e.g., glibc 2.2).  Otherwise linkage problems
4484 may occur when compiling with @code{AC_SYS_LARGEFILE} on
4485 largefile-sensitive systems where @code{off_t} does not default to a
4486 64bit entity.
4487 @end defmac
4489 @defmac AC_FUNC_GETGROUPS
4490 @acindex{FUNC_GETGROUPS}
4491 @ovindex GETGROUPS_LIBS
4492 @c @fuindex getgroups
4493 @prindex @code{getgroups}
4494 If the @code{getgroups} function is available and works (unlike on
4495 Ultrix 4.3, where @samp{getgroups (0, 0)} always fails), define
4496 @code{HAVE_GETGROUPS}.  Set @code{GETGROUPS_LIBS} to any libraries
4497 needed to get that function.  This macro runs @code{AC_TYPE_GETGROUPS}.
4498 @end defmac
4500 @defmac AC_FUNC_GETLOADAVG
4501 @acindex{FUNC_GETLOADAVG}
4502 @cvindex SVR4
4503 @cvindex DGUX
4504 @cvindex UMAX
4505 @cvindex UMAX4_3
4506 @cvindex HAVE_NLIST_H
4507 @cvindex NLIST_NAME_UNION
4508 @cvindex GETLODAVG_PRIVILEGED
4509 @cvindex NEED_SETGID
4510 @cvindex C_GETLOADAVG
4511 @ovindex LIBOBJS
4512 @ovindex NEED_SETGID
4513 @ovindex KMEM_GROUP
4514 @ovindex GETLOADAVG_LIBS
4515 @c @fuindex getloadavg
4516 @prindex @code{getloadavg}
4517 Check how to get the system load averages.  To perform its tests
4518 properly, this macro needs the file @file{getloadavg.c}; therefore, be
4519 sure to set the @code{AC_LIBOBJ} replacement directory properly (see
4520 @ref{Generic Functions}, @code{AC_CONFIG_LIBOBJ_DIR}).
4522 If the system has the @code{getloadavg} function, define
4523 @code{HAVE_GETLOADAVG}, and set @code{GETLOADAVG_LIBS} to any libraries
4524 necessary to get that function.  Also add @code{GETLOADAVG_LIBS} to
4525 @code{LIBS}.  Otherwise, require an @code{AC_LIBOBJ} replacement for
4526 @samp{getloadavg} with source code in @file{@var{dir}/getloadavg.c}, and
4527 possibly define several other C preprocessor macros and output
4528 variables:
4530 @enumerate
4531 @item
4532 Define @code{C_GETLOADAVG}.
4534 @item
4535 Define @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if on
4536 those systems.
4538 @item
4539 @hdrindex{nlist.h}
4540 If @file{nlist.h} is found, define @code{HAVE_NLIST_H}.
4542 @item
4543 If @samp{struct nlist} has an @samp{n_un.n_name} member, define
4544 @code{HAVE_STRUCT_NLIST_N_UN_N_NAME}.  The obsolete symbol
4545 @code{NLIST_NAME_UNION} is still defined, but do not depend upon it.
4547 @item
4548 Programs may need to be installed set-group-ID (or set-user-ID) for
4549 @code{getloadavg} to work.  In this case, define
4550 @code{GETLOADAVG_PRIVILEGED}, set the output variable @code{NEED_SETGID}
4551 to @samp{true} (and otherwise to @samp{false}), and set
4552 @code{KMEM_GROUP} to the name of the group that should own the installed
4553 program.
4554 @end enumerate
4556 The @code{AC_FUNC_GETLOADVG} macro is obsolescent.  New programs should
4557 use Gnulib's @code{getloadavg} module.  @xref{Gnulib}.
4558 @end defmac
4560 @defmac AC_FUNC_GETMNTENT
4561 @acindex{FUNC_GETMNTENT}
4562 @cvindex HAVE_GETMNTENT
4563 @c @fuindex getmntent
4564 @prindex @code{getmntent}
4565 Check for @code{getmntent} in the standard C library, and then in the
4566 @file{sun}, @file{seq}, and @file{gen} libraries, for @sc{unicos},
4567 @sc{irix} 4, @sc{ptx}, and UnixWare, respectively.  Then, if
4568 @code{getmntent} is available, define @code{HAVE_GETMNTENT}.
4569 @end defmac
4571 @defmac AC_FUNC_GETPGRP
4572 @acindex{FUNC_GETPGRP}
4573 @cvindex GETPGRP_VOID
4574 @c @fuindex getpgid
4575 @c @fuindex getpgrp
4576 @prindex @code{getpgid}
4577 @prindex @code{getpgrp}
4578 Define @code{GETPGRP_VOID} if it is an error to pass 0 to
4579 @code{getpgrp}; this is the Posix behavior.  On older @acronym{BSD}
4580 systems, you must pass 0 to @code{getpgrp}, as it takes an argument and
4581 behaves like Posix's @code{getpgid}.
4583 @example
4584 #ifdef GETPGRP_VOID
4585   pid = getpgrp ();
4586 #else
4587   pid = getpgrp (0);
4588 #endif
4589 @end example
4591 This macro does not check whether
4592 @code{getpgrp} exists at all; if you need to work in that situation,
4593 first call @code{AC_CHECK_FUNC} for @code{getpgrp}.
4595 This macro is obsolescent, as current systems have a @code{getpgrp}
4596 whose signature conforms to Posix.  New programs need not use this macro.
4597 @end defmac
4599 @defmac AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK
4600 @acindex{FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK}
4601 @cvindex LSTAT_FOLLOWS_SLASHED_SYMLINK
4602 @c @fuindex lstat
4603 @prindex @code{lstat}
4604 If @file{link} is a symbolic link, then @code{lstat} should treat
4605 @file{link/} the same as @file{link/.}.  However, many older
4606 @code{lstat} implementations incorrectly ignore trailing slashes.
4608 It is safe to assume that if @code{lstat} incorrectly ignores
4609 trailing slashes, then other symbolic-link-aware functions like
4610 @code{unlink} also incorrectly ignore trailing slashes.
4612 If @code{lstat} behaves properly, define
4613 @code{LSTAT_FOLLOWS_SLASHED_SYMLINK}, otherwise require an
4614 @code{AC_LIBOBJ} replacement of @code{lstat}.
4615 @end defmac
4617 @defmac AC_FUNC_MALLOC
4618 @acindex{FUNC_MALLOC}
4619 @cvindex HAVE_MALLOC
4620 @cvindex malloc
4621 @c @fuindex malloc
4622 @prindex @code{malloc}
4623 If the @code{malloc} function is compatible with the @acronym{GNU} C
4624 library @code{malloc} (i.e., @samp{malloc (0)} returns a valid
4625 pointer), define @code{HAVE_MALLOC} to 1.  Otherwise define
4626 @code{HAVE_MALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
4627 @samp{malloc}, and define @code{malloc} to @code{rpl_malloc} so that the
4628 native @code{malloc} is not used in the main project.
4630 Typically, the replacement file @file{malloc.c} should look like (note
4631 the @samp{#undef malloc}):
4633 @verbatim
4634 #ifdef HAVE_CONFIG_H
4635 # include <config.h>
4636 #endif
4637 #undef malloc
4639 #include <sys/types.h>
4641 void *malloc ();
4643 /* Allocate an N-byte block of memory from the heap.
4644    If N is zero, allocate a 1-byte block.  */
4646 void *
4647 rpl_malloc (size_t n)
4649   if (n == 0)
4650     n = 1;
4651   return malloc (n);
4653 @end verbatim
4654 @end defmac
4656 @defmac AC_FUNC_MEMCMP
4657 @acindex{FUNC_MEMCMP}
4658 @ovindex LIBOBJS
4659 @c @fuindex memcmp
4660 @prindex @code{memcmp}
4661 If the @code{memcmp} function is not available, or does not work on
4662 8-bit data (like the one on SunOS 4.1.3), or fails when comparing 16
4663 bytes or more and with at least one buffer not starting on a 4-byte
4664 boundary (such as the one on NeXT x86 OpenStep), require an
4665 @code{AC_LIBOBJ} replacement for @samp{memcmp}.
4667 This macro is obsolescent, as current systems have a working
4668 @code{memcmp}.  New programs need not use this macro.
4669 @end defmac
4671 @defmac AC_FUNC_MBRTOWC
4672 @acindex{FUNC_MBRTOWC}
4673 @cvindex HAVE_MBRTOWC
4674 @c @fuindex mbrtowc
4675 @prindex @code{mbrtowc}
4676 Define @code{HAVE_MBRTOWC} to 1 if the function @code{mbrtowc} and the
4677 type @code{mbstate_t} are properly declared.
4678 @end defmac
4680 @defmac AC_FUNC_MKTIME
4681 @acindex{FUNC_MKTIME}
4682 @ovindex LIBOBJS
4683 @c @fuindex mktime
4684 @prindex @code{mktime}
4685 If the @code{mktime} function is not available, or does not work
4686 correctly, require an @code{AC_LIBOBJ} replacement for @samp{mktime}.
4687 For the purposes of this test, @code{mktime} should conform to the
4688 Posix standard and should be the inverse of
4689 @code{localtime}.
4690 @end defmac
4692 @defmac AC_FUNC_MMAP
4693 @acindex{FUNC_MMAP}
4694 @cvindex HAVE_MMAP
4695 @c @fuindex mmap
4696 @prindex @code{mmap}
4697 If the @code{mmap} function exists and works correctly, define
4698 @code{HAVE_MMAP}.  This checks only private fixed mapping of already-mapped
4699 memory.
4700 @end defmac
4702 @defmac AC_FUNC_OBSTACK
4703 @acindex{FUNC_OBSTACK}
4704 @cvindex HAVE_OBSTACK
4705 @cindex obstack
4706 If the obstacks are found, define @code{HAVE_OBSTACK}, else require an
4707 @code{AC_LIBOBJ} replacement for @samp{obstack}.
4708 @end defmac
4710 @defmac AC_FUNC_REALLOC
4711 @acindex{FUNC_REALLOC}
4712 @cvindex HAVE_REALLOC
4713 @cvindex realloc
4714 @c @fuindex realloc
4715 @prindex @code{realloc}
4716 If the @code{realloc} function is compatible with the @acronym{GNU} C
4717 library @code{realloc} (i.e., @samp{realloc (NULL, 0)} returns a
4718 valid pointer), define @code{HAVE_REALLOC} to 1.  Otherwise define
4719 @code{HAVE_REALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
4720 @samp{realloc}, and define @code{realloc} to @code{rpl_realloc} so that
4721 the native @code{realloc} is not used in the main project.  See
4722 @code{AC_FUNC_MALLOC} for details.
4723 @end defmac
4725 @defmac AC_FUNC_SELECT_ARGTYPES
4726 @acindex{FUNC_SELECT_ARGTYPES}
4727 @cvindex SELECT_TYPE_ARG1
4728 @cvindex SELECT_TYPE_ARG234
4729 @cvindex SELECT_TYPE_ARG5
4730 @c @fuindex select
4731 @prindex @code{select}
4732 Determines the correct type to be passed for each of the
4733 @code{select} function's arguments, and defines those types
4734 in @code{SELECT_TYPE_ARG1}, @code{SELECT_TYPE_ARG234}, and
4735 @code{SELECT_TYPE_ARG5} respectively.  @code{SELECT_TYPE_ARG1} defaults
4736 to @samp{int}, @code{SELECT_TYPE_ARG234} defaults to @samp{int *},
4737 and @code{SELECT_TYPE_ARG5} defaults to @samp{struct timeval *}.
4739 This macro is obsolescent, as current systems have a @code{select} whose
4740 signature conforms to Posix.  New programs need not use this macro.
4741 @end defmac
4743 @defmac AC_FUNC_SETPGRP
4744 @acindex{FUNC_SETPGRP}
4745 @cvindex SETPGRP_VOID
4746 @c @fuindex setpgrp
4747 @prindex @code{setpgrp}
4748 If @code{setpgrp} takes no argument (the Posix version), define
4749 @code{SETPGRP_VOID}.  Otherwise, it is the @acronym{BSD} version, which takes
4750 two process IDs as arguments.  This macro does not check whether
4751 @code{setpgrp} exists at all; if you need to work in that situation,
4752 first call @code{AC_CHECK_FUNC} for @code{setpgrp}.
4754 This macro is obsolescent, as current systems have a @code{setpgrp}
4755 whose signature conforms to Posix.  New programs need not use this macro.
4756 @end defmac
4758 @defmac AC_FUNC_STAT
4759 @defmacx AC_FUNC_LSTAT
4760 @acindex{FUNC_STAT}
4761 @acindex{FUNC_LSTAT}
4762 @cvindex HAVE_STAT_EMPTY_STRING_BUG
4763 @cvindex HAVE_LSTAT_EMPTY_STRING_BUG
4764 @c @fuindex stat
4765 @prindex @code{stat}
4766 @c @fuindex lstat
4767 @prindex @code{lstat}
4768 Determine whether @code{stat} or @code{lstat} have the bug that it
4769 succeeds when given the zero-length file name as argument.  The @code{stat}
4770 and @code{lstat} from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do
4771 this.
4773 If it does, then define @code{HAVE_STAT_EMPTY_STRING_BUG} (or
4774 @code{HAVE_LSTAT_EMPTY_STRING_BUG}) and ask for an @code{AC_LIBOBJ}
4775 replacement of it.
4777 These macros are obsolescent, as no current systems have the bug.
4778 New programs need not use these macros.
4779 @end defmac
4781 @defmac AC_FUNC_SETVBUF_REVERSED
4782 @acindex{FUNC_SETVBUF_REVERSED}
4783 @cvindex SETVBUF_REVERSED
4784 @c @fuindex setvbuf
4785 @prindex @code{setvbuf}
4786 If @code{setvbuf} takes the buffering type as its second argument and
4787 the buffer pointer as the third, instead of the other way around, define
4788 @code{SETVBUF_REVERSED}.
4790 This macro is obsolescent, as no current systems have the bug.
4791 New programs need not use this macro.
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 or a variable) 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 it is valid to use @var{symbol} as an
5655 r-value, not if it is really declared, because it is much safer to avoid
5656 introducing extra declarations when they are not needed.
5657 @end defmac
5659 @defmac AC_CHECK_DECLS (@var{symbols}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5660 @acindex{CHECK_DECLS}
5661 @cvindex HAVE_DECL_@var{symbol}
5662 For each of the @var{symbols} (@emph{comma}-separated list), define
5663 @code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
5664 @var{symbol} is declared, otherwise to @samp{0}.  If
5665 @var{action-if-not-found} is given, it is additional shell code to
5666 execute when one of the function declarations is needed, otherwise
5667 @var{action-if-found} is executed.
5669 This macro uses an M4 list as first argument:
5670 @example
5671 AC_CHECK_DECLS([strdup])
5672 AC_CHECK_DECLS([strlen])
5673 AC_CHECK_DECLS([malloc, realloc, calloc, free])
5674 @end example
5676 Unlike the other @samp{AC_CHECK_*S} macros, when a @var{symbol} is not
5677 declared, @code{HAVE_DECL_@var{symbol}} is defined to @samp{0} instead
5678 of leaving @code{HAVE_DECL_@var{symbol}} undeclared.  When you are
5679 @emph{sure} that the check was performed, use
5680 @code{HAVE_DECL_@var{symbol}} in @code{#if}:
5682 @example
5683 #if !HAVE_DECL_SYMBOL
5684 extern char *symbol;
5685 #endif
5686 @end example
5688 @noindent
5689 If the test may have not been performed, however, because it is safer
5690 @emph{not} to declare a symbol than to use a declaration that conflicts
5691 with the system's one, you should use:
5693 @example
5694 #if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC
5695 void *malloc (size_t *s);
5696 #endif
5697 @end example
5699 @noindent
5700 You fall into the second category only in extreme situations: either
5701 your files may be used without being configured, or they are used during
5702 the configuration.  In most cases the traditional approach is enough.
5703 @end defmac
5705 @defmac AC_CHECK_DECLS_ONCE (@var{symbols})
5706 @acindex{CHECK_DECLS_ONCE}
5707 @cvindex HAVE_DECL_@var{symbol}
5708 For each of the @var{symbols} (@emph{comma}-separated list), define
5709 @code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
5710 @var{symbol} is declared in the default include files, otherwise to
5711 @samp{0}.  This is a once-only variant of @code{AC_CHECK_DECLS}.  It
5712 generates the checking code at most once, so that @command{configure} is
5713 smaller and faster; but the checks cannot be conditionalized and are
5714 always done once, early during the @command{configure} run.
5715 @end defmac
5718 @node Structures
5719 @section Structures
5720 @cindex Structure, checking
5722 The following macros check for the presence of certain members in C
5723 structures.  If there is no macro specifically defined to check for a
5724 member you need, then you can use the general structure-member macros
5725 (@pxref{Generic Structures}) or, for more complex tests, you may use
5726 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
5728 @menu
5729 * Particular Structures::       Macros to check for certain structure members
5730 * Generic Structures::          How to find other structure members
5731 @end menu
5733 @node Particular Structures
5734 @subsection Particular Structure Checks
5736 The following macros check for certain structures or structure members.
5738 @defmac AC_STRUCT_DIRENT_D_INO
5739 @acindex{STRUCT_DIRENT_D_INO}
5740 @cvindex HAVE_STRUCT_DIRENT_D_INO
5741 Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular
5742 Headers}).  Then, if @code{struct dirent} contains a @code{d_ino}
5743 member, define @code{HAVE_STRUCT_DIRENT_D_INO}.
5745 @code{HAVE_STRUCT_DIRENT_D_INO} indicates only the presence of
5746 @code{d_ino}, not whether its contents are always reliable.
5747 Traditionally, a zero @code{d_ino} indicated a deleted directory entry,
5748 though current systems hide this detail from the user and never return
5749 zero @code{d_ino} values.
5750 Many current systems report an incorrect @code{d_ino} for a directory
5751 entry that is a mount point.
5752 @end defmac
5754 @defmac AC_STRUCT_DIRENT_D_TYPE
5755 @acindex{STRUCT_DIRENT_D_TYPE}
5756 @cvindex HAVE_STRUCT_DIRENT_D_TYPE
5757 Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular
5758 Headers}).  Then, if @code{struct dirent} contains a @code{d_type}
5759 member, define @code{HAVE_STRUCT_DIRENT_D_TYPE}.
5760 @end defmac
5762 @defmac AC_STRUCT_ST_BLKSIZE
5763 @acindex{STRUCT_ST_BLKSIZE}
5764 @cvindex HAVE_STRUCT_STAT_ST_BLKSIZE
5765 @cvindex HAVE_ST_BLKSIZE
5766 If @code{struct stat} contains an @code{st_blksize} member, define
5767 @code{HAVE_STRUCT_STAT_ST_BLKSIZE}.  The former name,
5768 @code{HAVE_ST_BLKSIZE} is to be avoided, as its support will cease in
5769 the future.  This macro is obsoleted, and should be replaced by
5771 @example
5772 AC_CHECK_MEMBERS([struct stat.st_blksize])
5773 @end example
5774 @end defmac
5776 @defmac AC_STRUCT_ST_BLOCKS
5777 @acindex{STRUCT_ST_BLOCKS}
5778 @cvindex HAVE_STRUCT_STAT_ST_BLOCKS
5779 @cvindex HAVE_ST_BLOCKS
5780 @ovindex LIBOBJS
5781 If @code{struct stat} contains an @code{st_blocks} member, define
5782 @code{HAVE_STRUCT_STAT_ST_BLOCKS}.  Otherwise, require an
5783 @code{AC_LIBOBJ} replacement of @samp{fileblocks}.  The former name,
5784 @code{HAVE_ST_BLOCKS} is to be avoided, as its support will cease in the
5785 future.
5786 @end defmac
5788 @defmac AC_STRUCT_ST_RDEV
5789 @acindex{STRUCT_ST_RDEV}
5790 @cvindex HAVE_ST_RDEV
5791 @cvindex HAVE_STRUCT_STAT_ST_RDEV
5792 If @code{struct stat} contains an @code{st_rdev} member, define
5793 @code{HAVE_STRUCT_STAT_ST_RDEV}.  The former name for this macro,
5794 @code{HAVE_ST_RDEV}, is to be avoided as it will cease to be supported
5795 in the future.  Actually, even the new macro is obsolete and should be
5796 replaced by:
5797 @example
5798 AC_CHECK_MEMBERS([struct stat.st_rdev])
5799 @end example
5800 @end defmac
5802 @defmac AC_STRUCT_TM
5803 @acindex{STRUCT_TM}
5804 @cvindex TM_IN_SYS_TIME
5805 @hdrindex{time.h}
5806 @hdrindex{sys/time.h}
5807 If @file{time.h} does not define @code{struct tm}, define
5808 @code{TM_IN_SYS_TIME}, which means that including @file{sys/time.h}
5809 had better define @code{struct tm}.
5811 This macro is obsolescent, as @file{time.h} defines @code{struct tm} in
5812 current systems.  New programs need not use this macro.
5813 @end defmac
5815 @defmac AC_STRUCT_TIMEZONE
5816 @acindex{STRUCT_TIMEZONE}
5817 @cvindex HAVE_TM_ZONE
5818 @cvindex HAVE_TZNAME
5819 Figure out how to get the current timezone.  If @code{struct tm} has a
5820 @code{tm_zone} member, define @code{HAVE_STRUCT_TM_TM_ZONE} (and the
5821 obsoleted @code{HAVE_TM_ZONE}).  Otherwise, if the external array
5822 @code{tzname} is found, define @code{HAVE_TZNAME}; if it is declared,
5823 define @code{HAVE_DECL_TZNAME}.
5824 @end defmac
5826 @node Generic Structures
5827 @subsection Generic Structure Checks
5829 These macros are used to find structure members not covered by the
5830 ``particular'' test macros.
5832 @defmac AC_CHECK_MEMBER (@var{aggregate}.@var{member}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5833 @acindex{CHECK_MEMBER}
5834 Check whether @var{member} is a member of the aggregate @var{aggregate}.
5835 If no @var{includes} are specified, the default includes are used
5836 (@pxref{Default Includes}).
5838 @example
5839 AC_CHECK_MEMBER([struct passwd.pw_gecos], [],
5840                 [AC_MSG_ERROR([We need `passwd.pw_gecos'!])],
5841                 [#include <pwd.h>])
5842 @end example
5844 You can use this macro for submembers:
5846 @example
5847 AC_CHECK_MEMBER(struct top.middle.bot)
5848 @end example
5849 @end defmac
5851 @defmac AC_CHECK_MEMBERS (@var{members}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5852 @acindex{CHECK_MEMBERS}
5853 Check for the existence of each @samp{@var{aggregate}.@var{member}} of
5854 @var{members} using the previous macro.  When @var{member} belongs to
5855 @var{aggregate}, define @code{HAVE_@var{aggregate}_@var{member}} (in all
5856 capitals, with spaces and dots replaced by underscores).  If
5857 @var{action-if-found} is given, it is executed for each of the found
5858 members.  If @var{action-if-not-found} is given, it is executed for each
5859 of the members that could not be found.
5861 This macro uses M4 lists:
5862 @example
5863 AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize])
5864 @end example
5865 @end defmac
5868 @node Types
5869 @section Types
5870 @cindex Types
5871 @cindex C types
5873 The following macros check for C types, either builtin or typedefs.  If
5874 there is no macro specifically defined to check for a type you need, and
5875 you don't need to check for any special properties of it, then you can
5876 use a general type-check macro.
5878 @menu
5879 * Particular Types::            Special handling to find certain types
5880 * Generic Types::               How to find other types
5881 @end menu
5883 @node Particular Types
5884 @subsection Particular Type Checks
5886 @hdrindex{sys/types.h}
5887 @hdrindex{stdlib.h}
5888 @hdrindex{stdint.h}
5889 @hdrindex{inttypes.h}
5890 These macros check for particular C types in @file{sys/types.h},
5891 @file{stdlib.h}, @file{stdint.h}, @file{inttypes.h} and others, if they
5892 exist.
5894 The Gnulib @code{stdint} module is an alternate way to define many of
5895 these symbols; it is useful if you prefer your code to assume a
5896 C99-or-better environment.  @xref{Gnulib}.
5898 @defmac AC_TYPE_GETGROUPS
5899 @acindex{TYPE_GETGROUPS}
5900 @cvindex GETGROUPS_T
5901 Define @code{GETGROUPS_T} to be whichever of @code{gid_t} or @code{int}
5902 is the base type of the array argument to @code{getgroups}.
5903 @end defmac
5905 @defmac AC_TYPE_INT8_T
5906 @acindex{TYPE_INT8_T}
5907 @cvindex HAVE_INT8_T
5908 @cvindex int8_t
5909 If @file{stdint.h} or @file{inttypes.h} defines the type @code{int8_t},
5910 define @code{HAVE_INT8_T}.  Otherwise, define @code{int8_t} to a signed
5911 integer type that is exactly 8 bits wide and that uses two's complement
5912 representation, if such a type exists.
5913 @end defmac
5915 @defmac AC_TYPE_INT16_T
5916 @acindex{TYPE_INT16_T}
5917 @cvindex HAVE_INT16_T
5918 @cvindex int16_t
5919 This is like @code{AC_TYPE_INT8_T}, except for 16-bit integers.
5920 @end defmac
5922 @defmac AC_TYPE_INT32_T
5923 @acindex{TYPE_INT32_T}
5924 @cvindex HAVE_INT32_T
5925 @cvindex int32_t
5926 This is like @code{AC_TYPE_INT8_T}, except for 32-bit integers.
5927 @end defmac
5929 @defmac AC_TYPE_INT64_T
5930 @acindex{TYPE_INT64_T}
5931 @cvindex HAVE_INT64_T
5932 @cvindex int64_t
5933 This is like @code{AC_TYPE_INT8_T}, except for 64-bit integers.
5934 @end defmac
5936 @defmac AC_TYPE_INTMAX_T
5937 @acindex{TYPE_INTMAX_T}
5938 @cvindex HAVE_INTMAX_T
5939 @cvindex intmax_t
5940 If @file{stdint.h} or @file{inttypes.h} defines the type @code{intmax_t},
5941 define @code{HAVE_INTMAX_T}.  Otherwise, define @code{intmax_t} to the
5942 widest signed integer type.
5943 @end defmac
5945 @defmac AC_TYPE_INTPTR_T
5946 @acindex{TYPE_INTPTR_T}
5947 @cvindex HAVE_INTPTR_T
5948 @cvindex intptr_t
5949 If @file{stdint.h} or @file{inttypes.h} defines the type @code{intptr_t},
5950 define @code{HAVE_INTPTR_T}.  Otherwise, define @code{intptr_t} to a
5951 signed integer type wide enough to hold a pointer, if such a type
5952 exists.
5953 @end defmac
5955 @defmac AC_TYPE_LONG_DOUBLE
5956 @acindex{TYPE_LONG_DOUBLE}
5957 @cvindex HAVE_LONG_DOUBLE
5958 If the C compiler supports a working @code{long double} type, define
5959 @code{HAVE_LONG_DOUBLE}.  The @code{long double} type might have the
5960 same range and precision as @code{double}.
5961 @end defmac
5963 @defmac AC_TYPE_LONG_DOUBLE_WIDER
5964 @acindex{TYPE_LONG_DOUBLE_WIDER}
5965 @cvindex HAVE_LONG_DOUBLE_WIDER
5966 If the C compiler supports a working @code{long double} type with more
5967 range or precision than the @code{double} type, define
5968 @code{HAVE_LONG_DOUBLE_WIDER}.
5969 @end defmac
5971 @defmac AC_TYPE_LONG_LONG_INT
5972 @acindex{TYPE_LONG_LONG_INT}
5973 @cvindex HAVE_LONG_LONG_INT
5974 If the C compiler supports a working @code{long long int} type, define
5975 @code{HAVE_LONG_LONG_INT}.
5976 @end defmac
5978 @defmac AC_TYPE_MBSTATE_T
5979 @acindex{TYPE_MBSTATE_T}
5980 @cvindex mbstate_t
5981 @hdrindex{wchar.h}
5982 Define @code{HAVE_MBSTATE_T} if @code{<wchar.h>} declares the
5983 @code{mbstate_t} type.  Also, define @code{mbstate_t} to be a type if
5984 @code{<wchar.h>} does not declare it.
5985 @end defmac
5987 @defmac AC_TYPE_MODE_T
5988 @acindex{TYPE_MODE_T}
5989 @cvindex mode_t
5990 Define @code{mode_t} to a suitable type, if standard headers do not
5991 define it.
5992 @end defmac
5994 @defmac AC_TYPE_OFF_T
5995 @acindex{TYPE_OFF_T}
5996 @cvindex off_t
5997 Define @code{off_t} to a suitable type, if standard headers do not
5998 define it.
5999 @end defmac
6001 @defmac AC_TYPE_PID_T
6002 @acindex{TYPE_PID_T}
6003 @cvindex pid_t
6004 Define @code{pid_t} to a suitable type, if standard headers do not
6005 define it.
6006 @end defmac
6008 @defmac AC_TYPE_SIGNAL
6009 @acindex{TYPE_SIGNAL}
6010 @cvindex RETSIGTYPE
6011 @hdrindex{signal.h}
6012 If @file{signal.h} declares @code{signal} as returning a pointer to a
6013 function returning @code{void}, define @code{RETSIGTYPE} to be
6014 @code{void}; otherwise, define it to be @code{int}.
6016 Define signal handlers as returning type @code{RETSIGTYPE}:
6018 @example
6019 @group
6020 RETSIGTYPE
6021 hup_handler ()
6023 @dots{}
6025 @end group
6026 @end example
6027 @end defmac
6029 @defmac AC_TYPE_SIZE_T
6030 @acindex{TYPE_SIZE_T}
6031 @cvindex size_t
6032 Define @code{size_t} to a suitable type, if standard headers do not
6033 define it.
6034 @end defmac
6036 @defmac AC_TYPE_SSIZE_T
6037 @acindex{TYPE_SSIZE_T}
6038 @cvindex ssize_t
6039 Define @code{ssize_t} to a suitable type, if standard headers do not
6040 define it.
6041 @end defmac
6043 @defmac AC_TYPE_UID_T
6044 @acindex{TYPE_UID_T}
6045 @cvindex uid_t
6046 @cvindex gid_t
6047 Define @code{uid_t} and @code{gid_t} to suitable types, if standard
6048 headers do not define them.
6049 @end defmac
6051 @defmac AC_TYPE_UINT8_T
6052 @acindex{TYPE_UINT8_T}
6053 @cvindex HAVE_UINT8_T
6054 @cvindex uint8_t
6055 If @file{stdint.h} or @file{inttypes.h} defines the type @code{uint8_t},
6056 define @code{HAVE_UINT8_T}.  Otherwise, define @code{uint8_t} to an
6057 unsigned integer type that is exactly 8 bits wide, if such a type
6058 exists.
6059 @end defmac
6061 @defmac AC_TYPE_UINT16_T
6062 @acindex{TYPE_UINT16_T}
6063 @cvindex HAVE_UINT16_T
6064 @cvindex uint16_t
6065 This is like @code{AC_TYPE_UINT8_T}, except for 16-bit unsigned integers.
6066 @end defmac
6068 @defmac AC_TYPE_UINT32_T
6069 @acindex{TYPE_UINT32_T}
6070 @cvindex HAVE_UINT32_T
6071 @cvindex uint32_t
6072 This is like @code{AC_TYPE_UINT8_T}, except for 32-bit unsigned integers.
6073 @end defmac
6075 @defmac AC_TYPE_UINT64_T
6076 @acindex{TYPE_UINT64_T}
6077 @cvindex HAVE_UINT64_T
6078 @cvindex uint64_t
6079 This is like @code{AC_TYPE_UINT8_T}, except for 64-bit unsigned integers.
6080 @end defmac
6082 @defmac AC_TYPE_UINTMAX_T
6083 @acindex{TYPE_UINTMAX_T}
6084 @cvindex HAVE_UINTMAX_T
6085 @cvindex uintmax_t
6086 If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintmax_t},
6087 define @code{HAVE_UINTMAX_T}.  Otherwise, define @code{uintmax_t} to the
6088 widest unsigned integer type.
6089 @end defmac
6091 @defmac AC_TYPE_UINTPTR_T
6092 @acindex{TYPE_UINTPTR_T}
6093 @cvindex HAVE_UINTPTR_T
6094 @cvindex uintptr_t
6095 If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintptr_t},
6096 define @code{HAVE_UINTPTR_T}.  Otherwise, define @code{uintptr_t} to an
6097 unsigned integer type wide enough to hold a pointer, if such a type
6098 exists.
6099 @end defmac
6101 @defmac AC_TYPE_UNSIGNED_LONG_LONG_INT
6102 @acindex{TYPE_UNSIGNED_LONG_LONG_INT}
6103 @cvindex HAVE_UNSIGNED_LONG_LONG_INT
6104 If the C compiler supports a working @code{unsigned long long int} type,
6105 define @code{HAVE_UNSIGNED_LONG_LONG_INT}.
6106 @end defmac
6108 @node Generic Types
6109 @subsection Generic Type Checks
6111 These macros are used to check for types not covered by the ``particular''
6112 test macros.
6114 @defmac AC_CHECK_TYPE (@var{type}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
6115 @acindex{CHECK_TYPE}
6116 Check whether @var{type} is defined.  It may be a compiler builtin type
6117 or defined by the @var{includes} (@pxref{Default Includes}).
6118 @end defmac
6121 @defmac AC_CHECK_TYPES (@var{types}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
6122 @acindex{CHECK_TYPES}
6123 For each @var{type} of the @var{types} that is defined, define
6124 @code{HAVE_@var{type}} (in all capitals).  If no @var{includes} are
6125 specified, the default includes are used (@pxref{Default Includes}).  If
6126 @var{action-if-found} is given, it is additional shell code to execute
6127 when one of the types is found.  If @var{action-if-not-found} is given,
6128 it is executed when one of the types is not found.
6130 This macro uses M4 lists:
6131 @example
6132 AC_CHECK_TYPES([ptrdiff_t])
6133 AC_CHECK_TYPES([unsigned long long int, uintmax_t])
6134 @end example
6136 @end defmac
6138 Autoconf, up to 2.13, used to provide to another version of
6139 @code{AC_CHECK_TYPE}, broken by design.  In order to keep backward
6140 compatibility, a simple heuristics, quite safe but not totally, is
6141 implemented.  In case of doubt, read the documentation of the former
6142 @code{AC_CHECK_TYPE}, see @ref{Obsolete Macros}.
6145 @node Compilers and Preprocessors
6146 @section Compilers and Preprocessors
6147 @cindex Compilers
6148 @cindex Preprocessors
6150 @ovindex EXEEXT
6151 All the tests for compilers (@code{AC_PROG_CC}, @code{AC_PROG_CXX},
6152 @code{AC_PROG_F77}) define the output variable @code{EXEEXT} based on
6153 the output of the compiler, typically to the empty string if
6154 Posix and @samp{.exe} if a @acronym{DOS} variant.
6156 @ovindex OBJEXT
6157 They also define the output variable @code{OBJEXT} based on the
6158 output of the compiler, after @file{.c} files have been excluded, typically
6159 to @samp{o} if Posix, @samp{obj} if a @acronym{DOS} variant.
6161 If the compiler being used does not produce executables, the tests fail.  If
6162 the executables can't be run, and cross-compilation is not enabled, they
6163 fail too.  @xref{Manual Configuration}, for more on support for cross
6164 compiling.
6166 @menu
6167 * Specific Compiler Characteristics::  Some portability issues
6168 * Generic Compiler Characteristics::  Language independent tests and features
6169 * C Compiler::                  Checking its characteristics
6170 * C++ Compiler::                Likewise
6171 * Objective C Compiler::        Likewise
6172 * Erlang Compiler and Interpreter::  Likewise
6173 * Fortran Compiler::            Likewise
6174 @end menu
6176 @node Specific Compiler Characteristics
6177 @subsection Specific Compiler Characteristics
6179 Some compilers exhibit different behaviors.
6181 @table @asis
6182 @item Static/Dynamic Expressions
6183 Autoconf relies on a trick to extract one bit of information from the C
6184 compiler: using negative array sizes.  For instance the following
6185 excerpt of a C source demonstrates how to test whether @samp{int} objects are 4
6186 bytes wide:
6188 @example
6189 static int test_array[sizeof (int) == 4 ? 1 : -1];
6190 @end example
6192 @noindent
6193 To our knowledge, there is a single compiler that does not support this
6194 trick: the @acronym{HP} C compilers (the real ones, not only the ``bundled'') on
6195 @acronym{HP-UX} 11.00.
6196 They incorrectly reject the above program with the diagnostic
6197 ``Variable-length arrays cannot have static storage.''
6198 This bug comes from @acronym{HP} compilers' mishandling of @code{sizeof (int)},
6199 not from the @code{? 1 : -1}, and
6200 Autoconf works around this problem by casting @code{sizeof (int)} to
6201 @code{long int} before comparing it.
6202 @end table
6204 @node Generic Compiler Characteristics
6205 @subsection Generic Compiler Characteristics
6207 @defmac AC_CHECK_SIZEOF (@var{type}, @ovar{unused}, @dvar{includes, default-includes})
6208 @acindex{CHECK_SIZEOF}
6209 Define @code{SIZEOF_@var{type}} (@pxref{Standard Symbols}) to be the
6210 size in bytes of @var{type}.  If @samp{type} is unknown, it gets a size
6211 of 0.  If no @var{includes} are specified, the default includes are used
6212 (@pxref{Default Includes}).
6214 This macro now works even when cross-compiling.  The @var{unused}
6215 argument was used when cross-compiling.
6217 For example, the call
6219 @example
6220 AC_CHECK_SIZEOF([int *])
6221 @end example
6223 @noindent
6224 defines @code{SIZEOF_INT_P} to be 8 on DEC Alpha AXP systems.
6225 @end defmac
6227 @defmac AC_CHECK_ALIGNOF (@var{type}, @dvar{includes, default-includes})
6228 @acindex{CHECK_ALIGNOF}
6229 Define @code{ALIGNOF_@var{type}} (@pxref{Standard Symbols}) to be the
6230 alignment in bytes of @var{type}.  If @samp{type} is unknown, it gets a size
6231 of 0.  If no @var{includes} are specified, the default includes are used
6232 (@pxref{Default Includes}).
6233 @end defmac
6235 @defmac AC_COMPUTE_INT (@var{var}, @var{expression}, @dvar{includes, default-includes}, @ovar{action-if-fails})
6236 @acindex{COMPUTE_INT}
6237 Store into the shell variable @var{var} the value of the integer
6238 @var{expression}.  The
6239 value should fit in an initializer in a C variable of type @code{signed
6240 long}.  To support cross compilation (in which case, the macro only works on
6241 hosts that use twos-complement arithmetic), it should be possible to evaluate
6242 the expression at compile-time.  If no @var{includes} are specified, the default
6243 includes are used (@pxref{Default Includes}).
6245 Execute @var{action-if-fails} if the value cannot be determined correctly.
6246 @end defmac
6248 @defmac AC_LANG_WERROR
6249 @acindex{LANG_WERROR}
6250 Normally Autoconf ignores warnings generated by the compiler, linker, and
6251 preprocessor.  If this macro is used, warnings count as fatal
6252 errors for the current language.  This macro is useful when the
6253 results of configuration are used where warnings are unacceptable; for
6254 instance, if parts of a program are built with the @acronym{GCC}
6255 @option{-Werror}
6256 option.  If the whole program is built using @option{-Werror} it is
6257 often simpler to put @option{-Werror} in the compiler flags (@code{CFLAGS},
6258 etc.).
6259 @end defmac
6261 @node C Compiler
6262 @subsection C Compiler Characteristics
6264 The following macros provide ways to find and exercise a C Compiler.
6265 There are a few constructs that ought to be avoided, but do not deserve
6266 being checked for, since they can easily be worked around.
6268 @table @asis
6269 @item Don't use lines containing solitary backslashes
6270 They tickle a bug in the @acronym{HP-UX} C compiler (checked on
6271 @acronym{HP-UX} 10.20,
6272 11.00, and 11i).  When given the following source:
6274 @example
6275 #ifdef __STDC__
6277 * A comment with backslash-newlines in it.  %@{ %@} *\
6280 char str[] = "\\
6281 " A string with backslash-newlines in it %@{ %@} \\
6283 char apostrophe = '\\
6287 #endif
6288 @end example
6290 @noindent
6291 the compiler incorrectly fails with the diagnostics ``Non-terminating
6292 comment at end of file'' and ``Missing @samp{#endif} at end of file.''
6293 Removing the lines with solitary backslashes solves the problem.
6295 @item Don't compile several files at once if output matters to you
6296 Some compilers, such as @acronym{HP}'s, report names of files being
6297 compiled when given more than one file operand.  For instance:
6299 @example
6300 $ @kbd{cc a.c b.c}
6301 a.c:
6302 b.c:
6303 @end example
6305 @noindent
6306 This can cause problems if you observe the output of the compiler to
6307 detect failures.  Invoking @samp{cc -c a.c && cc -c b.c && cc -o c a.o
6308 b.o} solves the issue.
6310 @item Don't rely on @code{#error} failing
6311 The @sc{irix} C compiler does not fail when #error is preprocessed; it
6312 simply emits a diagnostic and continues, exiting successfully.  So,
6313 instead of an error directive like @code{#error "Unsupported word size"}
6314 it is more portable to use an invalid directive like @code{#Unsupported
6315 word size} in Autoconf tests.  In ordinary source code, @code{#error} is
6316 OK, since installers with inadequate compilers like @sc{irix} can simply
6317 examine these compilers' diagnostic output.
6319 @item Don't rely on correct @code{#line} support
6320 On Solaris, @command{c89} (at least Sun C 5.3 through 5.8)
6321 diagnoses @code{#line} directives whose line
6322 numbers are greater than 32767.  Nothing in Posix
6323 makes this invalid.  That is why Autoconf stopped issuing
6324 @code{#line} directives.
6325 @end table
6327 @defmac AC_PROG_CC (@ovar{compiler-search-list})
6328 @acindex{PROG_CC}
6329 @ovindex CC
6330 @ovindex CFLAGS
6331 Determine a C compiler to use.  If @code{CC} is not already set in the
6332 environment, check for @code{gcc} and @code{cc}, then for other C
6333 compilers.  Set output variable @code{CC} to the name of the compiler
6334 found.
6336 This macro may, however, be invoked with an optional first argument
6337 which, if specified, must be a blank-separated list of C compilers to
6338 search for.  This just gives the user an opportunity to specify an
6339 alternative search list for the C compiler.  For example, if you didn't
6340 like the default order, then you could invoke @code{AC_PROG_CC} like
6341 this:
6343 @example
6344 AC_PROG_CC([gcc cl cc])
6345 @end example
6347 If the C compiler does not handle function prototypes correctly by
6348 default, try to add an option to output variable @code{CC} to make it
6349 so.  This macro tries various options that select standard-conformance
6350 modes on various systems.
6352 After calling this macro you can check whether the C compiler has been
6353 set to accept @acronym{ANSI} C89 (@acronym{ISO} C90); if not, the shell
6354 variable
6355 @code{ac_cv_prog_cc_c89} is set to @samp{no}.  See also
6356 @code{AC_C_PROTOTYPES} below.
6358 If using the @acronym{GNU} C compiler, set shell variable @code{GCC} to
6359 @samp{yes}.  If output variable @code{CFLAGS} was not already set, set
6360 it to @option{-g -O2} for the @acronym{GNU} C compiler (@option{-O2} on systems
6361 where @acronym{GCC} does not accept @option{-g}), or @option{-g} for
6362 other compilers.
6363 @end defmac
6365 @defmac AC_PROG_CC_C_O
6366 @acindex{PROG_CC_C_O}
6367 @cvindex NO_MINUS_C_MINUS_O
6368 If the C compiler does not accept the @option{-c} and @option{-o} options
6369 simultaneously, define @code{NO_MINUS_C_MINUS_O}.  This macro actually
6370 tests both the compiler found by @code{AC_PROG_CC}, and, if different,
6371 the first @code{cc} in the path.  The test fails if one fails.  This
6372 macro was created for @acronym{GNU} Make to choose the default C compilation
6373 rule.
6374 @end defmac
6377 @defmac AC_PROG_CPP
6378 @acindex{PROG_CPP}
6379 @ovindex CPP
6380 Set output variable @code{CPP} to a command that runs the
6381 C preprocessor.  If @samp{$CC -E} doesn't work, @file{/lib/cpp} is used.
6382 It is only portable to run @code{CPP} on files with a @file{.c}
6383 extension.
6385 Some preprocessors don't indicate missing include files by the error
6386 status.  For such preprocessors an internal variable is set that causes
6387 other macros to check the standard error from the preprocessor and
6388 consider the test failed if any warnings have been reported.
6389 For most preprocessors, though, warnings do not cause include-file
6390 tests to fail unless @code{AC_PROG_CPP_WERROR} is also specified.
6391 @end defmac
6393 @defmac AC_PROG_CPP_WERROR
6394 @acindex{PROG_CPP_WERROR}
6395 @ovindex CPP
6396 This acts like @code{AC_PROG_CPP}, except it treats warnings from the
6397 preprocessor as errors even if the preprocessor exit status indicates
6398 success.  This is useful for avoiding headers that generate mandatory
6399 warnings, such as deprecation notices.
6400 @end defmac
6403 The following macros check for C compiler or machine architecture
6404 features.  To check for characteristics not listed here, use
6405 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
6406 @code{AC_RUN_IFELSE} (@pxref{Runtime}).
6408 @defmac AC_PROG_CC_STDC
6409 @acindex{PROG_CC_STDC}
6410 If the C compiler cannot compile @acronym{ISO} Standard C (currently
6411 C99), try to add an option to output variable @code{CC} to make it work.
6412 If the compiler does not support C99, fall back to supporting
6413 @acronym{ANSI} C89 (@acronym{ISO} C90).
6415 After calling this macro you can check whether the C compiler has been
6416 set to accept Standard C; if not, the shell variable
6417 @code{ac_cv_prog_cc_stdc} is set to @samp{no}.
6418 @end defmac
6420 @defmac AC_PROG_CC_C89
6421 @acindex{PROG_CC_C89}
6422 If the C compiler is not in @acronym{ANSI} C89 (@acronym{ISO} C90) mode by
6423 default, try to add an option to output variable @code{CC} to make it
6424 so.  This macro tries various options that select @acronym{ANSI} C89 on
6425 some system or another.  It considers the compiler to be in
6426 @acronym{ANSI} C89 mode if it handles function prototypes correctly.
6428 After calling this macro you can check whether the C compiler has been
6429 set to accept @acronym{ANSI} C89; if not, the shell variable
6430 @code{ac_cv_prog_cc_c89} is set to @samp{no}.
6432 This macro is called automatically by @code{AC_PROG_CC}.
6433 @end defmac
6435 @defmac AC_PROG_CC_C99
6436 @acindex{PROG_CC_C99}
6437 If the C compiler is not in C99 mode by default, try to add an
6438 option to output variable @code{CC} to make it so.  This macro tries
6439 various options that select C99 on some system or another.  It
6440 considers the compiler to be in C99 mode if it handles @code{_Bool},
6441 @code{//} comments, flexible array members, @code{inline}, @code{long
6442 long int}, mixed code and declarations, named initialization of structs,
6443 @code{restrict}, @code{va_copy}, varargs macros, variable declarations
6444 in @code{for} loops, and variable length arrays.
6446 After calling this macro you can check whether the C compiler has been
6447 set to accept C99; if not, the shell variable
6448 @code{ac_cv_prog_cc_c99} is set to @samp{no}.
6449 @end defmac
6451 @defmac AC_C_BACKSLASH_A
6452 @acindex{HAVE_C_BACKSLASH_A}
6453 Define @samp{HAVE_C_BACKSLASH_A} to 1 if the C compiler understands
6454 @samp{\a}.
6456 This macro is obsolescent, as current C compilers understand @samp{\a}.
6457 New programs need not use this macro.
6458 @end defmac
6460 @defmac AC_C_BIGENDIAN (@ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-unknown})
6461 @acindex{C_BIGENDIAN}
6462 @cvindex WORDS_BIGENDIAN
6463 @cindex Endianness
6464 If words are stored with the most significant byte first (like Motorola
6465 and SPARC CPUs), execute @var{action-if-true}.  If words are stored with
6466 the least significant byte first (like Intel and VAX CPUs), execute
6467 @var{action-if-false}.
6469 This macro runs a test-case if endianness cannot be determined from the
6470 system header files.  When cross-compiling, the test-case is not run but
6471 grep'ed for some magic values.  @var{action-if-unknown} is executed if
6472 the latter case fails to determine the byte sex of the host system.
6474 The default for @var{action-if-true} is to define
6475 @samp{WORDS_BIGENDIAN}.  The default for @var{action-if-false} is to do
6476 nothing.  And finally, the default for @var{action-if-unknown} is to
6477 abort configure and tell the installer which variable he should preset
6478 to bypass this test.
6479 @end defmac
6481 @defmac AC_C_CONST
6482 @acindex{C_CONST}
6483 @cvindex const
6484 If the C compiler does not fully support the @code{const} keyword,
6485 define @code{const} to be empty.  Some C compilers that do
6486 not define @code{__STDC__} do support @code{const}; some compilers that
6487 define @code{__STDC__} do not completely support @code{const}.  Programs
6488 can simply use @code{const} as if every C compiler supported it; for
6489 those that don't, the makefile or configuration header file
6490 defines it as empty.
6492 Occasionally installers use a C++ compiler to compile C code, typically
6493 because they lack a C compiler.  This causes problems with @code{const},
6494 because C and C++ treat @code{const} differently.  For example:
6496 @example
6497 const int foo;
6498 @end example
6500 @noindent
6501 is valid in C but not in C++.  These differences unfortunately cannot be
6502 papered over by defining @code{const} to be empty.
6504 If @command{autoconf} detects this situation, it leaves @code{const} alone,
6505 as this generally yields better results in practice.  However, using a
6506 C++ compiler to compile C code is not recommended or supported, and
6507 installers who run into trouble in this area should get a C compiler
6508 like @acronym{GCC} to compile their C code.
6510 This macro is obsolescent, as current C compilers support @code{const}.
6511 New programs need not use this macro.
6512 @end defmac
6514 @defmac AC_C_RESTRICT
6515 @acindex{C_RESTRICT}
6516 @cvindex restrict
6517 If the C compiler recognizes the @code{restrict} keyword, don't do anything.
6518 If it recognizes only a variant spelling (@code{__restrict},
6519 @code{__restrict__}, or @code{_Restrict}), then define
6520 @code{restrict} to that.
6521 Otherwise, define @code{restrict} to be empty.
6522 Thus, programs may simply use @code{restrict} as if every C compiler
6523 supported it; for those that do not, the makefile
6524 or configuration header defines it away.
6526 Although support in C++ for the @code{restrict} keyword is not
6527 required, several C++ compilers do accept the keyword.
6528 This macro works for them, too.
6529 @end defmac
6531 @defmac AC_C_VOLATILE
6532 @acindex{C_VOLATILE}
6533 @cvindex volatile
6534 If the C compiler does not understand the keyword @code{volatile},
6535 define @code{volatile} to be empty.  Programs can simply use
6536 @code{volatile} as if every C compiler supported it; for those that do
6537 not, the makefile or configuration header defines it as
6538 empty.
6540 If the correctness of your program depends on the semantics of
6541 @code{volatile}, simply defining it to be empty does, in a sense, break
6542 your code.  However, given that the compiler does not support
6543 @code{volatile}, you are at its mercy anyway.  At least your
6544 program compiles, when it wouldn't before.
6545 @xref{Volatile Objects}, for more about @code{volatile}.
6547 In general, the @code{volatile} keyword is a standard C feature, so
6548 you might expect that @code{volatile} is available only when
6549 @code{__STDC__} is defined.  However, Ultrix 4.3's native compiler does
6550 support volatile, but does not define @code{__STDC__}.
6552 This macro is obsolescent, as current C compilers support @code{volatile}.
6553 New programs need not use this macro.
6554 @end defmac
6556 @defmac AC_C_INLINE
6557 @acindex{C_INLINE}
6558 @cvindex inline
6559 If the C compiler supports the keyword @code{inline}, do nothing.
6560 Otherwise define @code{inline} to @code{__inline__} or @code{__inline}
6561 if it accepts one of those, otherwise define @code{inline} to be empty.
6562 @end defmac
6564 @defmac AC_C_CHAR_UNSIGNED
6565 @acindex{C_CHAR_UNSIGNED}
6566 @cvindex __CHAR_UNSIGNED__
6567 If the C type @code{char} is unsigned, define @code{__CHAR_UNSIGNED__},
6568 unless the C compiler predefines it.
6569 @end defmac
6571 @defmac AC_C_STRINGIZE
6572 @acindex{C_STRINGIZE}
6573 @cvindex HAVE_STRINGIZE
6574 If the C preprocessor supports the stringizing operator, define
6575 @code{HAVE_STRINGIZE}.  The stringizing operator is @samp{#} and is
6576 found in macros such as this:
6578 @example
6579 #define x(y) #y
6580 @end example
6582 This macro is obsolescent, as current C compilers support the
6583 stringizing operator.  New programs need not use this macro.
6584 @end defmac
6586 @defmac AC_C_TYPEOF
6587 @acindex{C_TYPEOF}
6588 @cvindex HAVE_TYPEOF
6589 @cvindex typeof
6590 If the C compiler supports @acronym{GCC}'s @code{typeof} syntax either
6591 directly or
6592 through a different spelling of the keyword (e.g., @code{__typeof__}),
6593 define @code{HAVE_TYPEOF}.  If the support is available only through a
6594 different spelling, define @code{typeof} to that spelling.
6595 @end defmac
6597 @defmac AC_C_PROTOTYPES
6598 @acindex{C_PROTOTYPES}
6599 @cvindex PROTOTYPES
6600 @cvindex __PROTOTYPES
6601 @cvindex PARAMS
6602 If function prototypes are understood by the compiler (as determined by
6603 @code{AC_PROG_CC}), define @code{PROTOTYPES} and @code{__PROTOTYPES}.
6604 Defining @code{__PROTOTYPES} is for the benefit of
6605 header files that cannot use macros that infringe on user name space.
6607 This macro is obsolescent, as current C compilers support prototypes.
6608 New programs need not use this macro.
6609 @end defmac
6611 @defmac AC_PROG_GCC_TRADITIONAL
6612 @acindex{PROG_GCC_TRADITIONAL}
6613 @ovindex CC
6614 Add @option{-traditional} to output variable @code{CC} if using the
6615 @acronym{GNU} C compiler and @code{ioctl} does not work properly without
6616 @option{-traditional}.  That usually happens when the fixed header files
6617 have not been installed on an old system.
6619 This macro is obsolescent, since current versions of the @acronym{GNU} C
6620 compiler fix the header files automatically when installed.
6621 @end defmac
6624 @node C++ Compiler
6625 @subsection C++ Compiler Characteristics
6628 @defmac AC_PROG_CXX (@ovar{compiler-search-list})
6629 @acindex{PROG_CXX}
6630 @ovindex CXX
6631 @ovindex CXXFLAGS
6632 Determine a C++ compiler to use.  Check whether the environment variable
6633 @code{CXX} or @code{CCC} (in that order) is set; if so, then set output
6634 variable @code{CXX} to its value.
6636 Otherwise, if the macro is invoked without an argument, then search for
6637 a C++ compiler under the likely names (first @code{g++} and @code{c++}
6638 then other names).  If none of those checks succeed, then as a last
6639 resort set @code{CXX} to @code{g++}.
6641 This macro may, however, be invoked with an optional first argument
6642 which, if specified, must be a blank-separated list of C++ compilers to
6643 search for.  This just gives the user an opportunity to specify an
6644 alternative search list for the C++ compiler.  For example, if you
6645 didn't like the default order, then you could invoke @code{AC_PROG_CXX}
6646 like this:
6648 @example
6649 AC_PROG_CXX([gcc cl KCC CC cxx cc++ xlC aCC c++ g++])
6650 @end example
6652 If using the @acronym{GNU} C++ compiler, set shell variable @code{GXX} to
6653 @samp{yes}.  If output variable @code{CXXFLAGS} was not already set, set
6654 it to @option{-g -O2} for the @acronym{GNU} C++ compiler (@option{-O2} on
6655 systems where G++ does not accept @option{-g}), or @option{-g} for other
6656 compilers.
6657 @end defmac
6659 @defmac AC_PROG_CXXCPP
6660 @acindex{PROG_CXXCPP}
6661 @ovindex CXXCPP
6662 Set output variable @code{CXXCPP} to a command that runs the C++
6663 preprocessor.  If @samp{$CXX -E} doesn't work, @file{/lib/cpp} is used.
6664 It is portable to run @code{CXXCPP} only on files with a @file{.c},
6665 @file{.C}, @file{.cc}, or @file{.cpp} extension.
6667 Some preprocessors don't indicate missing include files by the error
6668 status.  For such preprocessors an internal variable is set that causes
6669 other macros to check the standard error from the preprocessor and
6670 consider the test failed if any warnings have been reported.  However,
6671 it is not known whether such broken preprocessors exist for C++.
6672 @end defmac
6674 @defmac AC_PROG_CXX_C_O
6675 @acindex{PROG_CXX_C_O}
6676 @cvindex CXX_NO_MINUS_C_MINUS_O
6677 Test whether the C++ compiler accepts the options @option{-c} and
6678 @option{-o} simultaneously, and define @code{CXX_NO_MINUS_C_MINUS_O},
6679 if it does not.
6680 @end defmac
6683 @node Objective C Compiler
6684 @subsection Objective C Compiler Characteristics
6687 @defmac AC_PROG_OBJC (@ovar{compiler-search-list})
6688 @acindex{PROG_OBJC}
6689 @ovindex OBJC
6690 @ovindex OBJCFLAGS
6691 Determine an Objective C compiler to use.  If @code{OBJC} is not already
6692 set in the environment, check for Objective C compilers.  Set output
6693 variable @code{OBJC} to the name of the compiler found.
6695 This macro may, however, be invoked with an optional first argument
6696 which, if specified, must be a blank-separated list of Objective C compilers to
6697 search for.  This just gives the user an opportunity to specify an
6698 alternative search list for the Objective C compiler.  For example, if you
6699 didn't like the default order, then you could invoke @code{AC_PROG_OBJC}
6700 like this:
6702 @example
6703 AC_PROG_OBJC([gcc objcc objc])
6704 @end example
6706 If using the @acronym{GNU} Objective C compiler, set shell variable
6707 @code{GOBJC} to @samp{yes}.  If output variable @code{OBJCFLAGS} was not
6708 already set, set it to @option{-g -O2} for the @acronym{GNU} Objective C
6709 compiler (@option{-O2} on systems where @command{gcc} does not accept
6710 @option{-g}), or @option{-g} for other compilers.
6711 @end defmac
6713 @defmac AC_PROG_OBJCCPP
6714 @acindex{PROG_OBJCCPP}
6715 @ovindex OBJCCPP
6716 Set output variable @code{OBJCCPP} to a command that runs the Objective C
6717 preprocessor.  If @samp{$OBJC -E} doesn't work, @file{/lib/cpp} is used.
6718 @end defmac
6721 @node Erlang Compiler and Interpreter
6722 @subsection Erlang Compiler and Interpreter Characteristics
6723 @cindex Erlang
6725 Autoconf defines the following macros for determining paths to the essential
6726 Erlang/OTP programs:
6728 @defmac AC_ERLANG_PATH_ERLC (@ovar{value-if-not-found}, @ovar{path})
6729 @acindex{ERLANG_PATH_ERLC}
6730 @ovindex ERLC
6731 @ovindex ERLCFLAGS
6732 Determine an Erlang compiler to use.  If @code{ERLC} is not already set in the
6733 environment, check for @command{erlc}.  Set output variable @code{ERLC} to the
6734 complete path of the compiler command found.  In addition, if @code{ERLCFLAGS}
6735 is not set in the environment, set it to an empty value.
6737 The two optional arguments have the same meaning as the two last arguments of
6738 macro @code{AC_PROG_PATH} for looking for the @command{erlc} program.  For
6739 example, to look for @command{erlc} only in the @file{/usr/lib/erlang/bin}
6740 directory:
6742 @example
6743 AC_ERLANG_PATH_ERLC([not found], [/usr/lib/erlang/bin])
6744 @end example
6745 @end defmac
6747 @defmac AC_ERLANG_NEED_ERLC (@ovar{path})
6748 @acindex{ERLANG_NEED_ERLC}
6749 A simplified variant of the @code{AC_ERLANG_PATH_ERLC} macro, that prints an
6750 error message and exits the @command{configure} script if the @command{erlc}
6751 program is not found.
6752 @end defmac
6754 @defmac AC_ERLANG_PATH_ERL (@ovar{value-if-not-found}, @ovar{path})
6755 @acindex{ERLANG_PATH_ERL}
6756 @ovindex ERL
6757 Determine an Erlang interpreter to use.  If @code{ERL} is not already set in the
6758 environment, check for @command{erl}.  Set output variable @code{ERL} to the
6759 complete path of the interpreter command found.
6761 The two optional arguments have the same meaning as the two last arguments of
6762 macro @code{AC_PROG_PATH} for looking for the @command{erl} program.  For
6763 example, to look for @command{erl} only in the @file{/usr/lib/erlang/bin}
6764 directory:
6766 @example
6767 AC_ERLANG_PATH_ERL([not found], [/usr/lib/erlang/bin])
6768 @end example
6769 @end defmac
6771 @defmac AC_ERLANG_NEED_ERL (@ovar{path})
6772 @acindex{ERLANG_NEED_ERL}
6773 A simplified variant of the @code{AC_ERLANG_PATH_ERL} macro, that prints an
6774 error message and exits the @command{configure} script if the @command{erl}
6775 program is not found.
6776 @end defmac
6779 @node Fortran Compiler
6780 @subsection Fortran Compiler Characteristics
6781 @cindex Fortran
6782 @cindex F77
6784 The Autoconf Fortran support is divided into two categories: legacy
6785 Fortran 77 macros (@code{F77}), and modern Fortran macros (@code{FC}).
6786 The former are intended for traditional Fortran 77 code, and have output
6787 variables like @code{F77}, @code{FFLAGS}, and @code{FLIBS}.  The latter
6788 are for newer programs that can (or must) compile under the newer
6789 Fortran standards, and have output variables like @code{FC},
6790 @code{FCFLAGS}, and @code{FCLIBS}.
6792 Except for two new macros @code{AC_FC_SRCEXT} and
6793 @code{AC_FC_FREEFORM} (see below), the @code{FC} and @code{F77} macros
6794 behave almost identically, and so they are documented together in this
6795 section.
6798 @defmac AC_PROG_F77 (@ovar{compiler-search-list})
6799 @acindex{PROG_F77}
6800 @ovindex F77
6801 @ovindex FFLAGS
6802 Determine a Fortran 77 compiler to use.  If @code{F77} is not already
6803 set in the environment, then check for @code{g77} and @code{f77}, and
6804 then some other names.  Set the output variable @code{F77} to the name
6805 of the compiler found.
6807 This macro may, however, be invoked with an optional first argument
6808 which, if specified, must be a blank-separated list of Fortran 77
6809 compilers to search for.  This just gives the user an opportunity to
6810 specify an alternative search list for the Fortran 77 compiler.  For
6811 example, if you didn't like the default order, then you could invoke
6812 @code{AC_PROG_F77} like this:
6814 @example
6815 AC_PROG_F77([fl32 f77 fort77 xlf g77 f90 xlf90])
6816 @end example
6818 If using @code{g77} (the @acronym{GNU} Fortran 77 compiler), then
6819 set the shell variable @code{G77} to @samp{yes}.
6820 If the output variable @code{FFLAGS} was not already set in the
6821 environment, then set it to @option{-g -02} for @code{g77} (or @option{-O2}
6822 where @code{g77} does not accept @option{-g}).  Otherwise, set
6823 @code{FFLAGS} to @option{-g} for all other Fortran 77 compilers.
6824 @end defmac
6826 @defmac AC_PROG_FC (@ovar{compiler-search-list}, @ovar{dialect})
6827 @acindex{PROG_FC}
6828 @ovindex FC
6829 @ovindex FCFLAGS
6830 Determine a Fortran compiler to use.  If @code{FC} is not already set in
6831 the environment, then @code{dialect} is a hint to indicate what Fortran
6832 dialect to search for; the default is to search for the newest available
6833 dialect.  Set the output variable @code{FC} to the name of the compiler
6834 found.
6836 By default, newer dialects are preferred over older dialects, but if
6837 @code{dialect} is specified then older dialects are preferred starting
6838 with the specified dialect.  @code{dialect} can currently be one of
6839 Fortran 77, Fortran 90, or Fortran 95.  However, this is only a hint of
6840 which compiler @emph{name} to prefer (e.g., @code{f90} or @code{f95}),
6841 and no attempt is made to guarantee that a particular language standard
6842 is actually supported.  Thus, it is preferable that you avoid the
6843 @code{dialect} option, and use AC_PROG_FC only for code compatible with
6844 the latest Fortran standard.
6846 This macro may, alternatively, be invoked with an optional first argument
6847 which, if specified, must be a blank-separated list of Fortran
6848 compilers to search for, just as in @code{AC_PROG_F77}.
6850 If the output variable @code{FCFLAGS} was not already set in the
6851 environment, then set it to @option{-g -02} for @acronym{GNU} @code{g77} (or
6852 @option{-O2} where @code{g77} does not accept @option{-g}).  Otherwise,
6853 set @code{FCFLAGS} to @option{-g} for all other Fortran compilers.
6854 @end defmac
6856 @defmac AC_PROG_F77_C_O
6857 @defmacx AC_PROG_FC_C_O
6858 @acindex{PROG_F77_C_O}
6859 @acindex{PROG_FC_C_O}
6860 @cvindex F77_NO_MINUS_C_MINUS_O
6861 @cvindex FC_NO_MINUS_C_MINUS_O
6862 Test whether the Fortran compiler accepts the options @option{-c} and
6863 @option{-o} simultaneously, and define @code{F77_NO_MINUS_C_MINUS_O} or
6864 @code{FC_NO_MINUS_C_MINUS_O}, respectively, if it does not.
6865 @end defmac
6867 The following macros check for Fortran compiler characteristics.
6868 To check for characteristics not listed here, use
6869 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
6870 @code{AC_RUN_IFELSE} (@pxref{Runtime}), making sure to first set the
6871 current language to Fortran 77 or Fortran via @code{AC_LANG([Fortran 77])}
6872 or @code{AC_LANG(Fortran)} (@pxref{Language Choice}).
6875 @defmac AC_F77_LIBRARY_LDFLAGS
6876 @defmacx AC_FC_LIBRARY_LDFLAGS
6877 @acindex{F77_LIBRARY_LDFLAGS}
6878 @ovindex FLIBS
6879 @acindex{FC_LIBRARY_LDFLAGS}
6880 @ovindex FCLIBS
6881 Determine the linker flags (e.g., @option{-L} and @option{-l}) for the
6882 @dfn{Fortran intrinsic and runtime libraries} that are required to
6883 successfully link a Fortran program or shared library.  The output
6884 variable @code{FLIBS} or @code{FCLIBS} is set to these flags (which
6885 should be included after @code{LIBS} when linking).
6887 This macro is intended to be used in those situations when it is
6888 necessary to mix, e.g., C++ and Fortran source code in a single
6889 program or shared library (@pxref{Mixing Fortran 77 With C and C++, , ,
6890 automake, @acronym{GNU} Automake}).
6892 For example, if object files from a C++ and Fortran compiler must be
6893 linked together, then the C++ compiler/linker must be used for linking
6894 (since special C++-ish things need to happen at link time like calling
6895 global constructors, instantiating templates, enabling exception
6896 support, etc.).
6898 However, the Fortran intrinsic and runtime libraries must be linked in
6899 as well, but the C++ compiler/linker doesn't know by default how to add
6900 these Fortran 77 libraries.  Hence, this macro was created to determine
6901 these Fortran libraries.
6903 The macros @code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or
6904 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} are probably also necessary to
6905 link C/C++ with Fortran; see below.
6906 @end defmac
6908 @defmac AC_F77_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
6909 @defmacx AC_FC_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
6910 @acindex{F77_DUMMY_MAIN}
6911 @cvindex F77_DUMMY_MAIN
6912 With many compilers, the Fortran libraries detected by
6913 @code{AC_F77_LIBRARY_LDFLAGS} or @code{AC_FC_LIBRARY_LDFLAGS} provide
6914 their own @code{main} entry function that initializes things like
6915 Fortran I/O, and which then calls a user-provided entry function named
6916 (say) @code{MAIN__} to run the user's program.  The
6917 @code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or
6918 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros figure out how to deal with
6919 this interaction.
6921 When using Fortran for purely numerical functions (no I/O, etc.)@: often
6922 one prefers to provide one's own @code{main} and skip the Fortran
6923 library initializations.  In this case, however, one may still need to
6924 provide a dummy @code{MAIN__} routine in order to prevent linking errors
6925 on some systems.  @code{AC_F77_DUMMY_MAIN} or @code{AC_FC_DUMMY_MAIN}
6926 detects whether any such routine is @emph{required} for linking, and
6927 what its name is; the shell variable @code{F77_DUMMY_MAIN} or
6928 @code{FC_DUMMY_MAIN} holds this name, @code{unknown} when no solution
6929 was found, and @code{none} when no such dummy main is needed.
6931 By default, @var{action-if-found} defines @code{F77_DUMMY_MAIN} or
6932 @code{FC_DUMMY_MAIN} to the name of this routine (e.g., @code{MAIN__})
6933 @emph{if} it is required.  @var{action-if-not-found} defaults to
6934 exiting with an error.
6936 In order to link with Fortran routines, the user's C/C++ program should
6937 then include the following code to define the dummy main if it is
6938 needed:
6940 @example
6941 #ifdef F77_DUMMY_MAIN
6942 #  ifdef __cplusplus
6943      extern "C"
6944 #  endif
6945    int F77_DUMMY_MAIN() @{ return 1; @}
6946 #endif
6947 @end example
6949 (Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
6951 Note that this macro is called automatically from @code{AC_F77_WRAPPERS}
6952 or @code{AC_FC_WRAPPERS}; there is generally no need to call it
6953 explicitly unless one wants to change the default actions.
6954 @end defmac
6956 @defmac AC_F77_MAIN
6957 @defmacx AC_FC_MAIN
6958 @acindex{F77_MAIN}
6959 @cvindex F77_MAIN
6960 @acindex{FC_MAIN}
6961 @cvindex FC_MAIN
6962 As discussed above, many Fortran libraries allow you to provide an entry
6963 point called (say) @code{MAIN__} instead of the usual @code{main}, which
6964 is then called by a @code{main} function in the Fortran libraries that
6965 initializes things like Fortran I/O@.  The
6966 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros detect whether it is
6967 @emph{possible} to utilize such an alternate main function, and defines
6968 @code{F77_MAIN} and @code{FC_MAIN} to the name of the function.  (If no
6969 alternate main function name is found, @code{F77_MAIN} and @code{FC_MAIN} are
6970 simply defined to @code{main}.)
6972 Thus, when calling Fortran routines from C that perform things like I/O,
6973 one should use this macro and name the "main" function
6974 @code{F77_MAIN} or @code{FC_MAIN} instead of @code{main}.
6975 @end defmac
6977 @defmac AC_F77_WRAPPERS
6978 @defmacx AC_FC_WRAPPERS
6979 @acindex{F77_WRAPPERS}
6980 @cvindex F77_FUNC
6981 @cvindex F77_FUNC_
6982 @acindex{FC_WRAPPERS}
6983 @cvindex FC_FUNC
6984 @cvindex FC_FUNC_
6985 Defines C macros @code{F77_FUNC (name, NAME)}, @code{FC_FUNC (name, NAME)},
6986 @code{F77_FUNC_(name, NAME)}, and @code{FC_FUNC_(name, NAME)} to properly
6987 mangle the names of C/C++ identifiers, and identifiers with underscores,
6988 respectively, so that they match the name-mangling scheme used by the
6989 Fortran compiler.
6991 Fortran is case-insensitive, and in order to achieve this the Fortran
6992 compiler converts all identifiers into a canonical case and format.  To
6993 call a Fortran subroutine from C or to write a C function that is
6994 callable from Fortran, the C program must explicitly use identifiers in
6995 the format expected by the Fortran compiler.  In order to do this, one
6996 simply wraps all C identifiers in one of the macros provided by
6997 @code{AC_F77_WRAPPERS} or @code{AC_FC_WRAPPERS}.  For example, suppose
6998 you have the following Fortran 77 subroutine:
7000 @example
7001       subroutine foobar (x, y)
7002       double precision x, y
7003       y = 3.14159 * x
7004       return
7005       end
7006 @end example
7008 You would then declare its prototype in C or C++ as:
7010 @example
7011 #define FOOBAR_F77 F77_FUNC (foobar, FOOBAR)
7012 #ifdef __cplusplus
7013 extern "C"  /* prevent C++ name mangling */
7014 #endif
7015 void FOOBAR_F77(double *x, double *y);
7016 @end example
7018 Note that we pass both the lowercase and uppercase versions of the
7019 function name to @code{F77_FUNC} so that it can select the right one.
7020 Note also that all parameters to Fortran 77 routines are passed as
7021 pointers (@pxref{Mixing Fortran 77 With C and C++, , , automake, @acronym{GNU}
7022 Automake}).
7024 (Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
7026 Although Autoconf tries to be intelligent about detecting the
7027 name-mangling scheme of the Fortran compiler, there may be Fortran
7028 compilers that it doesn't support yet.  In this case, the above code
7029 generates a compile-time error, but some other behavior
7030 (e.g., disabling Fortran-related features) can be induced by checking
7031 whether @code{F77_FUNC} or @code{FC_FUNC} is defined.
7033 Now, to call that routine from a C program, we would do something like:
7035 @example
7037     double x = 2.7183, y;
7038     FOOBAR_F77 (&x, &y);
7040 @end example
7042 If the Fortran identifier contains an underscore (e.g., @code{foo_bar}),
7043 you should use @code{F77_FUNC_} or @code{FC_FUNC_} instead of
7044 @code{F77_FUNC} or @code{FC_FUNC} (with the same arguments).  This is
7045 because some Fortran compilers mangle names differently if they contain
7046 an underscore.
7047 @end defmac
7049 @defmac AC_F77_FUNC (@var{name}, @ovar{shellvar})
7050 @defmacx AC_FC_FUNC (@var{name}, @ovar{shellvar})
7051 @acindex{F77_FUNC}
7052 @acindex{FC_FUNC}
7053 Given an identifier @var{name}, set the shell variable @var{shellvar} to
7054 hold the mangled version @var{name} according to the rules of the
7055 Fortran linker (see also @code{AC_F77_WRAPPERS} or
7056 @code{AC_FC_WRAPPERS}).  @var{shellvar} is optional; if it is not
7057 supplied, the shell variable is simply @var{name}.  The purpose of
7058 this macro is to give the caller a way to access the name-mangling
7059 information other than through the C preprocessor as above, for example,
7060 to call Fortran routines from some language other than C/C++.
7061 @end defmac
7063 @defmac AC_FC_SRCEXT (@var{ext}, @ovar{action-if-success}, @ovar{action-if-failure})
7064 @acindex{FC_SRCEXT}
7065 By default, the @code{FC} macros perform their tests using a @file{.f}
7066 extension for source-code files.  Some compilers, however, only enable
7067 newer language features for appropriately named files, e.g., Fortran 90
7068 features only for @file{.f90} files.  On the other hand, some other
7069 compilers expect all source files to end in @file{.f} and require
7070 special flags to support other file name extensions.  The
7071 @code{AC_FC_SRCEXT} macro deals with both of these issues.
7073 The @code{AC_FC_SRCEXT} tries to get the @code{FC} compiler to accept files
7074 ending with the extension .@var{ext} (i.e., @var{ext} does @emph{not}
7075 contain the dot).  If any special compiler flags are needed for this, it
7076 stores them in the output variable @code{FCFLAGS_}@var{ext}.  This
7077 extension and these flags are then used for all subsequent @code{FC} tests
7078 (until @code{AC_FC_SRCEXT} is called again).
7080 For example, you would use @code{AC_FC_SRCEXT(f90)} to employ the
7081 @file{.f90} extension in future tests, and it would set a
7082 @code{FCFLAGS_f90} output variable with any extra flags that are needed
7083 to compile such files.
7085 The @code{FCFLAGS_}@var{ext} can @emph{not} be simply absorbed into
7086 @code{FCFLAGS}, for two reasons based on the limitations of some
7087 compilers.  First, only one @code{FCFLAGS_}@var{ext} can be used at a
7088 time, so files with different extensions must be compiled separately.
7089 Second, @code{FCFLAGS_}@var{ext} must appear @emph{immediately} before
7090 the source-code file name when compiling.  So, continuing the example
7091 above, you might compile a @file{foo.f90} file in your makefile with the
7092 command:
7094 @example
7095 foo.o: foo.f90
7096      $(FC) -c $(FCFLAGS) $(FCFLAGS_f90) '$(srcdir)/foo.f90'
7097 @end example
7099 If @code{AC_FC_SRCEXT} succeeds in compiling files with the @var{ext}
7100 extension, it calls @var{action-if-success} (defaults to nothing).  If
7101 it fails, and cannot find a way to make the @code{FC} compiler accept such
7102 files, it calls @var{action-if-failure} (defaults to exiting with an
7103 error message).
7105 @end defmac
7107 @defmac AC_FC_FREEFORM (@ovar{action-if-success}, @ovar{action-if-failure})
7108 @acindex{FC_FREEFORM}
7110 The @code{AC_FC_FREEFORM} tries to ensure that the Fortran compiler
7111 (@code{$FC}) allows free-format source code (as opposed to the older
7112 fixed-format style from Fortran 77).  If necessary, it may add some
7113 additional flags to @code{FCFLAGS}.
7115 This macro is most important if you are using the default @file{.f}
7116 extension, since many compilers interpret this extension as indicating
7117 fixed-format source unless an additional flag is supplied.  If you
7118 specify a different extension with @code{AC_FC_SRCEXT}, such as
7119 @file{.f90} or @file{.f95}, then @code{AC_FC_FREEFORM} ordinarily
7120 succeeds without modifying @code{FCFLAGS}.
7122 If @code{AC_FC_FREEFORM} succeeds in compiling free-form source, it
7123 calls @var{action-if-success} (defaults to nothing).  If it fails, it
7124 calls @var{action-if-failure} (defaults to exiting with an error
7125 message).
7126 @end defmac
7128 @node System Services
7129 @section System Services
7131 The following macros check for operating system services or capabilities.
7133 @defmac AC_PATH_X
7134 @acindex{PATH_X}
7135 @evindex XMKMF
7136 @cindex X Window System
7137 Try to locate the X Window System include files and libraries.  If the
7138 user gave the command line options @option{--x-includes=@var{dir}} and
7139 @option{--x-libraries=@var{dir}}, use those directories.
7141 If either or both were not given, get the missing values by running
7142 @code{xmkmf} (or an executable pointed to by the @code{XMKMF}
7143 environment variable) on a trivial @file{Imakefile} and examining the
7144 makefile that it produces.  Setting @code{XMKMF} to @samp{false}
7145 disables this method.
7147 If this method fails to find the X Window System, @command{configure}
7148 looks for the files in several directories where they often reside.
7149 If either method is successful, set the shell variables
7150 @code{x_includes} and @code{x_libraries} to their locations, unless they
7151 are in directories the compiler searches by default.
7153 If both methods fail, or the user gave the command line option
7154 @option{--without-x}, set the shell variable @code{no_x} to @samp{yes};
7155 otherwise set it to the empty string.
7156 @end defmac
7158 @defmac AC_PATH_XTRA
7159 @acindex{PATH_XTRA}
7160 @ovindex X_CFLAGS
7161 @ovindex X_LIBS
7162 @ovindex X_EXTRA_LIBS
7163 @ovindex X_PRE_LIBS
7164 @cvindex X_DISPLAY_MISSING
7165 An enhanced version of @code{AC_PATH_X}.  It adds the C compiler flags
7166 that X needs to output variable @code{X_CFLAGS}, and the X linker flags
7167 to @code{X_LIBS}.  Define @code{X_DISPLAY_MISSING} if X is not
7168 available.
7170 This macro also checks for special libraries that some systems need in
7171 order to compile X programs.  It adds any that the system needs to
7172 output variable @code{X_EXTRA_LIBS}.  And it checks for special X11R6
7173 libraries that need to be linked with before @option{-lX11}, and adds
7174 any found to the output variable @code{X_PRE_LIBS}.
7176 @c This is an incomplete kludge.  Make a real way to do it.
7177 @c If you need to check for other X functions or libraries yourself, then
7178 @c after calling this macro, add the contents of @code{X_EXTRA_LIBS} to
7179 @c @code{LIBS} temporarily, like this: (FIXME - add example)
7180 @end defmac
7182 @defmac AC_SYS_INTERPRETER
7183 @acindex{SYS_INTERPRETER}
7184 Check whether the system supports starting scripts with a line of the
7185 form @samp{#!/bin/sh} to select the interpreter to use for the script.
7186 After running this macro, shell code in @file{configure.ac} can check
7187 the shell variable @code{interpval}; it is set to @samp{yes}
7188 if the system supports @samp{#!}, @samp{no} if not.
7189 @end defmac
7191 @defmac AC_SYS_LARGEFILE
7192 @acindex{SYS_LARGEFILE}
7193 @cvindex _FILE_OFFSET_BITS
7194 @cvindex _LARGE_FILES
7195 @ovindex CC
7196 @cindex Large file support
7197 @cindex LFS
7198 Arrange for
7199 @uref{http://www.unix-systems.org/@/version2/@/whatsnew/@/lfs20mar.html,
7200 large-file support}.  On some hosts, one must use special compiler
7201 options to build programs that can access large files.  Append any such
7202 options to the output variable @code{CC}.  Define
7203 @code{_FILE_OFFSET_BITS} and @code{_LARGE_FILES} if necessary.
7205 Large-file support can be disabled by configuring with the
7206 @option{--disable-largefile} option.
7208 If you use this macro, check that your program works even when
7209 @code{off_t} is wider than @code{long int}, since this is common when
7210 large-file support is enabled.  For example, it is not correct to print
7211 an arbitrary @code{off_t} value @code{X} with @code{printf ("%ld",
7212 (long int) X)}.
7214 The LFS introduced the @code{fseeko} and @code{ftello} functions to
7215 replace their C counterparts @code{fseek} and @code{ftell} that do not
7216 use @code{off_t}.  Take care to use @code{AC_FUNC_FSEEKO} to make their
7217 prototypes available when using them and large-file support is
7218 enabled.
7219 @end defmac
7221 @defmac AC_SYS_LONG_FILE_NAMES
7222 @acindex{SYS_LONG_FILE_NAMES}
7223 @cvindex HAVE_LONG_FILE_NAMES
7224 If the system supports file names longer than 14 characters, define
7225 @code{HAVE_LONG_FILE_NAMES}.
7226 @end defmac
7228 @defmac AC_SYS_POSIX_TERMIOS
7229 @acindex{SYS_POSIX_TERMIOS}
7230 @cindex Posix termios headers
7231 @cindex termios Posix headers
7232 Check to see if the Posix termios headers and functions are available on the
7233 system.  If so, set the shell variable @code{ac_cv_sys_posix_termios} to
7234 @samp{yes}.  If not, set the variable to @samp{no}.
7235 @end defmac
7237 @node Posix Variants
7238 @section Posix Variants
7240 The following macros check for certain operating systems that need
7241 special treatment for some programs, due to exceptional oddities in
7242 their header files or libraries.  These macros are warts; they will be
7243 replaced by a more systematic approach, based on the functions they make
7244 available or the environments they provide.
7246 @defmac AC_AIX
7247 @acindex{AIX}
7248 @cvindex _ALL_SOURCE
7249 If on @acronym{AIX}, define @code{_ALL_SOURCE}.
7250 Allows the use of some @acronym{BSD}
7251 functions.  Should be called before any macros that run the C compiler.
7252 @end defmac
7254 @defmac AC_GNU_SOURCE
7255 @acindex{GNU_SOURCE}
7256 @cvindex _GNU_SOURCE
7257 If using the @acronym{GNU} C library, define @code{_GNU_SOURCE}.
7258 Allows the use of some @acronym{GNU} functions.  Should be called
7259 before any macros that run the C compiler.
7260 @end defmac
7262 @defmac AC_ISC_POSIX
7263 @acindex{ISC_POSIX}
7264 @ovindex LIBS
7265 For @sc{interactive} Systems Corporation Unix, add @option{-lcposix} to output
7266 variable @code{LIBS} if necessary for Posix facilities.  Call this
7267 after @code{AC_PROG_CC} and before any other macros that use Posix
7268 interfaces.
7270 This macro is obsolescent, as @sc{interactive} Unix is obsolete, and Sun
7271 dropped support for it on 2006-07-23.  New programs need not use this
7272 macro.
7273 @end defmac
7275 @defmac AC_MINIX
7276 @acindex{MINIX}
7277 @cvindex _MINIX
7278 @cvindex _POSIX_SOURCE
7279 @cvindex _POSIX_1_SOURCE
7280 If on Minix, define @code{_MINIX} and @code{_POSIX_SOURCE} and define
7281 @code{_POSIX_1_SOURCE} to be 2.  This allows the use of Posix
7282 facilities.  Should be called before any macros that run the C compiler.
7283 @end defmac
7285 @defmac AC_USE_SYSTEM_EXTENSIONS
7286 @acindex{USE_SYSTEM_EXTENSIONS}
7287 @cvindex _ALL_SOURCE
7288 @cvindex _GNU_SOURCE
7289 @cvindex _MINIX
7290 @cvindex _POSIX_1_SOURCE
7291 @cvindex _POSIX_PTHREAD_SEMANTICS
7292 @cvindex _POSIX_SOURCE
7293 @cvindex __EXTENSIONS__
7294 If possible, enable extensions to Posix on hosts that normally disable
7295 the extensions, typically due to standards-conformance namespace issues.
7296 This may involve defining @code{__EXTENSIONS__} and
7297 @code{_POSIX_PTHREAD_SEMANTICS}, which are macros used by Solaris.  This
7298 macro also has the combined effects of @code{AC_GNU_SOURCE},
7299 @code{AC_AIX}, and @code{AC_MINIX}.
7300 @end defmac
7303 @node Erlang Libraries
7304 @section Erlang Libraries
7305 @cindex Erlang, Library, checking
7307 The following macros check for an installation of Erlang/OTP, and for the
7308 presence of certain Erlang libraries.  All those macros require the
7309 configuration of an Erlang interpreter and an Erlang compiler
7310 (@pxref{Erlang Compiler and Interpreter}).
7312 @defmac AC_ERLANG_SUBST_ROOT_DIR
7313 @acindex{ERLANG_SUBST_ROOT_DIR}
7314 @ovindex ERLANG_ROOT_DIR
7316 Set the output variable @code{ERLANG_ROOT_DIR} to the path to the base directory
7317 in which Erlang/OTP is installed (as returned by Erlang's @code{code:root_dir/0}
7318 function).  The result of this test is cached if caching is enabled when running
7319 @command{configure}.
7320 @end defmac
7322 @defmac AC_ERLANG_SUBST_LIB_DIR
7323 @acindex{ERLANG_SUBST_LIB_DIR}
7324 @ovindex ERLANG_LIB_DIR
7326 Set the output variable @code{ERLANG_LIB_DIR} to the path of the library
7327 directory of Erlang/OTP (as returned by Erlang's
7328 @code{code:lib_dir/0} function), which subdirectories each contain an installed
7329 Erlang/OTP library.  The result of this test is cached if caching is enabled
7330 when running @command{configure}.
7331 @end defmac
7333 @defmac AC_ERLANG_CHECK_LIB (@var{library}, @ovar{action-if-found}, @ovar{action-if-not-found})
7334 @acindex{ERLANG_CHECK_LIB}
7335 @ovindex ERLANG_LIB_DIR_@var{library}
7336 @ovindex ERLANG_LIB_VER_@var{library}
7338 Test whether the Erlang/OTP library @var{library} is installed by
7339 calling Erlang's @code{code:lib_dir/1} function.  The result of this
7340 test is cached if caching is enabled when running @command{configure}.
7341 @var{action-if-found} is a list of shell commands to run if the library
7342 is installed; @var{action-if-not-found} is a list of shell commands to
7343 run if it is not.  Additionally, if the library is installed, the output
7344 variable @samp{ERLANG_LIB_DIR_@var{library}} is set to the path to the
7345 library installation directory, and the output variable
7346 @samp{ERLANG_LIB_VER_@var{library}} is set to the version number that is
7347 part of the subdirectory name, if it is in the standard form
7348 (@code{@var{library}-@var{version}}).  If the directory name does not
7349 have a version part, @samp{ERLANG_LIB_VER_@var{library}} is set to the
7350 empty string.  If the library is not installed,
7351 @samp{ERLANG_LIB_DIR_@var{library}} and
7352 @samp{ERLANG_LIB_VER_@var{library}} are set to @code{"not found"}.  For
7353 example, to check if library @code{stdlib} is installed:
7355 @example
7356 AC_ERLANG_CHECK_LIB([stdlib],
7357   [echo "stdlib version \"$ERLANG_LIB_VER_stdlib\""
7358    echo "is installed in \"$ERLANG_LIB_DIR_stdlib\""],
7359   [AC_MSG_ERROR([stdlib was not found!])])
7360 @end example
7361 @end defmac
7363 In addition to the above macros, which test installed Erlang libraries, the
7364 following macros determine the paths to the directories into which newly built
7365 Erlang libraries are to be installed:
7367 @defmac AC_ERLANG_SUBST_INSTALL_LIB_DIR
7368 @acindex{ERLANG_SUBST_INSTALL_LIB_DIR}
7369 @ovindex ERLANG_INSTALL_LIB_DIR
7371 Set the @code{ERLANG_INSTALL_LIB_DIR} output variable to the directory into
7372 which every built Erlang library should be installed in a separate subdirectory.
7373 If this variable is not set in the environment when @command{configure} runs,
7374 its default value is @code{$ERLANG_LIB_DIR}, which value is set by the
7375 @code{AC_ERLANG_SUBST_LIB_DIR} macro.
7376 @end defmac
7378 @defmac AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR (@var{library}, @var{version})
7379 @acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR}
7380 @ovindex ERLANG_INSTALL_LIB_DIR_@var{library}
7382 Set the @samp{ERLANG_INSTALL_LIB_DIR_@var{library}} output variable to the
7383 directory into which the built Erlang library @var{library} version
7384 @var{version} should be installed.  If this variable is not set in the
7385 environment when @command{configure} runs, its default value is
7386 @samp{$ERLANG_INSTALL_LIB_DIR/@var{library}-@var{version}}, the value of the
7387 @code{ERLANG_INSTALL_LIB_DIR} variable being set by the
7388 @code{AC_ERLANG_SUBST_INSTALL_LIB_DIR} macro.
7389 @end defmac
7395 @c ========================================================= Writing Tests
7397 @node Writing Tests
7398 @chapter Writing Tests
7400 If the existing feature tests don't do something you need, you have to
7401 write new ones.  These macros are the building blocks.  They provide
7402 ways for other macros to check whether various kinds of features are
7403 available and report the results.
7405 This chapter contains some suggestions and some of the reasons why the
7406 existing tests are written the way they are.  You can also learn a lot
7407 about how to write Autoconf tests by looking at the existing ones.  If
7408 something goes wrong in one or more of the Autoconf tests, this
7409 information can help you understand the assumptions behind them, which
7410 might help you figure out how to best solve the problem.
7412 These macros check the output of the compiler system of the current
7413 language (@pxref{Language Choice}).  They do not cache the results of
7414 their tests for future use (@pxref{Caching Results}), because they don't
7415 know enough about the information they are checking for to generate a
7416 cache variable name.  They also do not print any messages, for the same
7417 reason.  The checks for particular kinds of features call these macros
7418 and do cache their results and print messages about what they're
7419 checking for.
7421 When you write a feature test that could be applicable to more than one
7422 software package, the best thing to do is encapsulate it in a new macro.
7423 @xref{Writing Autoconf Macros}, for how to do that.
7425 @menu
7426 * Language Choice::             Selecting which language to use for testing
7427 * Writing Test Programs::       Forging source files for compilers
7428 * Running the Preprocessor::    Detecting preprocessor symbols
7429 * Running the Compiler::        Detecting language or header features
7430 * Running the Linker::          Detecting library features
7431 * Runtime::                     Testing for runtime features
7432 * Systemology::                 A zoology of operating systems
7433 * Multiple Cases::              Tests for several possible values
7434 @end menu
7436 @node Language Choice
7437 @section Language Choice
7438 @cindex Language
7440 Autoconf-generated @command{configure} scripts check for the C compiler and
7441 its features by default.  Packages that use other programming languages
7442 (maybe more than one, e.g., C and C++) need to test features of the
7443 compilers for the respective languages.  The following macros determine
7444 which programming language is used in the subsequent tests in
7445 @file{configure.ac}.
7447 @defmac AC_LANG (@var{language})
7448 Do compilation tests using the compiler, preprocessor, and file
7449 extensions for the specified @var{language}.
7451 Supported languages are:
7453 @table @samp
7454 @item C
7455 Do compilation tests using @code{CC} and @code{CPP} and use extension
7456 @file{.c} for test programs.  Use compilation flags: @code{CPPFLAGS} with
7457 @code{CPP}, and both @code{CPPFLAGS} and @code{CFLAGS} with @code{CC}.
7459 @item C++
7460 Do compilation tests using @code{CXX} and @code{CXXCPP} and use
7461 extension @file{.C} for test programs.  Use compilation flags:
7462 @code{CPPFLAGS} with @code{CXXPP}, and both @code{CPPFLAGS} and
7463 @code{CXXFLAGS} with @code{CXX}.
7465 @item Fortran 77
7466 Do compilation tests using @code{F77} and use extension @file{.f} for
7467 test programs.  Use compilation flags: @code{FFLAGS}.
7469 @item Fortran
7470 Do compilation tests using @code{FC} and use extension @file{.f} (or
7471 whatever has been set by @code{AC_FC_SRCEXT}) for test programs.  Use
7472 compilation flags: @code{FCFLAGS}.
7474 @item Erlang
7475 @ovindex ERLC
7476 @ovindex ERL
7477 @ovindex ERLCFLAGS
7478 Compile and execute tests using @code{ERLC} and @code{ERL} and use extension
7479 @file{.erl} for test Erlang modules.  Use compilation flags: @code{ERLCFLAGS}.
7481 @item Objective C
7482 Do compilation tests using @code{OBJC} and @code{OBJCCPP} and use
7483 extension @file{.m} for test programs.  Use compilation flags:
7484 @code{CPPFLAGS} with @code{OBJCPP}, and both @code{CPPFLAGS} and
7485 @code{OBJCFLAGS} with @code{OBJC}.
7486 @end table
7487 @end defmac
7489 @defmac AC_LANG_PUSH (@var{language})
7490 @acindex{LANG_PUSH}
7491 Remember the current language (as set by @code{AC_LANG}) on a stack, and
7492 then select the @var{language}.  Use this macro and @code{AC_LANG_POP}
7493 in macros that need to temporarily switch to a particular language.
7494 @end defmac
7496 @defmac AC_LANG_POP (@ovar{language})
7497 @acindex{LANG_POP}
7498 Select the language that is saved on the top of the stack, as set by
7499 @code{AC_LANG_PUSH}, and remove it from the stack.
7501 If given, @var{language} specifies the language we just @emph{quit}.  It
7502 is a good idea to specify it when it's known (which should be the
7503 case@dots{}), since Autoconf detects inconsistencies.
7505 @example
7506 AC_LANG_PUSH([Fortran 77])
7507 # Perform some tests on Fortran 77.
7508 # @dots{}
7509 AC_LANG_POP([Fortran 77])
7510 @end example
7511 @end defmac
7513 @defmac AC_LANG_ASSERT (@var{language})
7514 @acindex{LANG_ASSERT} Check statically that the current language is
7515 @var{language}.  You should use this in your language specific macros
7516 to avoid that they be called with an inappropriate language.
7518 This macro runs only at @command{autoconf} time, and incurs no cost at
7519 @command{configure} time.  Sadly enough and because Autoconf is a two
7520 layer language @footnote{Because M4 is not aware of Sh code,
7521 especially conditionals, some optimizations that look nice statically
7522 may produce incorrect results at runtime.}, the macros
7523 @code{AC_LANG_PUSH} and @code{AC_LANG_POP} cannot be ``optimizing'',
7524 therefore as much as possible you ought to avoid using them to wrap
7525 your code, rather, require from the user to run the macro with a
7526 correct current language, and check it with @code{AC_LANG_ASSERT}.
7527 And anyway, that may help the user understand she is running a Fortran
7528 macro while expecting a result about her Fortran 77 compiler@dots{}
7529 @end defmac
7532 @defmac AC_REQUIRE_CPP
7533 @acindex{REQUIRE_CPP}
7534 Ensure that whichever preprocessor would currently be used for tests has
7535 been found.  Calls @code{AC_REQUIRE} (@pxref{Prerequisite Macros}) with an
7536 argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP},
7537 depending on which language is current.
7538 @end defmac
7541 @node Writing Test Programs
7542 @section Writing Test Programs
7544 Autoconf tests follow a common scheme: feed some program with some
7545 input, and most of the time, feed a compiler with some source file.
7546 This section is dedicated to these source samples.
7548 @menu
7549 * Guidelines::                  General rules for writing test programs
7550 * Test Functions::              Avoiding pitfalls in test programs
7551 * Generating Sources::          Source program boilerplate
7552 @end menu
7554 @node Guidelines
7555 @subsection Guidelines for Test Programs
7557 The most important rule to follow when writing testing samples is:
7559 @center @emph{Look for realism.}
7561 This motto means that testing samples must be written with the same
7562 strictness as real programs are written.  In particular, you should
7563 avoid ``shortcuts'' and simplifications.
7565 Don't just play with the preprocessor if you want to prepare a
7566 compilation.  For instance, using @command{cpp} to check whether a header is
7567 functional might let your @command{configure} accept a header which
7568 causes some @emph{compiler} error.  Do not hesitate to check a header with
7569 other headers included before, especially required headers.
7571 Make sure the symbols you use are properly defined, i.e., refrain for
7572 simply declaring a function yourself instead of including the proper
7573 header.
7575 Test programs should not write to standard output.  They
7576 should exit with status 0 if the test succeeds, and with status 1
7577 otherwise, so that success
7578 can be distinguished easily from a core dump or other failure;
7579 segmentation violations and other failures produce a nonzero exit
7580 status.  Unless you arrange for @code{exit} to be declared, test
7581 programs should @code{return}, not @code{exit}, from @code{main},
7582 because on many systems @code{exit} is not declared by default.
7584 Test programs can use @code{#if} or @code{#ifdef} to check the values of
7585 preprocessor macros defined by tests that have already run.  For
7586 example, if you call @code{AC_HEADER_STDBOOL}, then later on in
7587 @file{configure.ac} you can have a test program that includes
7588 @file{stdbool.h} conditionally:
7590 @example
7591 @group
7592 #ifdef HAVE_STDBOOL_H
7593 # include <stdbool.h>
7594 #endif
7595 @end group
7596 @end example
7598 Both @code{#if HAVE_STDBOOL_H} and @code{#ifdef HAVE_STDBOOL_H} will
7599 work with any standard C compiler.  Some developers prefer @code{#if}
7600 because it is easier to read, while others prefer @code{#ifdef} because
7601 it avoids diagnostics with picky compilers like @acronym{GCC} with the
7602 @option{-Wundef} option.
7604 If a test program needs to use or create a data file, give it a name
7605 that starts with @file{conftest}, such as @file{conftest.data}.  The
7606 @command{configure} script cleans up by running @samp{rm -f -r conftest*}
7607 after running test programs and if the script is interrupted.
7609 @node Test Functions
7610 @subsection Test Functions
7612 These days it's safe to assume support for function prototypes
7613 (introduced in C89).
7615 Functions that test programs declare should also be conditionalized for
7616 C++, which requires @samp{extern "C"} prototypes.  Make sure to not
7617 include any header files containing clashing prototypes.
7619 @example
7620 #ifdef __cplusplus
7621 extern "C"
7622 #endif
7623 void *valloc (size_t);
7624 @end example
7626 If a test program calls a function with invalid parameters (just to see
7627 whether it exists), organize the program to ensure that it never invokes
7628 that function.  You can do this by calling it in another function that is
7629 never invoked.  You can't do it by putting it after a call to
7630 @code{exit}, because @acronym{GCC} version 2 knows that @code{exit}
7631 never returns
7632 and optimizes out any code that follows it in the same block.
7634 If you include any header files, be sure to call the functions
7635 relevant to them with the correct number of arguments, even if they are
7636 just 0, to avoid compilation errors due to prototypes.  @acronym{GCC}
7637 version 2
7638 has internal prototypes for several functions that it automatically
7639 inlines; for example, @code{memcpy}.  To avoid errors when checking for
7640 them, either pass them the correct number of arguments or redeclare them
7641 with a different return type (such as @code{char}).
7644 @node Generating Sources
7645 @subsection Generating Sources
7647 Autoconf provides a set of macros that can be used to generate test
7648 source files.  They are written to be language generic, i.e., they
7649 actually depend on the current language (@pxref{Language Choice}) to
7650 ``format'' the output properly.
7653 @defmac AC_LANG_CONFTEST (@var{source})
7654 @acindex{LANG_CONFTEST}
7655 Save the @var{source} text in the current test source file:
7656 @file{conftest.@var{extension}} where the @var{extension} depends on the
7657 current language.
7659 Note that the @var{source} is evaluated exactly once, like regular
7660 Autoconf macro arguments, and therefore (i) you may pass a macro
7661 invocation, (ii) if not, be sure to double quote if needed.
7662 @end defmac
7664 @defmac AC_LANG_SOURCE (@var{source})
7665 @acindex{LANG_SOURCE}
7666 Expands into the @var{source}, with the definition of
7667 all the @code{AC_DEFINE} performed so far.
7668 @end defmac
7670 For instance executing (observe the double quotation!):
7672 @example
7673 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7674 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
7675   [Greetings string.])
7676 AC_LANG(C)
7677 AC_LANG_CONFTEST(
7678    [AC_LANG_SOURCE([[const char hw[] = "Hello, World\n";]])])
7679 gcc -E -dD -o - conftest.c
7680 @end example
7682 @noindent
7683 results in:
7685 @example
7686 @dots{}
7687 # 1 "conftest.c"
7689 #define PACKAGE_NAME "Hello"
7690 #define PACKAGE_TARNAME "hello"
7691 #define PACKAGE_VERSION "1.0"
7692 #define PACKAGE_STRING "Hello 1.0"
7693 #define PACKAGE_BUGREPORT "bug-hello@@example.org"
7694 #define HELLO_WORLD "Hello, World\n"
7696 const char hw[] = "Hello, World\n";
7697 @end example
7699 When the test language is Fortran or Erlang, the @code{AC_DEFINE} definitions
7700 are not automatically translated into constants in the source code by this
7701 macro.
7703 @defmac AC_LANG_PROGRAM (@var{prologue}, @var{body})
7704 @acindex{LANG_PROGRAM}
7705 Expands into a source file which consists of the @var{prologue}, and
7706 then @var{body} as body of the main function (e.g., @code{main} in
7707 C).  Since it uses @code{AC_LANG_SOURCE}, the features of the latter are
7708 available.
7709 @end defmac
7711 For instance:
7713 @example
7714 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7715 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
7716   [Greetings string.])
7717 AC_LANG_CONFTEST(
7718 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
7719                  [[fputs (hw, stdout);]])])
7720 gcc -E -dD -o - conftest.c
7721 @end example
7723 @noindent
7724 results in:
7726 @example
7727 @dots{}
7728 # 1 "conftest.c"
7730 #define PACKAGE_NAME "Hello"
7731 #define PACKAGE_TARNAME "hello"
7732 #define PACKAGE_VERSION "1.0"
7733 #define PACKAGE_STRING "Hello 1.0"
7734 #define PACKAGE_BUGREPORT "bug-hello@@example.org"
7735 #define HELLO_WORLD "Hello, World\n"
7737 const char hw[] = "Hello, World\n";
7739 main ()
7741 fputs (hw, stdout);
7742   ;
7743   return 0;
7745 @end example
7747 In Erlang tests, the created source file is that of an Erlang module called
7748 @code{conftest} (@file{conftest.erl}).  This module defines and exports at least
7749 one @code{start/0} function, which is called to perform the test.  The
7750 @var{prologue} is optional code that is inserted between the module header and
7751 the @code{start/0} function definition.  @var{body} is the body of the
7752 @code{start/0} function without the final period (@pxref{Runtime}, about
7753 constraints on this function's behavior).
7755 For instance:
7757 @example
7758 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7759 AC_LANG(Erlang)
7760 AC_LANG_CONFTEST(
7761 [AC_LANG_PROGRAM([[-define(HELLO_WORLD, "Hello, world!").]],
7762                  [[io:format("~s~n", [?HELLO_WORLD])]])])
7763 cat conftest.erl
7764 @end example
7766 @noindent
7767 results in:
7769 @example
7770 -module(conftest).
7771 -export([start/0]).
7772 -define(HELLO_WORLD, "Hello, world!").
7773 start() ->
7774 io:format("~s~n", [?HELLO_WORLD])
7776 @end example
7778 @defmac AC_LANG_CALL (@var{prologue}, @var{function})
7779 @acindex{LANG_CALL}
7780 Expands into a source file which consists of the @var{prologue}, and
7781 then a call to the @var{function} as body of the main function (e.g.,
7782 @code{main} in C).  Since it uses @code{AC_LANG_PROGRAM}, the feature
7783 of the latter are available.
7785 This function will probably be replaced in the future by a version
7786 which would enable specifying the arguments.  The use of this macro is
7787 not encouraged, as it violates strongly the typing system.
7789 This macro cannot be used for Erlang tests.
7790 @end defmac
7792 @defmac AC_LANG_FUNC_LINK_TRY (@var{function})
7793 @acindex{LANG_FUNC_LINK_TRY}
7794 Expands into a source file which uses the @var{function} in the body of
7795 the main function (e.g., @code{main} in C).  Since it uses
7796 @code{AC_LANG_PROGRAM}, the features of the latter are available.
7798 As @code{AC_LANG_CALL}, this macro is documented only for completeness.
7799 It is considered to be severely broken, and in the future will be
7800 removed in favor of actual function calls (with properly typed
7801 arguments).
7803 This macro cannot be used for Erlang tests.
7804 @end defmac
7806 @node Running the Preprocessor
7807 @section Running the Preprocessor
7809 Sometimes one might need to run the preprocessor on some source file.
7810 @emph{Usually it is a bad idea}, as you typically need to @emph{compile}
7811 your project, not merely run the preprocessor on it; therefore you
7812 certainly want to run the compiler, not the preprocessor.  Resist the
7813 temptation of following the easiest path.
7815 Nevertheless, if you need to run the preprocessor, then use
7816 @code{AC_PREPROC_IFELSE}.
7818 The macros described in this section cannot be used for tests in Erlang or
7819 Fortran, since those languages require no preprocessor.
7821 @defmac AC_PREPROC_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
7822 @acindex{PREPROC_IFELSE}
7823 Run the preprocessor of the current language (@pxref{Language Choice})
7824 on the @var{input}, run the shell commands @var{action-if-true} on
7825 success, @var{action-if-false} otherwise.  The @var{input} can be made
7826 by @code{AC_LANG_PROGRAM} and friends.
7828 This macro uses @code{CPPFLAGS}, but not @code{CFLAGS}, because
7829 @option{-g}, @option{-O}, etc.@: are not valid options to many C
7830 preprocessors.
7832 It is customary to report unexpected failures with
7833 @code{AC_MSG_FAILURE}.
7834 @end defmac
7836 For instance:
7838 @example
7839 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7840 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
7841   [Greetings string.])
7842 AC_PREPROC_IFELSE(
7843    [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
7844                     [[fputs (hw, stdout);]])],
7845    [AC_MSG_RESULT([OK])],
7846    [AC_MSG_FAILURE([unexpected preprocessor failure])])
7847 @end example
7849 @noindent
7850 results in:
7852 @example
7853 checking for gcc... gcc
7854 checking for C compiler default output file name... a.out
7855 checking whether the C compiler works... yes
7856 checking whether we are cross compiling... no
7857 checking for suffix of executables...
7858 checking for suffix of object files... o
7859 checking whether we are using the GNU C compiler... yes
7860 checking whether gcc accepts -g... yes
7861 checking for gcc option to accept ISO C89... none needed
7862 checking how to run the C preprocessor... gcc -E
7864 @end example
7866 @sp 1
7868 The macro @code{AC_TRY_CPP} (@pxref{Obsolete Macros}) used to play the
7869 role of @code{AC_PREPROC_IFELSE}, but double quotes its argument, making
7870 it impossible to use it to elaborate sources.  You are encouraged to
7871 get rid of your old use of the macro @code{AC_TRY_CPP} in favor of
7872 @code{AC_PREPROC_IFELSE}, but, in the first place, are you sure you need
7873 to run the @emph{preprocessor} and not the compiler?
7875 @defmac AC_EGREP_HEADER (@var{pattern}, @var{header-file}, @var{action-if-found}, @ovar{action-if-not-found})
7876 @acindex{EGREP_HEADER}
7877 If the output of running the preprocessor on the system header file
7878 @var{header-file} matches the extended regular expression
7879 @var{pattern}, execute shell commands @var{action-if-found}, otherwise
7880 execute @var{action-if-not-found}.
7881 @end defmac
7883 @defmac AC_EGREP_CPP (@var{pattern}, @var{program}, @ovar{action-if-found}, @ovar{action-if-not-found})
7884 @acindex{EGREP_CPP}
7885 @var{program} is the text of a C or C++ program, on which shell
7886 variable, back quote, and backslash substitutions are performed.  If the
7887 output of running the preprocessor on @var{program} matches the
7888 extended regular expression @var{pattern}, execute shell commands
7889 @var{action-if-found}, otherwise execute @var{action-if-not-found}.
7890 @end defmac
7894 @node Running the Compiler
7895 @section Running the Compiler
7897 To check for a syntax feature of the current language's (@pxref{Language
7898 Choice}) compiler, such as whether it recognizes a certain keyword, or
7899 simply to try some library feature, use @code{AC_COMPILE_IFELSE} to try
7900 to compile a small program that uses that feature.
7902 @defmac AC_COMPILE_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
7903 @acindex{COMPILE_IFELSE}
7904 Run the compiler and compilation flags of the current language
7905 (@pxref{Language Choice}) on the @var{input}, run the shell commands
7906 @var{action-if-true} on success, @var{action-if-false} otherwise.  The
7907 @var{input} can be made by @code{AC_LANG_PROGRAM} and friends.
7909 It is customary to report unexpected failures with
7910 @code{AC_MSG_FAILURE}.  This macro does not try to link; use
7911 @code{AC_LINK_IFELSE} if you need to do that (@pxref{Running the
7912 Linker}).
7913 @end defmac
7915 @ovindex ERL
7916 For tests in Erlang, the @var{input} must be the source code of a module named
7917 @code{conftest}.  @code{AC_COMPILE_IFELSE} generates a @file{conftest.beam}
7918 file that can be interpreted by the Erlang virtual machine (@code{ERL}).  It is
7919 recommended to use @code{AC_LANG_PROGRAM} to specify the test program, to ensure
7920 that the Erlang module has the right name.
7922 @node Running the Linker
7923 @section Running the Linker
7925 To check for a library, a function, or a global variable, Autoconf
7926 @command{configure} scripts try to compile and link a small program that
7927 uses it.  This is unlike Metaconfig, which by default uses @code{nm} or
7928 @code{ar} on the C library to try to figure out which functions are
7929 available.  Trying to link with the function is usually a more reliable
7930 approach because it avoids dealing with the variations in the options
7931 and output formats of @code{nm} and @code{ar} and in the location of the
7932 standard libraries.  It also allows configuring for cross-compilation or
7933 checking a function's runtime behavior if needed.  On the other hand,
7934 it can be slower than scanning the libraries once, but accuracy is more
7935 important than speed.
7937 @code{AC_LINK_IFELSE} is used to compile test programs to test for
7938 functions and global variables.  It is also used by @code{AC_CHECK_LIB}
7939 to check for libraries (@pxref{Libraries}), by adding the library being
7940 checked for to @code{LIBS} temporarily and trying to link a small
7941 program.
7944 @defmac AC_LINK_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
7945 @acindex{LINK_IFELSE}
7946 Run the compiler (and compilation flags) and the linker of the current
7947 language (@pxref{Language Choice}) on the @var{input}, run the shell
7948 commands @var{action-if-true} on success, @var{action-if-false}
7949 otherwise.  The @var{input} can be made by @code{AC_LANG_PROGRAM} and
7950 friends.
7952 @code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
7953 current compilation flags.
7955 It is customary to report unexpected failures with
7956 @code{AC_MSG_FAILURE}.  This macro does not try to execute the program;
7957 use @code{AC_RUN_IFELSE} if you need to do that (@pxref{Runtime}).
7958 @end defmac
7960 The @code{AC_LINK_IFELSE} macro cannot be used for Erlang tests, since Erlang
7961 programs are interpreted and do not require linking.
7965 @node Runtime
7966 @section Checking Runtime Behavior
7968 Sometimes you need to find out how a system performs at runtime, such
7969 as whether a given function has a certain capability or bug.  If you
7970 can, make such checks when your program runs instead of when it is
7971 configured.  You can check for things like the machine's endianness when
7972 your program initializes itself.
7974 If you really need to test for a runtime behavior while configuring,
7975 you can write a test program to determine the result, and compile and
7976 run it using @code{AC_RUN_IFELSE}.  Avoid running test programs if
7977 possible, because this prevents people from configuring your package for
7978 cross-compiling.
7980 @defmac AC_RUN_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-cross-compiling})
7981 @acindex{RUN_IFELSE}
7982 If @var{program} compiles and links successfully and returns an exit
7983 status of 0 when executed, run shell commands @var{action-if-true}.
7984 Otherwise, run shell commands @var{action-if-false}.
7986 The @var{input} can be made by @code{AC_LANG_PROGRAM} and friends.
7987 @code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
7988 compilation flags of the current language (@pxref{Language Choice}).
7990 If the compiler being used does not produce executables that run on the
7991 system where @command{configure} is being run, then the test program is
7992 not run.  If the optional shell commands @var{action-if-cross-compiling}
7993 are given, they are run instead.  Otherwise, @command{configure} prints
7994 an error message and exits.
7996 In the @var{action-if-false} section, the failing exit status is
7997 available in the shell variable @samp{$?}.  This exit status might be
7998 that of a failed compilation, or it might be that of a failed program
7999 execution.
8001 It is customary to report unexpected failures with
8002 @code{AC_MSG_FAILURE}.
8003 @end defmac
8005 Try to provide a pessimistic default value to use when cross-compiling
8006 makes runtime tests impossible.  You do this by passing the optional
8007 last argument to @code{AC_RUN_IFELSE}.  @command{autoconf} prints a
8008 warning message when creating @command{configure} each time it
8009 encounters a call to @code{AC_RUN_IFELSE} with no
8010 @var{action-if-cross-compiling} argument given.  You may ignore the
8011 warning, though users cannot configure your package for
8012 cross-compiling.  A few of the macros distributed with Autoconf produce
8013 this warning message.
8015 To configure for cross-compiling you can also choose a value for those
8016 parameters based on the canonical system name (@pxref{Manual
8017 Configuration}).  Alternatively, set up a test results cache file with
8018 the correct values for the host system (@pxref{Caching Results}).
8020 @ovindex cross_compiling
8021 To provide a default for calls of @code{AC_RUN_IFELSE} that are embedded
8022 in other macros, including a few of the ones that come with Autoconf,
8023 you can test whether the shell variable @code{cross_compiling} is set to
8024 @samp{yes}, and then use an alternate method to get the results instead
8025 of calling the macros.
8027 A C or C++ runtime test should be portable.
8028 @xref{Portable C and C++}.
8030 Erlang tests must exit themselves the Erlang VM by calling the @code{halt/1}
8031 function: the given status code is used to determine the success of the test
8032 (status is @code{0}) or its failure (status is different than @code{0}), as
8033 explained above.  It must be noted that data output through the standard output
8034 (e.g., using @code{io:format/2}) may be truncated when halting the VM.
8035 Therefore, if a test must output configuration information, it is recommended
8036 to create and to output data into the temporary file named @file{conftest.out},
8037 using the functions of module @code{file}.  The @code{conftest.out} file is
8038 automatically deleted by the @code{AC_RUN_IFELSE} macro.  For instance, a
8039 simplified implementation of Autoconf's @code{AC_ERLANG_SUBST_LIB_DIR} macro is:
8041 @example
8042 AC_INIT([LibdirTest], [1.0], [bug-libdirtest@@example.org])
8043 AC_ERLANG_NEED_ERL
8044 AC_LANG(Erlang)
8045 AC_RUN_IFELSE(
8046   [AC_LANG_PROGRAM([], [dnl
8047     file:write_file("conftest.out", code:lib_dir()),
8048     halt(0)])],
8049   [echo "code:lib_dir() returned: `cat conftest.out`"],
8050   [AC_MSG_FAILURE([test Erlang program execution failed])])
8051 @end example
8054 @node Systemology
8055 @section Systemology
8056 @cindex Systemology
8058 This section aims at presenting some systems and pointers to
8059 documentation.  It may help you addressing particular problems reported
8060 by users.
8062 @uref{http://www.opengroup.org/susv3, Posix-conforming systems} are
8063 derived from the @uref{http://www.bell-labs.com/history/unix/, Unix
8064 operating system}.
8066 The @uref{http://bhami.com/rosetta.html, Rosetta Stone for Unix}
8067 contains a table correlating the features of various Posix-conforming
8068 systems.  @uref{http://www.levenez.com/unix/, Unix History} is a
8069 simplified diagram of how many Unix systems were derived from each
8070 other.
8072 @uref{http://heirloom.sourceforge.net/, The Heirloom Project}
8073 provides some variants of traditional implementations of Unix utilities.
8075 @table @asis
8076 @item Darwin
8077 @cindex Darwin
8078 Darwin is also known as Mac OS X@.  Beware that the file system @emph{can} be
8079 case-preserving, but case insensitive.  This can cause nasty problems,
8080 since for instance the installation attempt for a package having an
8081 @file{INSTALL} file can result in @samp{make install} report that
8082 nothing was to be done!
8084 That's all dependent on whether the file system is a UFS (case
8085 sensitive) or HFS+ (case preserving).  By default Apple wants you to
8086 install the OS on HFS+.  Unfortunately, there are some pieces of
8087 software which really need to be built on UFS@.  We may want to rebuild
8088 Darwin to have both UFS and HFS+ available (and put the /local/build
8089 tree on the UFS).
8091 @item @acronym{QNX} 4.25
8092 @cindex @acronym{QNX} 4.25
8093 @c FIXME: Please, if you feel like writing something more precise,
8094 @c it'd be great.  In particular, I can't understand the difference with
8095 @c QNX Neutrino.
8096 @acronym{QNX} is a realtime operating system running on Intel architecture
8097 meant to be scalable from the small embedded systems to the hundred
8098 processor super-computer.  It claims to be Posix certified.  More
8099 information is available on the
8100 @uref{http://www.qnx.com/, @acronym{QNX} home page}.
8102 @item Tru64
8103 @cindex Tru64
8104 @uref{http://h30097.www3.hp.com/@/docs/,
8105 Documentation of several versions of Tru64} is available in different
8106 formats.
8108 @item Unix version 7
8109 @cindex Unix version 7
8110 @cindex V7
8111 Officially this was called the ``Seventh Edition'' of ``the @sc{unix}
8112 time-sharing system'' but we use the more-common name ``Unix version 7''.
8113 Documentation is available in the
8114 @uref{http://plan9.bell-labs.com/@/7thEdMan/, Unix Seventh Edition Manual}.
8115 Previous versions of Unix are called ``Unix version 6'', etc., but
8116 they were not as widely used.
8117 @end table
8120 @node Multiple Cases
8121 @section Multiple Cases
8123 Some operations are accomplished in several possible ways, depending on
8124 the OS variant.  Checking for them essentially requires a ``case
8125 statement''.  Autoconf does not directly provide one; however, it is
8126 easy to simulate by using a shell variable to keep track of whether a
8127 way to perform the operation has been found yet.
8129 Here is an example that uses the shell variable @code{fstype} to keep
8130 track of whether the remaining cases need to be checked.
8132 @example
8133 @group
8134 AC_MSG_CHECKING([how to get file system type])
8135 fstype=no
8136 # The order of these tests is important.
8137 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statvfs.h>
8138 #include <sys/fstyp.h>]])],
8139                   [AC_DEFINE([FSTYPE_STATVFS], [1],
8140                      [Define if statvfs exists.])
8141                    fstype=SVR4])
8142 if test $fstype = no; then
8143   AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
8144 #include <sys/fstyp.h>]])],
8145                   [AC_DEFINE([FSTYPE_USG_STATFS], [1],
8146                      [Define if USG statfs.])
8147                    fstype=SVR3])
8149 if test $fstype = no; then
8150   AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
8151 #include <sys/vmount.h>]])]),
8152                   [AC_DEFINE([FSTYPE_AIX_STATFS], [1],
8153                      [Define if AIX statfs.])
8154                    fstype=AIX])
8156 # (more cases omitted here)
8157 AC_MSG_RESULT([$fstype])
8158 @end group
8159 @end example
8161 @c ====================================================== Results of Tests.
8163 @node Results
8164 @chapter Results of Tests
8166 Once @command{configure} has determined whether a feature exists, what can
8167 it do to record that information?  There are four sorts of things it can
8168 do: define a C preprocessor symbol, set a variable in the output files,
8169 save the result in a cache file for future @command{configure} runs, and
8170 print a message letting the user know the result of the test.
8172 @menu
8173 * Defining Symbols::            Defining C preprocessor symbols
8174 * Setting Output Variables::    Replacing variables in output files
8175 * Special Chars in Variables::  Characters to beware of in variables
8176 * Caching Results::             Speeding up subsequent @command{configure} runs
8177 * Printing Messages::           Notifying @command{configure} users
8178 @end menu
8180 @node Defining Symbols
8181 @section Defining C Preprocessor Symbols
8183 A common action to take in response to a feature test is to define a C
8184 preprocessor symbol indicating the results of the test.  That is done by
8185 calling @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}.
8187 By default, @code{AC_OUTPUT} places the symbols defined by these macros
8188 into the output variable @code{DEFS}, which contains an option
8189 @option{-D@var{symbol}=@var{value}} for each symbol defined.  Unlike in
8190 Autoconf version 1, there is no variable @code{DEFS} defined while
8191 @command{configure} is running.  To check whether Autoconf macros have
8192 already defined a certain C preprocessor symbol, test the value of the
8193 appropriate cache variable, as in this example:
8195 @example
8196 AC_CHECK_FUNC([vprintf], [AC_DEFINE([HAVE_VPRINTF], [1],
8197                           [Define if vprintf exists.])])
8198 if test "$ac_cv_func_vprintf" != yes; then
8199   AC_CHECK_FUNC([_doprnt], [AC_DEFINE([HAVE_DOPRNT], [1],
8200                             [Define if _doprnt exists.])])
8202 @end example
8204 If @code{AC_CONFIG_HEADERS} has been called, then instead of creating
8205 @code{DEFS}, @code{AC_OUTPUT} creates a header file by substituting the
8206 correct values into @code{#define} statements in a template file.
8207 @xref{Configuration Headers}, for more information about this kind of
8208 output.
8210 @defmac AC_DEFINE (@var{variable}, @var{value}, @ovar{description})
8211 @defmacx AC_DEFINE (@var{variable})
8212 @acindex{DEFINE}
8213 Define the C preprocessor variable @var{variable} to @var{value} (verbatim).
8214 @var{value} should not contain literal newlines, and if you are not
8215 using @code{AC_CONFIG_HEADERS} it should not contain any @samp{#}
8216 characters, as @command{make} tends to eat them.  To use a shell variable,
8217 use @code{AC_DEFINE_UNQUOTED} instead.
8218 @var{description} is only useful if you are using
8219 @code{AC_CONFIG_HEADERS}.  In this case, @var{description} is put into
8220 the generated @file{config.h.in} as the comment before the macro define.
8221 The following example defines the C preprocessor variable
8222 @code{EQUATION} to be the string constant @samp{"$a > $b"}:
8224 @example
8225 AC_DEFINE([EQUATION], ["$a > $b"],
8226   [Equation string.])
8227 @end example
8229 If neither @var{value} nor @var{description} are given, then
8230 @var{value} defaults to 1 instead of to the empty string.  This is for
8231 backwards compatibility with older versions of Autoconf, but this usage
8232 is obsolescent and may be withdrawn in future versions of Autoconf.
8234 If the @var{variable} is a literal string, it is passed to
8235 @code{m4_pattern_allow} (@pxref{Forbidden Patterns}).
8236 @end defmac
8238 @defmac AC_DEFINE_UNQUOTED (@var{variable}, @var{value}, @ovar{description})
8239 @defmacx AC_DEFINE_UNQUOTED (@var{variable})
8240 @acindex{DEFINE_UNQUOTED}
8241 Like @code{AC_DEFINE}, but three shell expansions are
8242 performed---once---on @var{variable} and @var{value}: variable expansion
8243 (@samp{$}), command substitution (@samp{`}), and backslash escaping
8244 (@samp{\}).  Single and double quote characters in the value have no
8245 special meaning.  Use this macro instead of @code{AC_DEFINE} when
8246 @var{variable} or @var{value} is a shell variable.  Examples:
8248 @example
8249 AC_DEFINE_UNQUOTED([config_machfile], ["$machfile"],
8250   [Configuration machine file.])
8251 AC_DEFINE_UNQUOTED([GETGROUPS_T], [$ac_cv_type_getgroups],
8252   [getgroups return type.])
8253 AC_DEFINE_UNQUOTED([$ac_tr_hdr], [1],
8254   [Translated header name.])
8255 @end example
8256 @end defmac
8258 Due to a syntactical bizarreness of the Bourne shell, do not use
8259 semicolons to separate @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}
8260 calls from other macro calls or shell code; that can cause syntax errors
8261 in the resulting @command{configure} script.  Use either blanks or
8262 newlines.  That is, do this:
8264 @example
8265 AC_CHECK_HEADER([elf.h],
8266   [AC_DEFINE([SVR4], [1], [System V Release 4]) LIBS="-lelf $LIBS"])
8267 @end example
8269 @noindent
8270 or this:
8272 @example
8273 AC_CHECK_HEADER([elf.h],
8274   [AC_DEFINE([SVR4], [1], [System V Release 4])
8275    LIBS="-lelf $LIBS"])
8276 @end example
8278 @noindent
8279 instead of this:
8281 @example
8282 AC_CHECK_HEADER([elf.h],
8283   [AC_DEFINE([SVR4], [1], [System V Release 4]); LIBS="-lelf $LIBS"])
8284 @end example
8286 @node Setting Output Variables
8287 @section Setting Output Variables
8288 @cindex Output variables
8290 Another way to record the results of tests is to set @dfn{output
8291 variables}, which are shell variables whose values are substituted into
8292 files that @command{configure} outputs.  The two macros below create new
8293 output variables.  @xref{Preset Output Variables}, for a list of output
8294 variables that are always available.
8296 @defmac AC_SUBST (@var{variable}, @ovar{value})
8297 @acindex{SUBST}
8298 Create an output variable from a shell variable.  Make @code{AC_OUTPUT}
8299 substitute the variable @var{variable} into output files (typically one
8300 or more makefiles).  This means that @code{AC_OUTPUT}
8301 replaces instances of @samp{@@@var{variable}@@} in input files with the
8302 value that the shell variable @var{variable} has when @code{AC_OUTPUT}
8303 is called.  The value can contain newlines.
8304 The substituted value is not rescanned for more output variables;
8305 occurrences of @samp{@@@var{variable}@@} in the value are inserted
8306 literally into the output file.  (The algorithm uses the special marker
8307 @code{|#_!!_#|} internally, so the substituted value cannot contain
8308 @code{|#_!!_#|}.)
8310 If @var{value} is given, in addition assign it to @var{variable}.
8312 The string @var{variable} is passed to @code{m4_pattern_allow}
8313 (@pxref{Forbidden Patterns}).
8314 @end defmac
8316 @defmac AC_SUBST_FILE (@var{variable})
8317 @acindex{SUBST_FILE}
8318 Another way to create an output variable from a shell variable.  Make
8319 @code{AC_OUTPUT} insert (without substitutions) the contents of the file
8320 named by shell variable @var{variable} into output files.  This means
8321 that @code{AC_OUTPUT} replaces instances of
8322 @samp{@@@var{variable}@@} in output files (such as @file{Makefile.in})
8323 with the contents of the file that the shell variable @var{variable}
8324 names when @code{AC_OUTPUT} is called.  Set the variable to
8325 @file{/dev/null} for cases that do not have a file to insert.
8326 This substitution occurs only when the @samp{@@@var{variable}@@} is on a
8327 line by itself, optionally surrounded by spaces and tabs.  The
8328 substitution replaces the whole line, including the spaces, tabs, and
8329 the terminating newline.
8331 This macro is useful for inserting makefile fragments containing
8332 special dependencies or other @code{make} directives for particular host
8333 or target types into makefiles.  For example, @file{configure.ac}
8334 could contain:
8336 @example
8337 AC_SUBST_FILE([host_frag])
8338 host_frag=$srcdir/conf/sun4.mh
8339 @end example
8341 @noindent
8342 and then a @file{Makefile.in} could contain:
8344 @example
8345 @@host_frag@@
8346 @end example
8348 The string @var{variable} is passed to @code{m4_pattern_allow}
8349 (@pxref{Forbidden Patterns}).
8350 @end defmac
8352 @cindex Previous Variable
8353 @cindex Variable, Precious
8354 Running @command{configure} in varying environments can be extremely
8355 dangerous.  If for instance the user runs @samp{CC=bizarre-cc
8356 ./configure}, then the cache, @file{config.h}, and many other output
8357 files depend upon @command{bizarre-cc} being the C compiler.  If
8358 for some reason the user runs @command{./configure} again, or if it is
8359 run via @samp{./config.status --recheck}, (@xref{Automatic Remaking},
8360 and @pxref{config.status Invocation}), then the configuration can be
8361 inconsistent, composed of results depending upon two different
8362 compilers.
8364 Environment variables that affect this situation, such as @samp{CC}
8365 above, are called @dfn{precious variables}, and can be declared as such
8366 by @code{AC_ARG_VAR}.
8368 @defmac AC_ARG_VAR (@var{variable}, @var{description})
8369 @acindex{ARG_VAR}
8370 Declare @var{variable} is a precious variable, and include its
8371 @var{description} in the variable section of @samp{./configure --help}.
8373 Being precious means that
8374 @itemize @minus
8375 @item
8376 @var{variable} is substituted via @code{AC_SUBST}.
8378 @item
8379 The value of @var{variable} when @command{configure} was launched is
8380 saved in the cache, including if it was not specified on the command
8381 line but via the environment.  Indeed, while @command{configure} can
8382 notice the definition of @code{CC} in @samp{./configure CC=bizarre-cc},
8383 it is impossible to notice it in @samp{CC=bizarre-cc ./configure},
8384 which, unfortunately, is what most users do.
8386 We emphasize that it is the @emph{initial} value of @var{variable} which
8387 is saved, not that found during the execution of @command{configure}.
8388 Indeed, specifying @samp{./configure FOO=foo} and letting
8389 @samp{./configure} guess that @code{FOO} is @code{foo} can be two
8390 different things.
8392 @item
8393 @var{variable} is checked for consistency between two
8394 @command{configure} runs.  For instance:
8396 @example
8397 $ @kbd{./configure --silent --config-cache}
8398 $ @kbd{CC=cc ./configure --silent --config-cache}
8399 configure: error: `CC' was not set in the previous run
8400 configure: error: changes in the environment can compromise \
8401 the build
8402 configure: error: run `make distclean' and/or \
8403 `rm config.cache' and start over
8404 @end example
8406 @noindent
8407 and similarly if the variable is unset, or if its content is changed.
8410 @item
8411 @var{variable} is kept during automatic reconfiguration
8412 (@pxref{config.status Invocation}) as if it had been passed as a command
8413 line argument, including when no cache is used:
8415 @example
8416 $ @kbd{CC=/usr/bin/cc ./configure undeclared_var=raboof --silent}
8417 $ @kbd{./config.status --recheck}
8418 running CONFIG_SHELL=/bin/sh /bin/sh ./configure undeclared_var=raboof \
8419   CC=/usr/bin/cc  --no-create --no-recursion
8420 @end example
8421 @end itemize
8422 @end defmac
8424 @node Special Chars in Variables
8425 @section Special Characters in Output Variables
8426 @cindex Output variables, special characters in
8428 Many output variables are intended to be evaluated both by
8429 @command{make} and by the shell.  Some characters are expanded
8430 differently in these two contexts, so to avoid confusion these
8431 variables' values should not contain any of the following characters:
8433 @example
8434 " # $ & ' ( ) * ; < > ? [ \ ^ ` |
8435 @end example
8437 Also, these variables' values should neither contain newlines, nor start
8438 with @samp{~}, nor contain white space or @samp{:} immediately followed
8439 by @samp{~}.  The values can contain nonempty sequences of white space
8440 characters like tabs and spaces, but each such sequence might
8441 arbitrarily be replaced by a single space during substitution.
8443 These restrictions apply both to the values that @command{configure}
8444 computes, and to the values set directly by the user.  For example, the
8445 following invocations of @command{configure} are problematic, since they
8446 attempt to use special characters within @code{CPPFLAGS} and white space
8447 within @code{$(srcdir)}:
8449 @example
8450 CPPFLAGS='-DOUCH="&\"#$*?"' '../My Source/ouch-1.0/configure'
8452 '../My Source/ouch-1.0/configure' CPPFLAGS='-DOUCH="&\"#$*?"'
8453 @end example
8455 @node Caching Results
8456 @section Caching Results
8457 @cindex Cache
8459 To avoid checking for the same features repeatedly in various
8460 @command{configure} scripts (or in repeated runs of one script),
8461 @command{configure} can optionally save the results of many checks in a
8462 @dfn{cache file} (@pxref{Cache Files}).  If a @command{configure} script
8463 runs with caching enabled and finds a cache file, it reads the results
8464 of previous runs from the cache and avoids rerunning those checks.  As a
8465 result, @command{configure} can then run much faster than if it had to
8466 perform all of the checks every time.
8468 @defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it})
8469 @acindex{CACHE_VAL}
8470 Ensure that the results of the check identified by @var{cache-id} are
8471 available.  If the results of the check were in the cache file that was
8472 read, and @command{configure} was not given the @option{--quiet} or
8473 @option{--silent} option, print a message saying that the result was
8474 cached; otherwise, run the shell commands @var{commands-to-set-it}.  If
8475 the shell commands are run to determine the value, the value is
8476 saved in the cache file just before @command{configure} creates its output
8477 files.  @xref{Cache Variable Names}, for how to choose the name of the
8478 @var{cache-id} variable.
8480 The @var{commands-to-set-it} @emph{must have no side effects} except for
8481 setting the variable @var{cache-id}, see below.
8482 @end defmac
8484 @defmac AC_CACHE_CHECK (@var{message}, @var{cache-id}, @var{commands-to-set-it})
8485 @acindex{CACHE_CHECK}
8486 A wrapper for @code{AC_CACHE_VAL} that takes care of printing the
8487 messages.  This macro provides a convenient shorthand for the most
8488 common way to use these macros.  It calls @code{AC_MSG_CHECKING} for
8489 @var{message}, then @code{AC_CACHE_VAL} with the @var{cache-id} and
8490 @var{commands} arguments, and @code{AC_MSG_RESULT} with @var{cache-id}.
8492 The @var{commands-to-set-it} @emph{must have no side effects} except for
8493 setting the variable @var{cache-id}, see below.
8494 @end defmac
8496 @defmac AC_CACHE_CHECK_INT (@var{message}, @var{cache-id}, @var{expression}, @dvar{includes, default-includes}, @ovar{action-if-fails})
8497 @acindex{CACHE_CHECK_INT}
8498 This is a convenience macro for invoking @code{AC_COMPUTE_INT} to store
8499 into @var{cache-id} the value of the integer @var{expression}.
8501 This macro also checks whether the result is cached,
8502 and reports the test on the standard output
8503 with @code{AC_MSG_CHECKING} (which prints @var{message}) and
8504 @code{AC_MSG_RESULT}.
8506 Execute @var{action-if-fails} if the value cannot be determined correctly.
8507 Commands in @var{action-if-fails} must have no side effects
8508 except for possibly setting the variable @var{cache-id}.
8509 @xref{Caching Results}, for more information.
8510 @end defmac
8512 It is common to find buggy macros using @code{AC_CACHE_VAL} or
8513 @code{AC_CACHE_CHECK}, because people are tempted to call
8514 @code{AC_DEFINE} in the @var{commands-to-set-it}.  Instead, the code that
8515 @emph{follows} the call to @code{AC_CACHE_VAL} should call
8516 @code{AC_DEFINE}, by examining the value of the cache variable.  For
8517 instance, the following macro is broken:
8519 @example
8520 @group
8521 AC_DEFUN([AC_SHELL_TRUE],
8522 [AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
8523                 [ac_cv_shell_true_works=no
8524                  (true) 2>/dev/null && ac_cv_shell_true_works=yes
8525                  if test "$ac_cv_shell_true_works" = yes; then
8526                    AC_DEFINE([TRUE_WORKS], [1],
8527                              [Define if `true(1)' works properly.])
8528                  fi])
8530 @end group
8531 @end example
8533 @noindent
8534 This fails if the cache is enabled: the second time this macro is run,
8535 @code{TRUE_WORKS} @emph{will not be defined}.  The proper implementation
8538 @example
8539 @group
8540 AC_DEFUN([AC_SHELL_TRUE],
8541 [AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
8542                 [ac_cv_shell_true_works=no
8543                  (true) 2>/dev/null && ac_cv_shell_true_works=yes])
8544  if test "$ac_cv_shell_true_works" = yes; then
8545    AC_DEFINE([TRUE_WORKS], [1],
8546              [Define if `true(1)' works properly.])
8547  fi
8549 @end group
8550 @end example
8552 Also, @var{commands-to-set-it} should not print any messages, for
8553 example with @code{AC_MSG_CHECKING}; do that before calling
8554 @code{AC_CACHE_VAL}, so the messages are printed regardless of whether
8555 the results of the check are retrieved from the cache or determined by
8556 running the shell commands.
8558 @menu
8559 * Cache Variable Names::        Shell variables used in caches
8560 * Cache Files::                 Files @command{configure} uses for caching
8561 * Cache Checkpointing::         Loading and saving the cache file
8562 @end menu
8564 @node Cache Variable Names
8565 @subsection Cache Variable Names
8566 @cindex Cache variable
8568 The names of cache variables should have the following format:
8570 @example
8571 @var{package-prefix}_cv_@var{value-type}_@var{specific-value}_@ovar{additional-options}
8572 @end example
8574 @noindent
8575 for example, @samp{ac_cv_header_stat_broken} or
8576 @samp{ac_cv_prog_gcc_traditional}.  The parts of the variable name are:
8578 @table @asis
8579 @item @var{package-prefix}
8580 An abbreviation for your package or organization; the same prefix you
8581 begin local Autoconf macros with, except lowercase by convention.
8582 For cache values used by the distributed Autoconf macros, this value is
8583 @samp{ac}.
8585 @item @code{_cv_}
8586 Indicates that this shell variable is a cache value.  This string
8587 @emph{must} be present in the variable name, including the leading
8588 underscore.
8590 @item @var{value-type}
8591 A convention for classifying cache values, to produce a rational naming
8592 system.  The values used in Autoconf are listed in @ref{Macro Names}.
8594 @item @var{specific-value}
8595 Which member of the class of cache values this test applies to.
8596 For example, which function (@samp{alloca}), program (@samp{gcc}), or
8597 output variable (@samp{INSTALL}).
8599 @item @var{additional-options}
8600 Any particular behavior of the specific member that this test applies to.
8601 For example, @samp{broken} or @samp{set}.  This part of the name may
8602 be omitted if it does not apply.
8603 @end table
8605 The values assigned to cache variables may not contain newlines.
8606 Usually, their values are Boolean (@samp{yes} or @samp{no}) or the
8607 names of files or functions; so this is not an important restriction.
8609 @node Cache Files
8610 @subsection Cache Files
8612 A cache file is a shell script that caches the results of configure
8613 tests run on one system so they can be shared between configure scripts
8614 and configure runs.  It is not useful on other systems.  If its contents
8615 are invalid for some reason, the user may delete or edit it.
8617 By default, @command{configure} uses no cache file,
8618 to avoid problems caused by accidental
8619 use of stale cache files.
8621 To enable caching, @command{configure} accepts @option{--config-cache} (or
8622 @option{-C}) to cache results in the file @file{config.cache}.
8623 Alternatively, @option{--cache-file=@var{file}} specifies that
8624 @var{file} be the cache file.  The cache file is created if it does not
8625 exist already.  When @command{configure} calls @command{configure} scripts in
8626 subdirectories, it uses the @option{--cache-file} argument so that they
8627 share the same cache.  @xref{Subdirectories}, for information on
8628 configuring subdirectories with the @code{AC_CONFIG_SUBDIRS} macro.
8630 @file{config.status} only pays attention to the cache file if it is
8631 given the @option{--recheck} option, which makes it rerun
8632 @command{configure}.
8634 It is wrong to try to distribute cache files for particular system types.
8635 There is too much room for error in doing that, and too much
8636 administrative overhead in maintaining them.  For any features that
8637 can't be guessed automatically, use the standard method of the canonical
8638 system type and linking files (@pxref{Manual Configuration}).
8640 The site initialization script can specify a site-wide cache file to
8641 use, instead of the usual per-program cache.  In this case, the cache
8642 file gradually accumulates information whenever someone runs a new
8643 @command{configure} script.  (Running @command{configure} merges the new cache
8644 results with the existing cache file.)  This may cause problems,
8645 however, if the system configuration (e.g., the installed libraries or
8646 compilers) changes and the stale cache file is not deleted.
8648 @node Cache Checkpointing
8649 @subsection Cache Checkpointing
8651 If your configure script, or a macro called from @file{configure.ac}, happens
8652 to abort the configure process, it may be useful to checkpoint the cache
8653 a few times at key points using @code{AC_CACHE_SAVE}.  Doing so
8654 reduces the amount of time it takes to rerun the configure script with
8655 (hopefully) the error that caused the previous abort corrected.
8657 @c FIXME: Do we really want to document this guy?
8658 @defmac AC_CACHE_LOAD
8659 @acindex{CACHE_LOAD}
8660 Loads values from existing cache file, or creates a new cache file if a
8661 cache file is not found.  Called automatically from @code{AC_INIT}.
8662 @end defmac
8664 @defmac AC_CACHE_SAVE
8665 @acindex{CACHE_SAVE}
8666 Flushes all cached values to the cache file.  Called automatically from
8667 @code{AC_OUTPUT}, but it can be quite useful to call
8668 @code{AC_CACHE_SAVE} at key points in @file{configure.ac}.
8669 @end defmac
8671 For instance:
8673 @example
8674 @r{ @dots{} AC_INIT, etc. @dots{}}
8675 @group
8676 # Checks for programs.
8677 AC_PROG_CC
8678 AC_PROG_AWK
8679 @r{ @dots{} more program checks @dots{}}
8680 AC_CACHE_SAVE
8681 @end group
8683 @group
8684 # Checks for libraries.
8685 AC_CHECK_LIB([nsl], [gethostbyname])
8686 AC_CHECK_LIB([socket], [connect])
8687 @r{ @dots{} more lib checks @dots{}}
8688 AC_CACHE_SAVE
8689 @end group
8691 @group
8692 # Might abort@dots{}
8693 AM_PATH_GTK([1.0.2], [], [AC_MSG_ERROR([GTK not in path])])
8694 AM_PATH_GTKMM([0.9.5], [], [AC_MSG_ERROR([GTK not in path])])
8695 @end group
8696 @r{ @dots{} AC_OUTPUT, etc. @dots{}}
8697 @end example
8699 @node Printing Messages
8700 @section Printing Messages
8701 @cindex Messages, from @command{configure}
8703 @command{configure} scripts need to give users running them several kinds
8704 of information.  The following macros print messages in ways appropriate
8705 for each kind.  The arguments to all of them get enclosed in shell
8706 double quotes, so the shell performs variable and back-quote
8707 substitution on them.
8709 These macros are all wrappers around the @command{echo} shell command.
8710 They direct output to the appropriate file descriptor (@pxref{File
8711 Descriptor Macros}).
8712 @command{configure} scripts should rarely need to run @command{echo} directly
8713 to print messages for the user.  Using these macros makes it easy to
8714 change how and when each kind of message is printed; such changes need
8715 only be made to the macro definitions and all the callers change
8716 automatically.
8718 To diagnose static issues, i.e., when @command{autoconf} is run, see
8719 @ref{Reporting Messages}.
8721 @defmac AC_MSG_CHECKING (@var{feature-description})
8722 @acindex{MSG_CHECKING}
8723 Notify the user that @command{configure} is checking for a particular
8724 feature.  This macro prints a message that starts with @samp{checking }
8725 and ends with @samp{...} and no newline.  It must be followed by a call
8726 to @code{AC_MSG_RESULT} to print the result of the check and the
8727 newline.  The @var{feature-description} should be something like
8728 @samp{whether the Fortran compiler accepts C++ comments} or @samp{for
8729 c89}.
8731 This macro prints nothing if @command{configure} is run with the
8732 @option{--quiet} or @option{--silent} option.
8733 @end defmac
8735 @defmac AC_MSG_RESULT (@var{result-description})
8736 @acindex{MSG_RESULT}
8737 Notify the user of the results of a check.  @var{result-description} is
8738 almost always the value of the cache variable for the check, typically
8739 @samp{yes}, @samp{no}, or a file name.  This macro should follow a call
8740 to @code{AC_MSG_CHECKING}, and the @var{result-description} should be
8741 the completion of the message printed by the call to
8742 @code{AC_MSG_CHECKING}.
8744 This macro prints nothing if @command{configure} is run with the
8745 @option{--quiet} or @option{--silent} option.
8746 @end defmac
8748 @defmac AC_MSG_NOTICE (@var{message})
8749 @acindex{MSG_NOTICE}
8750 Deliver the @var{message} to the user.  It is useful mainly to print a
8751 general description of the overall purpose of a group of feature checks,
8752 e.g.,
8754 @example
8755 AC_MSG_NOTICE([checking if stack overflow is detectable])
8756 @end example
8758 This macro prints nothing if @command{configure} is run with the
8759 @option{--quiet} or @option{--silent} option.
8760 @end defmac
8762 @defmac AC_MSG_ERROR (@var{error-description}, @ovar{exit-status})
8763 @acindex{MSG_ERROR}
8764 Notify the user of an error that prevents @command{configure} from
8765 completing.  This macro prints an error message to the standard error
8766 output and exits @command{configure} with @var{exit-status} (1 by default).
8767 @var{error-description} should be something like @samp{invalid value
8768 $HOME for \$HOME}.
8770 The @var{error-description} should start with a lower-case letter, and
8771 ``cannot'' is preferred to ``can't''.
8772 @end defmac
8774 @defmac AC_MSG_FAILURE (@var{error-description}, @ovar{exit-status})
8775 @acindex{MSG_FAILURE}
8776 This @code{AC_MSG_ERROR} wrapper notifies the user of an error that
8777 prevents @command{configure} from completing @emph{and} that additional
8778 details are provided in @file{config.log}.  This is typically used when
8779 abnormal results are found during a compilation.
8780 @end defmac
8782 @defmac AC_MSG_WARN (@var{problem-description})
8783 @acindex{MSG_WARN}
8784 Notify the @command{configure} user of a possible problem.  This macro
8785 prints the message to the standard error output; @command{configure}
8786 continues running afterward, so macros that call @code{AC_MSG_WARN} should
8787 provide a default (back-up) behavior for the situations they warn about.
8788 @var{problem-description} should be something like @samp{ln -s seems to
8789 make hard links}.
8790 @end defmac
8794 @c ====================================================== Programming in M4.
8796 @node Programming in M4
8797 @chapter Programming in M4
8798 @cindex M4
8800 Autoconf is written on top of two layers: @dfn{M4sugar}, which provides
8801 convenient macros for pure M4 programming, and @dfn{M4sh}, which
8802 provides macros dedicated to shell script generation.
8804 As of this version of Autoconf, these two layers are still experimental,
8805 and their interface might change in the future.  As a matter of fact,
8806 @emph{anything that is not documented must not be used}.
8808 @menu
8809 * M4 Quotation::                Protecting macros from unwanted expansion
8810 * Using autom4te::              The Autoconf executables backbone
8811 * Programming in M4sugar::      Convenient pure M4 macros
8812 * Programming in M4sh::         Common shell Constructs
8813 * File Descriptor Macros::      File descriptor macros for input and output
8814 @end menu
8816 @node M4 Quotation
8817 @section M4 Quotation
8818 @cindex M4 quotation
8819 @cindex quotation
8821 @c FIXME: Grmph, yet another quoting myth: quotation has *never*
8822 @c prevented `expansion' of $1.  Unless it refers to the expansion
8823 @c of the value of $1?  Anyway, we need a rewrite here@enddots{}
8825 The most common problem with existing macros is an improper quotation.
8826 This section, which users of Autoconf can skip, but which macro writers
8827 @emph{must} read, first justifies the quotation scheme that was chosen
8828 for Autoconf and then ends with a rule of thumb.  Understanding the
8829 former helps one to follow the latter.
8831 @menu
8832 * Active Characters::           Characters that change the behavior of M4
8833 * One Macro Call::              Quotation and one macro call
8834 * Quotation and Nested Macros::  Macros calling macros
8835 * Changequote is Evil::         Worse than INTERCAL: M4 + changequote
8836 * Quadrigraphs::                Another way to escape special characters
8837 * Quotation Rule Of Thumb::     One parenthesis, one quote
8838 @end menu
8840 @node Active Characters
8841 @subsection Active Characters
8843 To fully understand where proper quotation is important, you first need
8844 to know what the special characters are in Autoconf: @samp{#} introduces
8845 a comment inside which no macro expansion is performed, @samp{,}
8846 separates arguments, @samp{[} and @samp{]} are the quotes themselves,
8847 and finally @samp{(} and @samp{)} (which M4 tries to match by
8848 pairs).
8850 In order to understand the delicate case of macro calls, we first have
8851 to present some obvious failures.  Below they are ``obvious-ified'',
8852 but when you find them in real life, they are usually in disguise.
8854 Comments, introduced by a hash and running up to the newline, are opaque
8855 tokens to the top level: active characters are turned off, and there is
8856 no macro expansion:
8858 @example
8859 # define([def], ine)
8860 @result{}# define([def], ine)
8861 @end example
8863 Each time there can be a macro expansion, there is a quotation
8864 expansion, i.e., one level of quotes is stripped:
8866 @example
8867 int tab[10];
8868 @result{}int tab10;
8869 [int tab[10];]
8870 @result{}int tab[10];
8871 @end example
8873 Without this in mind, the reader might try hopelessly to use her macro
8874 @code{array}:
8876 @example
8877 define([array], [int tab[10];])
8878 array
8879 @result{}int tab10;
8880 [array]
8881 @result{}array
8882 @end example
8884 @noindent
8885 How can you correctly output the intended results@footnote{Using
8886 @code{defn}.}?
8889 @node One Macro Call
8890 @subsection One Macro Call
8892 Let's proceed on the interaction between active characters and macros
8893 with this small macro, which just returns its first argument:
8895 @example
8896 define([car], [$1])
8897 @end example
8899 @noindent
8900 The two pairs of quotes above are not part of the arguments of
8901 @code{define}; rather, they are understood by the top level when it
8902 tries to find the arguments of @code{define}.  Therefore, assuming
8903 @code{car} is not already defined, it is equivalent to write:
8905 @example
8906 define(car, $1)
8907 @end example
8909 @noindent
8910 But, while it is acceptable for a @file{configure.ac} to avoid unnecessary
8911 quotes, it is bad practice for Autoconf macros which must both be more
8912 robust and also advocate perfect style.
8914 At the top level, there are only two possibilities: either you
8915 quote or you don't:
8917 @example
8918 car(foo, bar, baz)
8919 @result{}foo
8920 [car(foo, bar, baz)]
8921 @result{}car(foo, bar, baz)
8922 @end example
8924 Let's pay attention to the special characters:
8926 @example
8927 car(#)
8928 @error{}EOF in argument list
8929 @end example
8931 The closing parenthesis is hidden in the comment; with a hypothetical
8932 quoting, the top level understood it this way:
8934 @example
8935 car([#)]
8936 @end example
8938 @noindent
8939 Proper quotation, of course, fixes the problem:
8941 @example
8942 car([#])
8943 @result{}#
8944 @end example
8946 Here are more examples:
8948 @example
8949 car(foo, bar)
8950 @result{}foo
8951 car([foo, bar])
8952 @result{}foo, bar
8953 car((foo, bar))
8954 @result{}(foo, bar)
8955 car([(foo], [bar)])
8956 @result{}(foo
8957 define([a], [b])
8958 @result{}
8959 car(a)
8960 @result{}b
8961 car([a])
8962 @result{}b
8963 car([[a]])
8964 @result{}a
8965 car([[[a]]])
8966 @result{}[a]
8967 @end example
8969 With this in mind, we can explore the cases where macros invoke
8970 macros@enddots{}
8973 @node Quotation and Nested Macros
8974 @subsection Quotation and Nested Macros
8976 The examples below use the following macros:
8978 @example
8979 define([car], [$1])
8980 define([active], [ACT, IVE])
8981 define([array], [int tab[10]])
8982 @end example
8984 Each additional embedded macro call introduces other possible
8985 interesting quotations:
8987 @example
8988 car(active)
8989 @result{}ACT
8990 car([active])
8991 @result{}ACT, IVE
8992 car([[active]])
8993 @result{}active
8994 @end example
8996 In the first case, the top level looks for the arguments of @code{car},
8997 and finds @samp{active}.  Because M4 evaluates its arguments
8998 before applying the macro, @samp{active} is expanded, which results in:
9000 @example
9001 car(ACT, IVE)
9002 @result{}ACT
9003 @end example
9005 @noindent
9006 In the second case, the top level gives @samp{active} as first and only
9007 argument of @code{car}, which results in:
9009 @example
9010 active
9011 @result{}ACT, IVE
9012 @end example
9014 @noindent
9015 i.e., the argument is evaluated @emph{after} the macro that invokes it.
9016 In the third case, @code{car} receives @samp{[active]}, which results in:
9018 @example
9019 [active]
9020 @result{}active
9021 @end example
9023 @noindent
9024 exactly as we already saw above.
9026 The example above, applied to a more realistic example, gives:
9028 @example
9029 car(int tab[10];)
9030 @result{}int tab10;
9031 car([int tab[10];])
9032 @result{}int tab10;
9033 car([[int tab[10];]])
9034 @result{}int tab[10];
9035 @end example
9037 @noindent
9038 Huh?  The first case is easily understood, but why is the second wrong,
9039 and the third right?  To understand that, you must know that after
9040 M4 expands a macro, the resulting text is immediately subjected
9041 to macro expansion and quote removal.  This means that the quote removal
9042 occurs twice---first before the argument is passed to the @code{car}
9043 macro, and second after the @code{car} macro expands to the first
9044 argument.
9046 As the author of the Autoconf macro @code{car}, you then consider it to
9047 be incorrect that your users have to double-quote the arguments of
9048 @code{car}, so you ``fix'' your macro.  Let's call it @code{qar} for
9049 quoted car:
9051 @example
9052 define([qar], [[$1]])
9053 @end example
9055 @noindent
9056 and check that @code{qar} is properly fixed:
9058 @example
9059 qar([int tab[10];])
9060 @result{}int tab[10];
9061 @end example
9063 @noindent
9064 Ahhh!  That's much better.
9066 But note what you've done: now that the arguments are literal strings,
9067 if the user wants to use the results of expansions as arguments, she has
9068 to use an @emph{unquoted} macro call:
9070 @example
9071 qar(active)
9072 @result{}ACT
9073 @end example
9075 @noindent
9076 where she wanted to reproduce what she used to do with @code{car}:
9078 @example
9079 car([active])
9080 @result{}ACT, IVE
9081 @end example
9083 @noindent
9084 Worse yet: she wants to use a macro that produces a set of @code{cpp}
9085 macros:
9087 @example
9088 define([my_includes], [#include <stdio.h>])
9089 car([my_includes])
9090 @result{}#include <stdio.h>
9091 qar(my_includes)
9092 @error{}EOF in argument list
9093 @end example
9095 This macro, @code{qar}, because it double quotes its arguments, forces
9096 its users to leave their macro calls unquoted, which is dangerous.
9097 Commas and other active symbols are interpreted by M4 before
9098 they are given to the macro, often not in the way the users expect.
9099 Also, because @code{qar} behaves differently from the other macros,
9100 it's an exception that should be avoided in Autoconf.
9102 @node Changequote is Evil
9103 @subsection @code{changequote} is Evil
9104 @cindex @code{changequote}
9106 The temptation is often high to bypass proper quotation, in particular
9107 when it's late at night.  Then, many experienced Autoconf hackers
9108 finally surrender to the dark side of the force and use the ultimate
9109 weapon: @code{changequote}.
9111 The M4 builtin @code{changequote} belongs to a set of primitives that
9112 allow one to adjust the syntax of the language to adjust it to one's
9113 needs.  For instance, by default M4 uses @samp{`} and @samp{'} as
9114 quotes, but in the context of shell programming (and actually of most
9115 programming languages), that's about the worst choice one can make:
9116 because of strings and back-quoted expressions in shell code (such as
9117 @samp{'this'} and @samp{`that`}), because of literal characters in usual
9118 programming languages (as in @samp{'0'}), there are many unbalanced
9119 @samp{`} and @samp{'}.  Proper M4 quotation then becomes a nightmare, if
9120 not impossible.  In order to make M4 useful in such a context, its
9121 designers have equipped it with @code{changequote}, which makes it
9122 possible to choose another pair of quotes.  M4sugar, M4sh, Autoconf, and
9123 Autotest all have chosen to use @samp{[} and @samp{]}.  Not especially
9124 because they are unlikely characters, but @emph{because they are
9125 characters unlikely to be unbalanced}.
9127 There are other magic primitives, such as @code{changecom} to specify
9128 what syntactic forms are comments (it is common to see
9129 @samp{changecom(<!--, -->)} when M4 is used to produce HTML pages),
9130 @code{changeword} and @code{changesyntax} to change other syntactic
9131 details (such as the character to denote the @var{n}th argument, @samp{$} by
9132 default, the parenthesis around arguments, etc.).
9134 These primitives are really meant to make M4 more useful for specific
9135 domains: they should be considered like command line options:
9136 @option{--quotes}, @option{--comments}, @option{--words}, and
9137 @option{--syntax}.  Nevertheless, they are implemented as M4 builtins, as
9138 it makes M4 libraries self contained (no need for additional options).
9140 There lies the problem@enddots{}
9142 @sp 1
9144 The problem is that it is then tempting to use them in the middle of an
9145 M4 script, as opposed to its initialization.  This, if not carefully
9146 thought out, can lead to disastrous effects: @emph{you are changing the
9147 language in the middle of the execution}.  Changing and restoring the
9148 syntax is often not enough: if you happened to invoke macros in between,
9149 these macros are lost, as the current syntax is probably not
9150 the one they were implemented with.
9152 @c FIXME: I've been looking for a short, real case example, but I
9153 @c lost them all :(
9156 @node Quadrigraphs
9157 @subsection Quadrigraphs
9158 @cindex quadrigraphs
9159 @cindex @samp{@@S|@@}
9160 @cindex @samp{@@&t@@}
9161 @c Info cannot handle `:' in index entries.
9162 @c @cindex @samp{@@<:@@}
9163 @c @cindex @samp{@@:>@@}
9164 @c @cindex @samp{@@%:@@}
9166 When writing an Autoconf macro you may occasionally need to generate
9167 special characters that are difficult to express with the standard
9168 Autoconf quoting rules.  For example, you may need to output the regular
9169 expression @samp{[^[]}, which matches any character other than @samp{[}.
9170 This expression contains unbalanced brackets so it cannot be put easily
9171 into an M4 macro.
9173 You can work around this problem by using one of the following
9174 @dfn{quadrigraphs}:
9176 @table @samp
9177 @item @@<:@@
9178 @samp{[}
9179 @item @@:>@@
9180 @samp{]}
9181 @item @@S|@@
9182 @samp{$}
9183 @item @@%:@@
9184 @samp{#}
9185 @item @@&t@@
9186 Expands to nothing.
9187 @end table
9189 Quadrigraphs are replaced at a late stage of the translation process,
9190 after @command{m4} is run, so they do not get in the way of M4 quoting.
9191 For example, the string @samp{^@@<:@@}, independently of its quotation,
9192 appears as @samp{^[} in the output.
9194 The empty quadrigraph can be used:
9196 @itemize @minus
9197 @item to mark trailing spaces explicitly
9199 Trailing spaces are smashed by @command{autom4te}.  This is a feature.
9201 @item to produce other quadrigraphs
9203 For instance @samp{@@<@@&t@@:@@} produces @samp{@@<:@@}.
9205 @item to escape @emph{occurrences} of forbidden patterns
9207 For instance you might want to mention @code{AC_FOO} in a comment, while
9208 still being sure that @command{autom4te} still catches unexpanded
9209 @samp{AC_*}.  Then write @samp{AC@@&t@@_FOO}.
9210 @end itemize
9212 The name @samp{@@&t@@} was suggested by Paul Eggert:
9214 @quotation
9215 I should give some credit to the @samp{@@&t@@} pun.  The @samp{&} is my
9216 own invention, but the @samp{t} came from the source code of the
9217 @sc{algol68c} compiler, written by Steve Bourne (of Bourne shell fame),
9218 and which used @samp{mt} to denote the empty string.  In C, it would
9219 have looked like something like:
9221 @example
9222 char const mt[] = "";
9223 @end example
9225 @noindent
9226 but of course the source code was written in Algol 68.
9228 I don't know where he got @samp{mt} from: it could have been his own
9229 invention, and I suppose it could have been a common pun around the
9230 Cambridge University computer lab at the time.
9231 @end quotation
9233 @node Quotation Rule Of Thumb
9234 @subsection Quotation Rule Of Thumb
9236 To conclude, the quotation rule of thumb is:
9238 @center @emph{One pair of quotes per pair of parentheses.}
9240 Never over-quote, never under-quote, in particular in the definition of
9241 macros.  In the few places where the macros need to use brackets
9242 (usually in C program text or regular expressions), properly quote
9243 @emph{the arguments}!
9245 It is common to read Autoconf programs with snippets like:
9247 @example
9248 AC_TRY_LINK(
9249 changequote(<<, >>)dnl
9250 <<#include <time.h>
9251 #ifndef tzname /* For SGI.  */
9252 extern char *tzname[]; /* RS6000 and others reject char **tzname.  */
9253 #endif>>,
9254 changequote([, ])dnl
9255 [atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)
9256 @end example
9258 @noindent
9259 which is incredibly useless since @code{AC_TRY_LINK} is @emph{already}
9260 double quoting, so you just need:
9262 @example
9263 AC_TRY_LINK(
9264 [#include <time.h>
9265 #ifndef tzname /* For SGI.  */
9266 extern char *tzname[]; /* RS6000 and others reject char **tzname.  */
9267 #endif],
9268             [atoi (*tzname);],
9269             [ac_cv_var_tzname=yes],
9270             [ac_cv_var_tzname=no])
9271 @end example
9273 @noindent
9274 The M4-fluent reader might note that these two examples are rigorously
9275 equivalent, since M4 swallows both the @samp{changequote(<<, >>)}
9276 and @samp{<<} @samp{>>} when it @dfn{collects} the arguments: these
9277 quotes are not part of the arguments!
9279 Simplified, the example above is just doing this:
9281 @example
9282 changequote(<<, >>)dnl
9283 <<[]>>
9284 changequote([, ])dnl
9285 @end example
9287 @noindent
9288 instead of simply:
9290 @example
9291 [[]]
9292 @end example
9294 With macros that do not double quote their arguments (which is the
9295 rule), double-quote the (risky) literals:
9297 @example
9298 AC_LINK_IFELSE([AC_LANG_PROGRAM(
9299 [[#include <time.h>
9300 #ifndef tzname /* For SGI.  */
9301 extern char *tzname[]; /* RS6000 and others reject char **tzname.  */
9302 #endif]],
9303                                 [atoi (*tzname);])],
9304                [ac_cv_var_tzname=yes],
9305                [ac_cv_var_tzname=no])
9306 @end example
9308 Please note that the macro @code{AC_TRY_LINK} is obsolete, so you really
9309 should be using @code{AC_LINK_IFELSE} instead.
9311 @xref{Quadrigraphs}, for what to do if you run into a hopeless case
9312 where quoting does not suffice.
9314 When you create a @command{configure} script using newly written macros,
9315 examine it carefully to check whether you need to add more quotes in
9316 your macros.  If one or more words have disappeared in the M4
9317 output, you need more quotes.  When in doubt, quote.
9319 However, it's also possible to put on too many layers of quotes.  If
9320 this happens, the resulting @command{configure} script may contain
9321 unexpanded macros.  The @command{autoconf} program checks for this problem
9322 by looking for the string @samp{AC_} in @file{configure}.  However, this
9323 heuristic does not work in general: for example, it does not catch
9324 overquoting in @code{AC_DEFINE} descriptions.
9327 @c ---------------------------------------- Using autom4te
9329 @node Using autom4te
9330 @section Using @command{autom4te}
9332 The Autoconf suite, including M4sugar, M4sh, and Autotest, in addition
9333 to Autoconf per se, heavily rely on M4.  All these different uses
9334 revealed common needs factored into a layer over M4:
9335 @command{autom4te}@footnote{
9337 Yet another great name from Lars J. Aas.
9341 @command{autom4te} is a preprocessor that is like @command{m4}.
9342 It supports M4 extensions designed for use in tools like Autoconf.
9344 @menu
9345 * autom4te Invocation::         A @acronym{GNU} M4 wrapper
9346 * Customizing autom4te::        Customizing the Autoconf package
9347 @end menu
9349 @node autom4te Invocation
9350 @subsection Invoking @command{autom4te}
9352 The command line arguments are modeled after M4's:
9354 @example
9355 autom4te @var{options} @var{files}
9356 @end example
9358 @noindent
9359 @evindex M4
9360 where the @var{files} are directly passed to @command{m4}.  By default,
9361 @acronym{GNU} M4 is found during configuration, but the environment
9362 variable
9363 @env{M4} can be set to tell @command{autom4te} where to look.  In addition
9364 to the regular expansion, it handles the replacement of the quadrigraphs
9365 (@pxref{Quadrigraphs}), and of @samp{__oline__}, the current line in the
9366 output.  It supports an extended syntax for the @var{files}:
9368 @table @file
9369 @item @var{file}.m4f
9370 This file is an M4 frozen file.  Note that @emph{all the previous files
9371 are ignored}.  See the option @option{--melt} for the rationale.
9373 @item @var{file}?
9374 If found in the library path, the @var{file} is included for expansion,
9375 otherwise it is ignored instead of triggering a failure.
9376 @end table
9378 @sp 1
9380 Of course, it supports the Autoconf common subset of options:
9382 @table @option
9383 @item --help
9384 @itemx -h
9385 Print a summary of the command line options and exit.
9387 @item --version
9388 @itemx -V
9389 Print the version number of Autoconf and exit.
9391 @item --verbose
9392 @itemx -v
9393 Report processing steps.
9395 @item --debug
9396 @itemx -d
9397 Don't remove the temporary files and be even more verbose.
9399 @item --include=@var{dir}
9400 @itemx -I @var{dir}
9401 Also look for input files in @var{dir}.  Multiple invocations
9402 accumulate.
9404 @item --output=@var{file}
9405 @itemx -o @var{file}
9406 Save output (script or trace) to @var{file}.  The file @option{-} stands
9407 for the standard output.
9408 @end table
9410 @sp 1
9412 As an extension of @command{m4}, it includes the following options:
9414 @table @option
9415 @item --warnings=@var{category}
9416 @itemx -W @var{category}
9417 @evindex WARNINGS
9418 @c FIXME: Point to the M4sugar macros, not Autoconf's.
9419 Report the warnings related to @var{category} (which can actually be a
9420 comma separated list).  @xref{Reporting Messages}, macro
9421 @code{AC_DIAGNOSE}, for a comprehensive list of categories.  Special
9422 values include:
9424 @table @samp
9425 @item all
9426 report all the warnings
9428 @item none
9429 report none
9431 @item error
9432 treats warnings as errors
9434 @item no-@var{category}
9435 disable warnings falling into @var{category}
9436 @end table
9438 Warnings about @samp{syntax} are enabled by default, and the environment
9439 variable @env{WARNINGS}, a comma separated list of categories, is
9440 honored.  @samp{autom4te -W @var{category}} actually
9441 behaves as if you had run:
9443 @example
9444 autom4te --warnings=syntax,$WARNINGS,@var{category}
9445 @end example
9447 @noindent
9448 For example, if you want to disable defaults and @env{WARNINGS}
9449 of @command{autom4te}, but enable the warnings about obsolete
9450 constructs, you would use @option{-W none,obsolete}.
9452 @cindex Back trace
9453 @cindex Macro invocation stack
9454 @command{autom4te} displays a back trace for errors, but not for
9455 warnings; if you want them, just pass @option{-W error}.
9457 @item --melt
9458 @itemx -M
9459 Do not use frozen files.  Any argument @code{@var{file}.m4f} is
9460 replaced by @code{@var{file}.m4}.  This helps tracing the macros which
9461 are executed only when the files are frozen, typically
9462 @code{m4_define}.  For instance, running:
9464 @example
9465 autom4te --melt 1.m4 2.m4f 3.m4 4.m4f input.m4
9466 @end example
9468 @noindent
9469 is roughly equivalent to running:
9471 @example
9472 m4 1.m4 2.m4 3.m4 4.m4 input.m4
9473 @end example
9475 @noindent
9476 while
9478 @example
9479 autom4te 1.m4 2.m4f 3.m4 4.m4f input.m4
9480 @end example
9482 @noindent
9483 is equivalent to:
9485 @example
9486 m4 --reload-state=4.m4f input.m4
9487 @end example
9489 @item --freeze
9490 @itemx -f
9491 Produce a frozen state file.  @command{autom4te} freezing is stricter
9492 than M4's: it must produce no warnings, and no output other than empty
9493 lines (a line with white space is @emph{not} empty) and comments
9494 (starting with @samp{#}).  Unlike @command{m4}'s similarly-named option,
9495 this option takes no argument:
9497 @example
9498 autom4te 1.m4 2.m4 3.m4 --freeze --output=3.m4f
9499 @end example
9501 @noindent
9502 corresponds to
9504 @example
9505 m4 1.m4 2.m4 3.m4 --freeze-state=3.m4f
9506 @end example
9508 @item --mode=@var{octal-mode}
9509 @itemx -m @var{octal-mode}
9510 Set the mode of the non-traces output to @var{octal-mode}; by default
9511 @samp{0666}.
9512 @end table
9514 @sp 1
9516 @cindex @file{autom4te.cache}
9517 As another additional feature over @command{m4}, @command{autom4te}
9518 caches its results.  @acronym{GNU} M4 is able to produce a regular
9519 output and traces at the same time.  Traces are heavily used in the
9520 @acronym{GNU} Build System: @command{autoheader} uses them to build
9521 @file{config.h.in}, @command{autoreconf} to determine what
9522 @acronym{GNU} Build System components are used, @command{automake} to
9523 ``parse'' @file{configure.ac} etc.  To avoid recomputation,
9524 traces are cached while performing regular expansion,
9525 and conversely.  This cache is (actually, the caches are) stored in
9526 the directory @file{autom4te.cache}.  @emph{It can safely be removed}
9527 at any moment (especially if for some reason @command{autom4te}
9528 considers it is trashed).
9530 @table @option
9531 @item --cache=@var{directory}
9532 @itemx -C @var{directory}
9533 Specify the name of the directory where the result should be cached.
9534 Passing an empty value disables caching.  Be sure to pass a relative
9535 file name, as for the time being, global caches are not supported.
9537 @item --no-cache
9538 Don't cache the results.
9540 @item --force
9541 @itemx -f
9542 If a cache is used, consider it obsolete (but update it anyway).
9543 @end table
9545 @sp 1
9547 Because traces are so important to the @acronym{GNU} Build System,
9548 @command{autom4te} provides high level tracing features as compared to
9549 M4, and helps exploiting the cache:
9551 @table @option
9552 @item --trace=@var{macro}[:@var{format}]
9553 @itemx -t @var{macro}[:@var{format}]
9554 Trace the invocations of @var{macro} according to the @var{format}.
9555 Multiple @option{--trace} arguments can be used to list several macros.
9556 Multiple @option{--trace} arguments for a single macro are not
9557 cumulative; instead, you should just make @var{format} as long as
9558 needed.
9560 The @var{format} is a regular string, with newlines if desired, and
9561 several special escape codes.  It defaults to @samp{$f:$l:$n:$%}.  It can
9562 use the following special escapes:
9564 @table @samp
9565 @item $$
9566 The character @samp{$}.
9568 @item $f
9569 The file name from which @var{macro} is called.
9571 @item $l
9572 The line number from which @var{macro} is called.
9574 @item $d
9575 The depth of the @var{macro} call.  This is an M4 technical detail that
9576 you probably don't want to know about.
9578 @item $n
9579 The name of the @var{macro}.
9581 @item $@var{num}
9582 The @var{num}th argument of the call to @var{macro}.
9584 @item $@@
9585 @itemx $@var{sep}@@
9586 @itemx $@{@var{separator}@}@@
9587 All the arguments passed to @var{macro}, separated by the character
9588 @var{sep} or the string @var{separator} (@samp{,} by default).  Each
9589 argument is quoted, i.e., enclosed in a pair of square brackets.
9591 @item $*
9592 @itemx $@var{sep}*
9593 @itemx $@{@var{separator}@}*
9594 As above, but the arguments are not quoted.
9596 @item $%
9597 @itemx $@var{sep}%
9598 @itemx $@{@var{separator}@}%
9599 As above, but the arguments are not quoted, all new line characters in
9600 the arguments are smashed, and the default separator is @samp{:}.
9602 The escape @samp{$%} produces single-line trace outputs (unless you put
9603 newlines in the @samp{separator}), while @samp{$@@} and @samp{$*} do
9604 not.
9605 @end table
9607 @xref{autoconf Invocation}, for examples of trace uses.
9609 @item --preselect=@var{macro}
9610 @itemx -p @var{macro}
9611 Cache the traces of @var{macro}, but do not enable traces.  This is
9612 especially important to save CPU cycles in the future.  For instance,
9613 when invoked, @command{autoconf} preselects all the macros that
9614 @command{autoheader}, @command{automake}, @command{autoreconf}, etc.,
9615 trace, so that running @command{m4} is not needed to trace them: the
9616 cache suffices.  This results in a huge speed-up.
9617 @end table
9619 @sp 1
9621 @cindex Autom4te Library
9622 Finally, @command{autom4te} introduces the concept of @dfn{Autom4te
9623 libraries}.  They consists in a powerful yet extremely simple feature:
9624 sets of combined command line arguments:
9626 @table @option
9627 @item --language=@var{language}
9628 @itemx -l @var{language}
9629 Use the @var{language} Autom4te library.  Current languages include:
9631 @table @code
9632 @item M4sugar
9633 create M4sugar output.
9635 @item M4sh
9636 create M4sh executable shell scripts.
9638 @item Autotest
9639 create Autotest executable test suites.
9641 @item Autoconf-without-aclocal-m4
9642 create Autoconf executable configure scripts without
9643 reading @file{aclocal.m4}.
9645 @item Autoconf
9646 create Autoconf executable configure scripts.  This language inherits
9647 all the characteristics of @code{Autoconf-without-aclocal-m4} and
9648 additionally reads @file{aclocal.m4}.
9649 @end table
9651 @item --prepend-include=@var{dir}
9652 @item -B @var{dir}
9653 Prepend directory @var{dir} to the search path.  This is used to include
9654 the language-specific files before any third-party macros.
9656 @end table
9658 @cindex @file{autom4te.cfg}
9659 As an example, if Autoconf is installed in its default location,
9660 @file{/usr/local}, the command @samp{autom4te -l m4sugar foo.m4} is
9661 strictly equivalent to the command:
9663 @example
9664 autom4te --prepend-include /usr/local/share/autoconf \
9665   m4sugar/m4sugar.m4f --warnings syntax foo.m4
9666 @end example
9668 @noindent
9669 Recursive expansion applies here: the command @samp{autom4te -l m4sh foo.m4}
9670 is the same as @samp{autom4te --language M4sugar m4sugar/m4sh.m4f
9671 foo.m4}, i.e.:
9673 @example
9674 autom4te --prepend-include /usr/local/share/autoconf \
9675   m4sugar/m4sugar.m4f m4sugar/m4sh.m4f --mode 777 foo.m4
9676 @end example
9678 @noindent
9679 The definition of the languages is stored in @file{autom4te.cfg}.
9681 @node Customizing autom4te
9682 @subsection Customizing @command{autom4te}
9684 One can customize @command{autom4te} via @file{~/.autom4te.cfg} (i.e.,
9685 as found in the user home directory), and @file{./.autom4te.cfg} (i.e.,
9686 as found in the directory from which @command{autom4te} is run).  The
9687 order is first reading @file{autom4te.cfg}, then @file{~/.autom4te.cfg},
9688 then @file{./.autom4te.cfg}, and finally the command line arguments.
9690 In these text files, comments are introduced with @code{#}, and empty
9691 lines are ignored.  Customization is performed on a per-language basis,
9692 wrapped in between a @samp{begin-language: "@var{language}"},
9693 @samp{end-language: "@var{language}"} pair.
9695 Customizing a language stands for appending options (@pxref{autom4te
9696 Invocation}) to the current definition of the language.  Options, and
9697 more generally arguments, are introduced by @samp{args:
9698 @var{arguments}}.  You may use the traditional shell syntax to quote the
9699 @var{arguments}.
9701 As an example, to disable Autoconf caches (@file{autom4te.cache})
9702 globally, include the following lines in @file{~/.autom4te.cfg}:
9704 @verbatim
9705 ## ------------------ ##
9706 ## User Preferences.  ##
9707 ## ------------------ ##
9709 begin-language: "Autoconf-without-aclocal-m4"
9710 args: --no-cache
9711 end-language: "Autoconf-without-aclocal-m4"
9712 @end verbatim
9715 @node Programming in M4sugar
9716 @section Programming in M4sugar
9718 @cindex M4sugar
9719 M4 by itself provides only a small, but sufficient, set of all-purpose
9720 macros.  M4sugar introduces additional generic macros.  Its name was
9721 coined by Lars J. Aas: ``Readability And Greater Understanding Stands 4
9722 M4sugar''.
9724 @menu
9725 * Redefined M4 Macros::         M4 builtins changed in M4sugar
9726 * Looping constructs::          Iteration in M4
9727 * Evaluation Macros::           More quotation and evaluation control
9728 * Text processing Macros::      String manipulation in M4
9729 * Forbidden Patterns::          Catching unexpanded macros
9730 @end menu
9732 @node Redefined M4 Macros
9733 @subsection Redefined M4 Macros
9735 @msindex{builtin}
9736 @msindex{decr}
9737 @msindex{define}
9738 @msindex{dumpdef}
9739 @msindex{errprint}
9740 @msindex{esyscmd}
9741 @msindex{eval}
9742 @msindex{format}
9743 @msindex{ifdef}
9744 @msindex{incr}
9745 @msindex{index}
9746 @msindex{indir}
9747 @msindex{len}
9748 @msindex{maketemp}
9749 @msindex{pushdef}
9750 @msindex{shift}
9751 @msindex{substr}
9752 @msindex{syscmd}
9753 @msindex{sysval}
9754 @msindex{translit}
9755 @msindex{undefine}
9756 With a few exceptions, all the M4 native macros are moved in the
9757 @samp{m4_} pseudo-namespace, e.g., M4sugar renames @code{define} as
9758 @code{m4_define} etc.
9760 Some M4 macros are redefined, and are slightly incompatible with their
9761 native equivalent.
9763 @defmac dnl
9764 @msindex{dnl}
9765 This macro kept its original name: no @code{m4_dnl} is defined.
9766 @end defmac
9768 @defmac m4_defn (@var{macro})
9769 @msindex{defn}
9770 Unlike the M4 builtin, this macro fails if @var{macro} is not
9771 defined.  See @code{m4_undefine}.
9772 @end defmac
9774 @defmac m4_exit (@var{exit-status})
9775 @msindex{exit}
9776 This macro corresponds to @code{m4exit}.
9777 @end defmac
9779 @defmac m4_if (@var{comment})
9780 @defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @ovar{not-equal})
9781 @defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @dots{})
9782 @msindex{if}
9783 This macro corresponds to @code{ifelse}.
9784 @end defmac
9786 @defmac m4_include (@var{file})
9787 @defmacx m4_sinclude (@var{file})
9788 @msindex{include}
9789 @msindex{sinclude}
9790 Like the M4 builtins, but warn against multiple inclusions of @var{file}.
9791 @end defmac
9793 @defmac m4_bpatsubst (@var{string}, @var{regexp}, @ovar{replacement})
9794 @msindex{bpatsubst}
9795 This macro corresponds to @code{patsubst}.  The name @code{m4_patsubst}
9796 is kept for future versions of M4sh, on top of @acronym{GNU} M4 which will
9797 provide extended regular expression syntax via @code{epatsubst}.
9798 @end defmac
9800 @defmac m4_popdef (@var{macro})
9801 @msindex{popdef}
9802 Unlike the M4 builtin, this macro fails if @var{macro} is not
9803 defined.  See @code{m4_undefine}.
9804 @end defmac
9806 @defmac m4_bregexp (@var{string}, @var{regexp}, @ovar{replacement})
9807 @msindex{bregexp}
9808 This macro corresponds to @code{regexp}.  The name @code{m4_regexp}
9809 is kept for future versions of M4sh, on top of @acronym{GNU} M4 which will
9810 provide extended regular expression syntax via @code{eregexp}.
9811 @end defmac
9813 @defmac m4_wrap (@var{text})
9814 @msindex{wrap}
9815 This macro corresponds to @code{m4wrap}.
9817 Posix requires arguments of multiple @code{m4wrap} calls to be
9818 reprocessed at @acronym{EOF} in the same order as the original calls.
9819 @acronym{GNU} M4 versions through 1.4.x, however, reprocess them in
9820 reverse order.  Your code should not depend on the order.
9822 Also, Posix requires @code{m4wrap} to ignore its second and succeeding
9823 arguments, but @acronym{GNU} M4 versions through 1.4.x concatenate the
9824 arguments with intervening spaces.  Your code should not pass more than
9825 one argument.
9827 You are encouraged to end @var{text} with @samp{[]}, to avoid unexpected
9828 token pasting between consecutive invocations of @code{m4_wrap}, as in:
9830 @example
9831 m4_define([foo], [bar])
9832 m4_define([foofoo], [OUCH])
9833 m4_wrap([foo])
9834 m4_wrap([foo])
9835 @result{}OUCH
9836 @end example
9837 @end defmac
9839 @defmac m4_undefine (@var{macro})
9840 @msindex{undefine}
9841 Unlike the M4 builtin, this macro fails if @var{macro} is not
9842 defined.  Use
9844 @example
9845 m4_ifdef([@var{macro}], [m4_undefine([@var{macro}])])
9846 @end example
9848 @noindent
9849 to recover the behavior of the builtin.
9850 @end defmac
9854 @node Looping constructs
9855 @subsection Looping constructs
9857 The following macros implement loops in M4.
9859 @defmac m4_for (@var{var}, @var{first}, @var{last}, @ovar{step}, @var{expression})
9860 @msindex{for}
9861 Loop over the numeric values between @var{first} and @var{last}
9862 including bounds by increments of @var{step}.  For each iteration,
9863 expand @var{expression} with the numeric value assigned to @var{var}.
9864 If @var{step} is omitted, it defaults to @samp{1} or @samp{-1} depending
9865 on the order of the limits.  If given, @var{step} has to match this
9866 order.
9867 @end defmac
9869 @defmac m4_foreach (@var{var}, @var{list}, @var{expression})
9870 @msindex{foreach}
9871 Loop over the comma-separated M4 list @var{list}, assigning each value
9872 to @var{var}, and expand @var{expression}.  The following example
9873 outputs two lines:
9875 @example
9876 m4_foreach([myvar], [[foo], [bar, baz]],
9877            [echo myvar
9880 @end example
9881 @end defmac
9883 @defmac m4_foreach_w (@var{var}, @var{list}, @var{expression})
9884 @msindex{foreach_w}
9885 Loop over the white-space-separated list @var{list}, assigning each value
9886 to @var{var}, and expand @var{expression}.
9888 The deprecated macro @code{AC_FOREACH} is an alias of
9889 @code{m4_foreach_w}.
9890 @end defmac
9894 @node Evaluation Macros
9895 @subsection Evaluation Macros
9897 The following macros give some control over the order of the evaluation
9898 by adding or removing levels of quotes.  They are meant for hard-core M4
9899 programmers.
9901 @defmac m4_dquote (@var{arg1}, @dots{})
9902 @msindex{dquote}
9903 Return the arguments as a quoted list of quoted arguments.
9904 @end defmac
9906 @defmac m4_quote (@var{arg1}, @dots{})
9907 @msindex{quote}
9908 Return the arguments as a single entity, i.e., wrap them into a pair of
9909 quotes.
9910 @end defmac
9912 The following example aims at emphasizing the difference between (i), not
9913 using these macros, (ii), using @code{m4_quote}, and (iii), using
9914 @code{m4_dquote}.
9916 @example
9917 $ @kbd{cat example.m4}
9918 # Overquote, so that quotes are visible.
9919 m4_define([show], [$[]1 = [$1], $[]@@ = [$@@]])
9920 m4_divert(0)dnl
9921 show(a, b)
9922 show(m4_quote(a, b))
9923 show(m4_dquote(a, b))
9924 $ @kbd{autom4te -l m4sugar example.m4}
9925 $1 = a, $@@ = [a],[b]
9926 $1 = a,b, $@@ = [a,b]
9927 $1 = [a],[b], $@@ = [[a],[b]]
9928 @end example
9932 @node Text processing Macros
9933 @subsection Text processing Macros
9935 The following macros may be used to manipulate strings in M4.
9936 They are not intended for casual use.
9938 @defmac m4_re_escape (@var{string})
9939 @msindex{re_escape}
9940 Backslash-escape all characters in @var{string} that are active in
9941 regexps.
9942 @end defmac
9944 @defmac m4_tolower (@var{string})
9945 @defmacx m4_toupper (@var{string})
9946 @msindex{tolower}
9947 @msindex{toupper}
9948 Return @var{string} with letters converted to upper or lower case,
9949 respectively.
9950 @end defmac
9952 @defmac m4_split (@var{string}, @ovar{regexp})
9953 @msindex{split}
9954 Split @var{string} into an M4 list of elements quoted by @samp{[} and
9955 @samp{]}, while keeping white space at the beginning and at the end.
9956 If @var{regexp} is given, use it instead of @samp{[\t ]+} for splitting.
9957 If @var{string} is empty, the result is an empty list.
9958 @end defmac
9960 @defmac m4_normalize (@var{string})
9961 @msindex{normalize}
9962 Remove leading and trailing spaces and tabs, sequences of
9963 backslash-then-newline, and replace multiple spaces and tabs with a
9964 single space.
9965 @end defmac
9967 @defmac m4_append (@var{macro-name}, @var{string}, @ovar{separator})
9968 @defmacx m4_append_uniq (@var{macro-name}, @var{string}, @ovar{separator})
9969 @msindex{append}
9970 @msindex{append_uniq}
9971 Redefine @var{macro-name} to its former contents with @var{separator}
9972 and @var{string} added at the end.  If @var{macro-name} was undefined
9973 before (but not if it was defined but empty), then no @var{separator} is
9974 added.  @code{m4_append} can be used to grow strings, and
9975 @code{m4_append_uniq} to grow strings without duplicating substrings.
9976 @end defmac
9980 @node Forbidden Patterns
9981 @subsection Forbidden Patterns
9982 @cindex Forbidden patterns
9983 @cindex Patterns, forbidden
9985 M4sugar provides a means to define suspicious patterns, patterns
9986 describing tokens which should not be found in the output.  For
9987 instance, if an Autoconf @file{configure} script includes tokens such as
9988 @samp{AC_DEFINE}, or @samp{dnl}, then most probably something went
9989 wrong (typically a macro was not evaluated because of overquotation).
9991 M4sugar forbids all the tokens matching @samp{^m4_} and @samp{^dnl$}.
9993 @defmac m4_pattern_forbid (@var{pattern})
9994 @msindex{pattern_forbid}
9995 Declare that no token matching @var{pattern} must be found in the output.
9996 Comments are not checked; this can be a problem if, for instance, you
9997 have some macro left unexpanded after an @samp{#include}.  No consensus
9998 is currently found in the Autoconf community, as some people consider it
9999 should be valid to name macros in comments (which doesn't make sense to
10000 the author of this documentation, as @samp{#}-comments should document
10001 the output, not the input, documented by @samp{dnl} comments).
10002 @end defmac
10004 Of course, you might encounter exceptions to these generic rules, for
10005 instance you might have to refer to @samp{$m4_flags}.
10007 @defmac m4_pattern_allow (@var{pattern})
10008 @msindex{pattern_allow}
10009 Any token matching @var{pattern} is allowed, including if it matches an
10010 @code{m4_pattern_forbid} pattern.
10011 @end defmac
10013 @node Programming in M4sh
10014 @section Programming in M4sh
10016 @c FIXME: Eventually will become a chapter, as it is not related to
10017 @c programming in M4 per se.
10019 M4sh, pronounced ``mash'', is aiming at producing portable Bourne shell
10020 scripts.  This name was coined by Lars J. Aas, who notes that,
10021 according to the Webster's Revised Unabridged Dictionary (1913):
10023 @quotation
10024 Mash \Mash\, n.  [Akin to G. meisch, maisch, meische, maische, mash,
10025 wash, and prob.@: to AS. miscian to mix.  See ``Mix''.]
10027 @enumerate 1
10028 @item
10029 A mass of mixed ingredients reduced to a soft pulpy state by beating or
10030 pressure@enddots{}
10032 @item
10033 A mixture of meal or bran and water fed to animals.
10035 @item
10036 A mess; trouble.  [Obs.] --Beau.@: & Fl.
10037 @end enumerate
10038 @end quotation
10041 For the time being, it is not mature enough to be widely used.
10043 M4sh provides portable alternatives for some common shell constructs
10044 that unfortunately are not portable in practice.
10046 @c Deprecated, to be replaced by a better API
10047 @ignore
10048 @defmac AS_BASENAME (@var{file-name})
10049 @asindex{BASENAME}
10050 Output the non-directory portion of @var{file-name}.  For example,
10051 if @code{$file} is @samp{/one/two/three}, the command
10052 @code{base=`AS_BASENAME(["$file"])`} sets @code{base} to @samp{three}.
10053 @end defmac
10054 @end ignore
10056 @defmac AS_BOURNE_COMPATIBLE
10057 @asindex{BOURNE_COMPATIBLE}
10058 Set up the shell to be more compatible with the Bourne shell as
10059 standardized by Posix, if possible.  This may involve setting
10060 environment variables, or setting options, or similar
10061 implementation-specific actions.
10062 @end defmac
10064 @defmac AS_CASE (@var{word}, @ovar{pattern1}, @ovar{if-matched1}, @dots{}, @ovar{default})
10065 @asindex{CASE}
10066 Expand into a shell @samp{case} statement, where @var{word} is matched
10067 against one or more patterns.  @var{if-matched} is run if the
10068 corresponding pattern matched @var{word}, else @var{default} is run.
10069 @end defmac
10071 @defmac AS_DIRNAME (@var{file-name})
10072 @asindex{DIRNAME}
10073 Output the directory portion of @var{file-name}.  For example,
10074 if @code{$file} is @samp{/one/two/three}, the command
10075 @code{dir=`AS_DIRNAME(["$file"])`} sets @code{dir} to @samp{/one/two}.
10076 @end defmac
10078 @defmac AS_IF (@var{test1}, @ovar{run-if-true1}, @dots{}, @ovar{run-if-false})
10079 @asindex{IF}
10080 Run shell code @var{test1}.  If @var{test1} exits with a zero status then
10081 run shell code @var{run-if-true1}, else examine further tests.  If no test
10082 exits with a zero status, run shell code @var{run-if-false}, with
10083 simplifications if either @var{run-if-true1} or @var{run-if-false1}
10084 is empty.  For example,
10086 @example
10087 AS_IF([test "$foo" = yes], [HANDLE_FOO([yes])],
10088       [test "$foo" != no], [HANDLE_FOO([maybe])],
10089       [echo foo not specified])
10090 @end example
10092 @noindent
10093 ensures any required macros of @code{HANDLE_FOO}
10094 are expanded before the first test.
10095 @end defmac
10097 @defmac AS_MKDIR_P (@var{file-name})
10098 @asindex{MKDIR_P}
10099 Make the directory @var{file-name}, including intervening directories
10100 as necessary.  This is equivalent to @samp{mkdir -p @var{file-name}},
10101 except that it is portable to older versions of @command{mkdir} that
10102 lack support for the @option{-p} option.  Also, @code{AS_MKDIR_P}
10103 succeeds if @var{file-name} is a symbolic link to an existing directory,
10104 even though Posix is unclear whether @samp{mkdir -p} should
10105 succeed in that case.  If creation of @var{file-name} fails, exit the
10106 script.
10108 Also see the @code{AC_PROG_MKDIR_P} macro (@pxref{Particular Programs}).
10109 @end defmac
10111 @defmac AS_SHELL_SANITIZE
10112 @asindex{SHELL_SANITIZE}
10113 Initialize the shell suitably for @code{configure} scripts.  This has
10114 the effect of @code{AS_BOURNE_COMPATIBLE}, and sets some other
10115 environment variables for predictable results from configuration tests.
10116 For example, it sets @env{LC_ALL} to change to the default C locale.
10117 @xref{Special Shell Variables}.
10118 @end defmac
10120 @defmac AS_TR_CPP (@var{expression})
10121 @asindex{TR_CPP}
10122 Transform @var{expression} into a valid right-hand side for a C @code{#define}.
10123 For example:
10125 @example
10126 # This outputs "#define HAVE_CHAR_P 1".
10127 type="char *"
10128 echo "#define AS_TR_CPP([HAVE_$type]) 1"
10129 @end example
10130 @end defmac
10132 @defmac AS_TR_SH (@var{expression})
10133 @asindex{TR_SH}
10134 Transform @var{expression} into a valid shell variable name.  For example:
10136 @example
10137 # This outputs "Have it!".
10138 header="sys/some file.h"
10139 AS_TR_SH([HAVE_$header])=yes
10140 if test "$HAVE_sys_some_file_h" = yes; then echo "Have it!"; fi
10141 @end example
10142 @end defmac
10144 @defmac AS_SET_CATFILE (@var{var}, @var{dir}, @var{file})
10145 @asindex{SET_CATFILE}
10146 Set the shell variable @var{var} to @var{dir}/@var{file}, but
10147 optimizing the common cases (@var{dir} or @var{file} is @samp{.},
10148 @var{file} is absolute, etc.).
10149 @end defmac
10152 @node File Descriptor Macros
10153 @section File Descriptor Macros
10154 @cindex input
10155 @cindex standard input
10156 @cindex file descriptors
10157 @cindex descriptors
10158 @cindex low-level output
10159 @cindex output, low-level
10161 The following macros define file descriptors used to output messages
10162 (or input values) from @file{configure} scripts.
10163 For example:
10165 @example
10166 echo "$wombats found" >&AS_MESSAGE_LOG_FD
10167 echo 'Enter desired kangaroo count:' >&AS_MESSAGE_FD
10168 read kangaroos <&AS_ORIGINAL_STDIN_FD`
10169 @end example
10171 @noindent
10172 However doing so is seldom needed, because Autoconf provides higher
10173 level macros as described below.
10175 @defmac AS_MESSAGE_FD
10176 @asindex{MESSAGE_FD}
10177 The file descriptor for @samp{checking for...}  messages and results.
10178 Normally this directs messages to the standard output, however when
10179 @command{configure} is run with the @option{-q} option, messages sent to
10180 @code{AS_MESSAGE_FD} are discarded.
10182 If you want to display some messages, consider using one of the printing
10183 macros (@pxref{Printing Messages}) instead.  Copies of messages output
10184 via these macros are also recorded in @file{config.log}.
10185 @end defmac
10187 @defmac AS_MESSAGE_LOG_FD
10188 @asindex{MESSAGE_LOG_FD}
10190 The file descriptor for messages logged to @file{config.log}.  Macros
10191 that run tools, like @code{AC_COMPILE_IFELSE} (@pxref{Running the
10192 Compiler}), redirect all output to this descriptor.  You may want to do
10193 so if you develop such a low-level macro.
10194 @end defmac
10196 @defmac AS_ORIGINAL_STDIN_FD
10197 @asindex{ORIGINAL_STDIN_FD}
10198 The file descriptor for the original standard input.
10200 When @command{configure} runs, it may accidentally execute an
10201 interactive command that has the same name as the non-interactive meant
10202 to be used or checked.  If the standard input was the terminal, such
10203 interactive programs would cause @command{configure} to stop, pending
10204 some user input.  Therefore @command{configure} redirects its standard
10205 input from @file{/dev/null} during its initialization.  This is not
10206 normally a problem, since @command{configure} normally does not need
10207 user input.
10209 In the extreme case where your @file{configure} script really needs to
10210 obtain some values from the original standard input, you can read them
10211 explicitly from @code{AS_ORIGINAL_STDIN_FD}.
10212 @end defmac
10215 @c =================================================== Writing Autoconf Macros.
10217 @node Writing Autoconf Macros
10218 @chapter Writing Autoconf Macros
10220 When you write a feature test that could be applicable to more than one
10221 software package, the best thing to do is encapsulate it in a new macro.
10222 Here are some instructions and guidelines for writing Autoconf macros.
10224 @menu
10225 * Macro Definitions::           Basic format of an Autoconf macro
10226 * Macro Names::                 What to call your new macros
10227 * Reporting Messages::          Notifying @command{autoconf} users
10228 * Dependencies Between Macros::  What to do when macros depend on other macros
10229 * Obsoleting Macros::           Warning about old ways of doing things
10230 * Coding Style::                Writing Autoconf macros @`a la Autoconf
10231 @end menu
10233 @node Macro Definitions
10234 @section Macro Definitions
10236 @acindex{DEFUN}
10237 Autoconf macros are defined using the @code{AC_DEFUN} macro, which is
10238 similar to the M4 builtin @code{m4_define} macro.  In addition to
10239 defining a macro, @code{AC_DEFUN} adds to it some code that is used to
10240 constrain the order in which macros are called (@pxref{Prerequisite
10241 Macros}).
10243 An Autoconf macro definition looks like this:
10245 @example
10246 AC_DEFUN(@var{macro-name}, @var{macro-body})
10247 @end example
10249 You can refer to any arguments passed to the macro as @samp{$1},
10250 @samp{$2}, etc.  @xref{Definitions, , How to define new macros, m4.info,
10251 @acronym{GNU} M4}, for more complete information on writing M4 macros.
10253 Be sure to properly quote both the @var{macro-body} @emph{and} the
10254 @var{macro-name} to avoid any problems if the macro happens to have
10255 been previously defined.
10257 Each macro should have a header comment that gives its prototype, and a
10258 brief description.  When arguments have default values, display them in
10259 the prototype.  For example:
10261 @example
10262 # AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1])
10263 # --------------------------------------
10264 m4_define([AC_MSG_ERROR],
10265   [@{ AS_MESSAGE([error: $1], [2])
10266      exit m4_default([$2], [1]); @}])
10267 @end example
10269 Comments about the macro should be left in the header comment.  Most
10270 other comments make their way into @file{configure}, so just keep
10271 using @samp{#} to introduce comments.
10273 @cindex @code{dnl}
10274 If you have some special comments about pure M4 code, comments
10275 that make no sense in @file{configure} and in the header comment, then
10276 use the builtin @code{dnl}: it causes M4 to discard the text
10277 through the next newline.
10279 Keep in mind that @code{dnl} is rarely needed to introduce comments;
10280 @code{dnl} is more useful to get rid of the newlines following macros
10281 that produce no output, such as @code{AC_REQUIRE}.
10284 @node Macro Names
10285 @section Macro Names
10287 All of the Autoconf macros have all-uppercase names starting with
10288 @samp{AC_} to prevent them from accidentally conflicting with other
10289 text.  All shell variables that they use for internal purposes have
10290 mostly-lowercase names starting with @samp{ac_}.  To ensure that your
10291 macros don't conflict with present or future Autoconf macros, you should
10292 prefix your own macro names and any shell variables they use with some
10293 other sequence.  Possibilities include your initials, or an abbreviation
10294 for the name of your organization or software package.
10296 Most of the Autoconf macros' names follow a structured naming convention
10297 that indicates the kind of feature check by the name.  The macro names
10298 consist of several words, separated by underscores, going from most
10299 general to most specific.  The names of their cache variables use the
10300 same convention (@pxref{Cache Variable Names}, for more information on
10301 them).
10303 The first word of the name after @samp{AC_} usually tells the category
10304 of the feature being tested.  Here are the categories used in Autoconf for
10305 specific test macros, the kind of macro that you are more likely to
10306 write.  They are also used for cache variables, in all-lowercase.  Use
10307 them where applicable; where they're not, invent your own categories.
10309 @table @code
10310 @item C
10311 C language builtin features.
10312 @item DECL
10313 Declarations of C variables in header files.
10314 @item FUNC
10315 Functions in libraries.
10316 @item GROUP
10317 Posix group owners of files.
10318 @item HEADER
10319 Header files.
10320 @item LIB
10321 C libraries.
10322 @item PATH
10323 Absolute names of files, including programs.
10324 @item PROG
10325 The base names of programs.
10326 @item MEMBER
10327 Members of aggregates.
10328 @item SYS
10329 Operating system features.
10330 @item TYPE
10331 C builtin or declared types.
10332 @item VAR
10333 C variables in libraries.
10334 @end table
10336 After the category comes the name of the particular feature being
10337 tested.  Any further words in the macro name indicate particular aspects
10338 of the feature.  For example, @code{AC_PROG_CC_STDC} checks whether the
10339 C compiler supports @acronym{ISO} Standard C.
10341 An internal macro should have a name that starts with an underscore;
10342 Autoconf internals should therefore start with @samp{_AC_}.
10343 Additionally, a macro that is an internal subroutine of another macro
10344 should have a name that starts with an underscore and the name of that
10345 other macro, followed by one or more words saying what the internal
10346 macro does.  For example, @code{AC_PATH_X} has internal macros
10347 @code{_AC_PATH_X_XMKMF} and @code{_AC_PATH_X_DIRECT}.
10349 @node Reporting Messages
10350 @section Reporting Messages
10351 @cindex Messages, from @command{autoconf}
10353 When macros statically diagnose abnormal situations, benign or fatal,
10354 they should report them using these macros.  For dynamic issues, i.e.,
10355 when @command{configure} is run, see @ref{Printing Messages}.
10357 @defmac AC_DIAGNOSE (@var{category}, @var{message})
10358 @acindex{DIAGNOSE}
10359 Report @var{message} as a warning (or as an error if requested by the
10360 user) if warnings of the @var{category} are turned on.  You are
10361 encouraged to use standard categories, which currently include:
10363 @table @samp
10364 @item all
10365 messages that don't fall into one of the following categories.  Use of an
10366 empty @var{category} is equivalent.
10368 @item cross
10369 related to cross compilation issues.
10371 @item obsolete
10372 use of an obsolete construct.
10374 @item syntax
10375 dubious syntactic constructs, incorrectly ordered macro calls.
10376 @end table
10377 @end defmac
10379 @defmac AC_WARNING (@var{message})
10380 @acindex{WARNING}
10381 Equivalent to @samp{AC_DIAGNOSE([syntax], @var{message})}, but you are
10382 strongly encouraged to use a finer grained category.
10383 @end defmac
10385 @defmac AC_FATAL (@var{message})
10386 @acindex{FATAL}
10387 Report a severe error @var{message}, and have @command{autoconf} die.
10388 @end defmac
10390 When the user runs @samp{autoconf -W error}, warnings from
10391 @code{AC_DIAGNOSE} and @code{AC_WARNING} are reported as error, see
10392 @ref{autoconf Invocation}.
10394 @node Dependencies Between Macros
10395 @section Dependencies Between Macros
10396 @cindex Dependencies between macros
10398 Some Autoconf macros depend on other macros having been called first in
10399 order to work correctly.  Autoconf provides a way to ensure that certain
10400 macros are called if needed and a way to warn the user if macros are
10401 called in an order that might cause incorrect operation.
10403 @menu
10404 * Prerequisite Macros::         Ensuring required information
10405 * Suggested Ordering::          Warning about possible ordering problems
10406 * One-Shot Macros::             Ensuring a macro is called only once
10407 @end menu
10409 @node Prerequisite Macros
10410 @subsection Prerequisite Macros
10411 @cindex Prerequisite macros
10412 @cindex Macros, prerequisites
10414 A macro that you write might need to use values that have previously
10415 been computed by other macros.  For example, @code{AC_DECL_YYTEXT}
10416 examines the output of @code{flex} or @code{lex}, so it depends on
10417 @code{AC_PROG_LEX} having been called first to set the shell variable
10418 @code{LEX}.
10420 Rather than forcing the user of the macros to keep track of the
10421 dependencies between them, you can use the @code{AC_REQUIRE} macro to do
10422 it automatically.  @code{AC_REQUIRE} can ensure that a macro is only
10423 called if it is needed, and only called once.
10425 @defmac AC_REQUIRE (@var{macro-name})
10426 @acindex{REQUIRE}
10427 If the M4 macro @var{macro-name} has not already been called, call it
10428 (without any arguments).  Make sure to quote @var{macro-name} with
10429 square brackets.  @var{macro-name} must have been defined using
10430 @code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
10431 that it has been called.
10433 @code{AC_REQUIRE} must be used inside a macro defined by @code{AC_DEFUN}; it
10434 must not be called from the top level.
10435 @end defmac
10437 @code{AC_REQUIRE} is often misunderstood.  It really implements
10438 dependencies between macros in the sense that if one macro depends upon
10439 another, the latter is expanded @emph{before} the body of the
10440 former.  To be more precise, the required macro is expanded before
10441 the outermost defined macro in the current expansion stack.
10442 In particular, @samp{AC_REQUIRE([FOO])} is not replaced with the body of
10443 @code{FOO}.  For instance, this definition of macros:
10445 @example
10446 @group
10447 AC_DEFUN([TRAVOLTA],
10448 [test "$body_temperature_in_celsius" -gt "38" &&
10449   dance_floor=occupied])
10450 AC_DEFUN([NEWTON_JOHN],
10451 [test "$hair_style" = "curly" &&
10452   dance_floor=occupied])
10453 @end group
10455 @group
10456 AC_DEFUN([RESERVE_DANCE_FLOOR],
10457 [if date | grep '^Sat.*pm' >/dev/null 2>&1; then
10458   AC_REQUIRE([TRAVOLTA])
10459   AC_REQUIRE([NEWTON_JOHN])
10460 fi])
10461 @end group
10462 @end example
10464 @noindent
10465 with this @file{configure.ac}
10467 @example
10468 AC_INIT([Dance Manager], [1.0], [bug-dance@@example.org])
10469 RESERVE_DANCE_FLOOR
10470 if test "$dance_floor" = occupied; then
10471   AC_MSG_ERROR([cannot pick up here, let's move])
10473 @end example
10475 @noindent
10476 does not leave you with a better chance to meet a kindred soul at
10477 other times than Saturday night since it expands into:
10479 @example
10480 @group
10481 test "$body_temperature_in_Celsius" -gt "38" &&
10482   dance_floor=occupied
10483 test "$hair_style" = "curly" &&
10484   dance_floor=occupied
10486 if date | grep '^Sat.*pm' >/dev/null 2>&1; then
10490 @end group
10491 @end example
10493 This behavior was chosen on purpose: (i) it prevents messages in
10494 required macros from interrupting the messages in the requiring macros;
10495 (ii) it avoids bad surprises when shell conditionals are used, as in:
10497 @example
10498 @group
10499 if @dots{}; then
10500   AC_REQUIRE([SOME_CHECK])
10502 @dots{}
10503 SOME_CHECK
10504 @end group
10505 @end example
10507 The helper macros @code{AS_IF} and @code{AS_CASE} may be used to
10508 enforce expansion of required macros outside of shell conditional
10509 constructs.  You are furthermore encouraged to put all @code{AC_REQUIRE} calls
10510 at the beginning of a macro.  You can use @code{dnl} to avoid the empty
10511 lines they leave.
10513 @node Suggested Ordering
10514 @subsection Suggested Ordering
10515 @cindex Macros, ordering
10516 @cindex Ordering macros
10518 Some macros should be run before another macro if both are called, but
10519 neither @emph{requires} that the other be called.  For example, a macro
10520 that changes the behavior of the C compiler should be called before any
10521 macros that run the C compiler.  Many of these dependencies are noted in
10522 the documentation.
10524 Autoconf provides the @code{AC_BEFORE} macro to warn users when macros
10525 with this kind of dependency appear out of order in a
10526 @file{configure.ac} file.  The warning occurs when creating
10527 @command{configure} from @file{configure.ac}, not when running
10528 @command{configure}.
10530 For example, @code{AC_PROG_CPP} checks whether the C compiler
10531 can run the C preprocessor when given the @option{-E} option.  It should
10532 therefore be called after any macros that change which C compiler is
10533 being used, such as @code{AC_PROG_CC}.  So @code{AC_PROG_CC} contains:
10535 @example
10536 AC_BEFORE([$0], [AC_PROG_CPP])dnl
10537 @end example
10539 @noindent
10540 This warns the user if a call to @code{AC_PROG_CPP} has already occurred
10541 when @code{AC_PROG_CC} is called.
10543 @defmac AC_BEFORE (@var{this-macro-name}, @var{called-macro-name})
10544 @acindex{BEFORE}
10545 Make M4 print a warning message to the standard error output if
10546 @var{called-macro-name} has already been called.  @var{this-macro-name}
10547 should be the name of the macro that is calling @code{AC_BEFORE}.  The
10548 macro @var{called-macro-name} must have been defined using
10549 @code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
10550 that it has been called.
10551 @end defmac
10553 @node One-Shot Macros
10554 @subsection One-Shot Macros
10555 @cindex One-shot macros
10556 @cindex Macros, called once
10558 Some macros should be called only once, either because calling them
10559 multiple time is unsafe, or because it is bad style.  For instance
10560 Autoconf ensures that @code{AC_CANONICAL_BUILD} and cousins
10561 (@pxref{Canonicalizing}) are evaluated only once, because it makes no
10562 sense to run these expensive checks more than once.  Such one-shot
10563 macros can be defined using @code{AC_DEFUN_ONCE}.
10565 @defmac AC_DEFUN_ONCE (@var{macro-name}, @var{macro-body})
10566 @acindex{DEFUN_ONCE}
10568 Declare macro @var{macro-name} like @code{AC_DEFUN} would (@pxref{Macro
10569 Definitions}), and emit a warning any time the macro is called more than
10570 once.
10571 @end defmac
10573 Obviously it is not sensible to evaluate a macro defined by
10574 @code{AC_DEFUN_ONCE} in a macro defined by @code{AC_DEFUN}.
10575 Most of the time you want to use @code{AC_REQUIRE} (@pxref{Prerequisite
10576 Macros}).
10578 @node Obsoleting Macros
10579 @section Obsoleting Macros
10580 @cindex Obsoleting macros
10581 @cindex Macros, obsoleting
10583 Configuration and portability technology has evolved over the years.
10584 Often better ways of solving a particular problem are developed, or
10585 ad-hoc approaches are systematized.  This process has occurred in many
10586 parts of Autoconf.  One result is that some of the macros are now
10587 considered @dfn{obsolete}; they still work, but are no longer considered
10588 the best thing to do, hence they should be replaced with more modern
10589 macros.  Ideally, @command{autoupdate} should replace the old macro calls
10590 with their modern implementation.
10592 Autoconf provides a simple means to obsolete a macro.
10594 @defmac AU_DEFUN (@var{old-macro}, @var{implementation}, @ovar{message})
10595 @auindex{DEFUN}
10596 Define @var{old-macro} as @var{implementation}.  The only difference
10597 with @code{AC_DEFUN} is that the user is warned that
10598 @var{old-macro} is now obsolete.
10600 If she then uses @command{autoupdate}, the call to @var{old-macro} is
10601 replaced by the modern @var{implementation}.  @var{message} should
10602 include information on what to do after running @command{autoupdate};
10603 @command{autoupdate} prints it as a warning, and includes it
10604 in the updated @file{configure.ac} file.
10606 The details of this macro are hairy: if @command{autoconf} encounters an
10607 @code{AU_DEFUN}ed macro, all macros inside its second argument are expanded
10608 as usual.  However, when @command{autoupdate} is run, only M4 and M4sugar
10609 macros are expanded here, while all other macros are disabled and
10610 appear literally in the updated @file{configure.ac}.
10611 @end defmac
10613 @defmac AU_ALIAS (@var{old-name}, @var{new-name})
10614 @auindex{ALIAS}
10615 Used if the @var{old-name} is to be replaced by a call to @var{new-macro}
10616 with the same parameters.  This happens for example if the macro was renamed.
10617 @end defmac
10619 @node Coding Style
10620 @section Coding Style
10621 @cindex Coding style
10623 The Autoconf macros follow a strict coding style.  You are encouraged to
10624 follow this style, especially if you intend to distribute your macro,
10625 either by contributing it to Autoconf itself, or via other means.
10627 The first requirement is to pay great attention to the quotation.  For
10628 more details, see @ref{Autoconf Language}, and @ref{M4 Quotation}.
10630 Do not try to invent new interfaces.  It is likely that there is a macro
10631 in Autoconf that resembles the macro you are defining: try to stick to
10632 this existing interface (order of arguments, default values, etc.).  We
10633 @emph{are} conscious that some of these interfaces are not perfect;
10634 nevertheless, when harmless, homogeneity should be preferred over
10635 creativity.
10637 Be careful about clashes both between M4 symbols and between shell
10638 variables.
10640 If you stick to the suggested M4 naming scheme (@pxref{Macro Names}),
10641 you are unlikely to generate conflicts.  Nevertheless, when you need to
10642 set a special value, @emph{avoid using a regular macro name}; rather,
10643 use an ``impossible'' name.  For instance, up to version 2.13, the macro
10644 @code{AC_SUBST} used to remember what @var{symbol} macros were already defined
10645 by setting @code{AC_SUBST_@var{symbol}}, which is a regular macro name.
10646 But since there is a macro named @code{AC_SUBST_FILE}, it was just
10647 impossible to @samp{AC_SUBST(FILE)}!  In this case,
10648 @code{AC_SUBST(@var{symbol})} or @code{_AC_SUBST(@var{symbol})} should
10649 have been used (yes, with the parentheses).
10650 @c or better yet, high-level macros such as @code{m4_expand_once}
10652 No Autoconf macro should ever enter the user-variable name space; i.e.,
10653 except for the variables that are the actual result of running the
10654 macro, all shell variables should start with @code{ac_}.  In
10655 addition, small macros or any macro that is likely to be embedded in
10656 other macros should be careful not to use obvious names.
10658 @cindex @code{dnl}
10659 Do not use @code{dnl} to introduce comments: most of the comments you
10660 are likely to write are either header comments which are not output
10661 anyway, or comments that should make their way into @file{configure}.
10662 There are exceptional cases where you do want to comment special M4
10663 constructs, in which case @code{dnl} is right, but keep in mind that it
10664 is unlikely.
10666 M4 ignores the leading blanks and newlines before each argument.
10667 Use this feature to
10668 indent in such a way that arguments are (more or less) aligned with the
10669 opening parenthesis of the macro being called.  For instance, instead of
10671 @example
10672 AC_CACHE_CHECK(for EMX OS/2 environment,
10673 ac_cv_emxos2,
10674 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])],
10675 [ac_cv_emxos2=yes], [ac_cv_emxos2=no])])
10676 @end example
10678 @noindent
10679 write
10681 @example
10682 AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
10683 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
10684                    [ac_cv_emxos2=yes],
10685                    [ac_cv_emxos2=no])])
10686 @end example
10688 @noindent
10689 or even
10691 @example
10692 AC_CACHE_CHECK([for EMX OS/2 environment],
10693                [ac_cv_emxos2],
10694                [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([],
10695                                                    [return __EMX__;])],
10696                                   [ac_cv_emxos2=yes],
10697                                   [ac_cv_emxos2=no])])
10698 @end example
10700 When using @code{AC_RUN_IFELSE} or any macro that cannot work when
10701 cross-compiling, provide a pessimistic value (typically @samp{no}).
10703 Feel free to use various tricks to prevent auxiliary tools, such as
10704 syntax-highlighting editors, from behaving improperly.  For instance,
10705 instead of:
10707 @example
10708 m4_bpatsubst([$1], [$"])
10709 @end example
10711 @noindent
10714 @example
10715 m4_bpatsubst([$1], [$""])
10716 @end example
10718 @noindent
10719 so that Emacsen do not open an endless ``string'' at the first quote.
10720 For the same reasons, avoid:
10722 @example
10723 test $[#] != 0
10724 @end example
10726 @noindent
10727 and use:
10729 @example
10730 test $[@@%:@@] != 0
10731 @end example
10733 @noindent
10734 Otherwise, the closing bracket would be hidden inside a @samp{#}-comment,
10735 breaking the bracket-matching highlighting from Emacsen.  Note the
10736 preferred style to escape from M4: @samp{$[1]}, @samp{$[@@]}, etc.  Do
10737 not escape when it is unnecessary.  Common examples of useless quotation
10738 are @samp{[$]$1} (write @samp{$$1}), @samp{[$]var} (use @samp{$var}),
10739 etc.  If you add portability issues to the picture, you'll prefer
10740 @samp{$@{1+"$[@@]"@}} to @samp{"[$]@@"}, and you'll prefer do something
10741 better than hacking Autoconf @code{:-)}.
10743 When using @command{sed}, don't use @option{-e} except for indenting
10744 purposes.  With the @code{s} and @code{y} commands, the preferred
10745 separator is @samp{/} unless @samp{/} itself might appear in the pattern
10746 or replacement, in which case you should use @samp{|}, or optionally
10747 @samp{,} if you know the pattern and replacement cannot contain a file
10748 name.  If none of these characters will do, choose a printable character
10749 that cannot appear in the pattern or replacement.  Characters from the
10750 set @samp{"#$&'()*;<=>?`|~} are good choices if the pattern or
10751 replacement might contain a file name, since they have special meaning
10752 to the shell and are less likely to occur in file names.
10754 @xref{Macro Definitions}, for details on how to define a macro.  If a
10755 macro doesn't use @code{AC_REQUIRE}, is expected to never be the object
10756 of an @code{AC_REQUIRE} directive, and macros required by other macros
10757 inside arguments do not need to be expanded before this macro, then
10758 use @code{m4_define}.  In case of doubt, use @code{AC_DEFUN}.
10759 All the @code{AC_REQUIRE} statements should be at the beginning of the
10760 macro, and each statement should be followed by @code{dnl}.
10762 You should not rely on the number of arguments: instead of checking
10763 whether an argument is missing, test that it is not empty.  It provides
10764 both a simpler and a more predictable interface to the user, and saves
10765 room for further arguments.
10767 Unless the macro is short, try to leave the closing @samp{])} at the
10768 beginning of a line, followed by a comment that repeats the name of the
10769 macro being defined.  This introduces an additional newline in
10770 @command{configure}; normally, that is not a problem, but if you want to
10771 remove it you can use @samp{[]dnl} on the last line.  You can similarly
10772 use @samp{[]dnl} after a macro call to remove its newline.  @samp{[]dnl}
10773 is recommended instead of @samp{dnl} to ensure that M4 does not
10774 interpret the @samp{dnl} as being attached to the preceding text or
10775 macro output.  For example, instead of:
10777 @example
10778 AC_DEFUN([AC_PATH_X],
10779 [AC_MSG_CHECKING([for X])
10780 AC_REQUIRE_CPP()
10781 @r{# @dots{}omitted@dots{}}
10782   AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
10783 fi])
10784 @end example
10786 @noindent
10787 you would write:
10789 @example
10790 AC_DEFUN([AC_PATH_X],
10791 [AC_REQUIRE_CPP()[]dnl
10792 AC_MSG_CHECKING([for X])
10793 @r{# @dots{}omitted@dots{}}
10794   AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
10795 fi[]dnl
10796 ])# AC_PATH_X
10797 @end example
10799 If the macro is long, try to split it into logical chunks.  Typically,
10800 macros that check for a bug in a function and prepare its
10801 @code{AC_LIBOBJ} replacement should have an auxiliary macro to perform
10802 this setup.  Do not hesitate to introduce auxiliary macros to factor
10803 your code.
10805 In order to highlight the recommended coding style, here is a macro
10806 written the old way:
10808 @example
10809 dnl Check for EMX on OS/2.
10810 dnl _AC_EMXOS2
10811 AC_DEFUN(_AC_EMXOS2,
10812 [AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2,
10813 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)],
10814 ac_cv_emxos2=yes, ac_cv_emxos2=no)])
10815 test "$ac_cv_emxos2" = yes && EMXOS2=yes])
10816 @end example
10818 @noindent
10819 and the new way:
10821 @example
10822 # _AC_EMXOS2
10823 # ----------
10824 # Check for EMX on OS/2.
10825 m4_define([_AC_EMXOS2],
10826 [AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
10827 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
10828                    [ac_cv_emxos2=yes],
10829                    [ac_cv_emxos2=no])])
10830 test "$ac_cv_emxos2" = yes && EMXOS2=yes[]dnl
10831 ])# _AC_EMXOS2
10832 @end example
10837 @c ============================================= Portable Shell Programming
10839 @node Portable Shell
10840 @chapter Portable Shell Programming
10841 @cindex Portable shell programming
10843 When writing your own checks, there are some shell-script programming
10844 techniques you should avoid in order to make your code portable.  The
10845 Bourne shell and upward-compatible shells like the Korn shell and Bash
10846 have evolved over the years, but to prevent trouble, do not take
10847 advantage of features that were added after Unix version 7, circa
10848 1977 (@pxref{Systemology}).
10850 You should not use shell functions, aliases, negated character
10851 classes, or other features that are not found in all Bourne-compatible
10852 shells; restrict yourself to the lowest common denominator.  Even
10853 @code{unset} is not supported by all shells!
10855 Some ancient systems have quite
10856 small limits on the length of the @samp{#!} line; for instance, 32
10857 bytes (not including the newline) on SunOS 4.
10858 A few ancient 4.2@acronym{BSD} based systems (such as Dynix circa 1984)
10859 required a single space between the @samp{#!} and the @samp{/}.
10860 However, these ancient systems are no longer of practical concern.
10862 The set of external programs you should run in a @command{configure} script
10863 is fairly small.  @xref{Utilities in Makefiles, , Utilities in
10864 Makefiles, standards, @acronym{GNU} Coding Standards}, for the list.  This
10865 restriction allows users to start out with a fairly small set of
10866 programs and build the rest, avoiding too many interdependencies between
10867 packages.
10869 Some of these external utilities have a portable subset of features; see
10870 @ref{Limitations of Usual Tools}.
10872 There are other sources of documentation about shells.  The
10873 specification for the Posix
10874 @uref{http://www.opengroup.org/@/susv3/@/utilities/@/xcu_chap02.html, Shell
10875 Command Language}, though more generous than the restrictive shell
10876 subset described above, is fairly portable nowadays.  Also please see
10877 @uref{http://www.faqs.org/@/faqs/@/unix-faq/@/shell/, the Shell FAQs}.
10879 @menu
10880 * Shellology::                  A zoology of shells
10881 * Here-Documents::              Quirks and tricks
10882 * File Descriptors::            FDs and redirections
10883 * File System Conventions::     File names
10884 * Shell Substitutions::         Variable and command expansions
10885 * Assignments::                 Varying side effects of assignments
10886 * Parentheses::                 Parentheses in shell scripts
10887 * Slashes::                     Slashes in shell scripts
10888 * Special Shell Variables::     Variables you should not change
10889 * Limitations of Builtins::     Portable use of not so portable /bin/sh
10890 * Limitations of Usual Tools::  Portable use of portable tools
10891 @end menu
10893 @node Shellology
10894 @section Shellology
10895 @cindex Shellology
10897 There are several families of shells, most prominently the Bourne family
10898 and the C shell family which are deeply incompatible.  If you want to
10899 write portable shell scripts, avoid members of the C shell family.  The
10900 @uref{http://www.faqs.org/@/faqs/@/unix-faq/@/shell/@/shell-differences/, the
10901 Shell difference FAQ} includes a small history of Posix shells, and a
10902 comparison between several of them.
10904 Below we describe some of the members of the Bourne shell family.
10906 @table @asis
10907 @item Ash
10908 @cindex Ash
10909 Ash is often used on @acronym{GNU}/Linux and @acronym{BSD}
10910 systems as a light-weight Bourne-compatible shell.  Ash 0.2 has some
10911 bugs that are fixed in the 0.3.x series, but portable shell scripts
10912 should work around them, since version 0.2 is still shipped with many
10913 @acronym{GNU}/Linux distributions.
10915 To be compatible with Ash 0.2:
10917 @itemize @minus
10918 @item
10919 don't use @samp{$?} after expanding empty or unset variables,
10920 or at the start of an @command{eval}:
10922 @example
10923 foo=
10924 false
10925 $foo
10926 echo "Do not use it: $?"
10927 false
10928 eval 'echo "Do not use it: $?"'
10929 @end example
10931 @item
10932 don't use command substitution within variable expansion:
10934 @example
10935 cat $@{FOO=`bar`@}
10936 @end example
10938 @item
10939 beware that single builtin substitutions are not performed by a
10940 subshell, hence their effect applies to the current shell!  @xref{Shell
10941 Substitutions}, item ``Command Substitution''.
10942 @end itemize
10944 @item Bash
10945 @cindex Bash
10946 To detect whether you are running Bash, test whether
10947 @code{BASH_VERSION} is set.  To require
10948 Posix compatibility, run @samp{set -o posix}.  @xref{Bash POSIX
10949 Mode, , Bash Posix Mode, bash, The @acronym{GNU} Bash Reference
10950 Manual}, for details.
10952 @item Bash 2.05 and later
10953 @cindex Bash 2.05 and later
10954 Versions 2.05 and later of Bash use a different format for the
10955 output of the @command{set} builtin, designed to make evaluating its
10956 output easier.  However, this output is not compatible with earlier
10957 versions of Bash (or with many other shells, probably).  So if
10958 you use Bash 2.05 or higher to execute @command{configure},
10959 you'll need to use Bash 2.05 for all other build tasks as well.
10961 @item Ksh
10962 @cindex Ksh
10963 @cindex Korn shell
10964 @prindex @samp{ksh}
10965 @prindex @samp{ksh88}
10966 @prindex @samp{ksh93}
10967 The Korn shell is compatible with the Bourne family and it mostly
10968 conforms to Posix.  It has two major variants commonly
10969 called @samp{ksh88} and @samp{ksh93}, named after the years of initial
10970 release.  It is usually called @command{ksh}, but is called @command{sh}
10971 on some hosts if you set your path appropriately.
10973 Solaris systems have three variants:
10974 @prindex @command{/usr/bin/ksh} on Solaris
10975 @command{/usr/bin/ksh} is @samp{ksh88}; it is
10976 standard on Solaris 2.0 and later.
10977 @prindex @command{/usr/xpg4/bin/sh} on Solaris
10978 @command{/usr/xpg4/bin/sh} is a Posix-compliant variant of
10979 @samp{ksh88}; it is standard on Solaris 9 and later.
10980 @prindex @command{/usr/dt/bin/dtksh} on Solaris
10981 @command{/usr/dt/bin/dtksh} is @samp{ksh93}.
10982 Variants that are not standard may be parts of optional
10983 packages.  There is no extra charge for these packages, but they are
10984 not part of a minimal OS install and therefore some installations may
10985 not have it.
10987 Starting with Tru64 Version 4.0, the Korn shell @command{/usr/bin/ksh}
10988 is also available as @command{/usr/bin/posix/sh}.  If the environment
10989 variable @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of
10990 the standard shell conform to Posix.
10992 @item Pdksh
10993 @prindex @samp{pdksh}
10994 A public-domain clone of the Korn shell called @command{pdksh} is widely
10995 available: it has most of the @samp{ksh88} features along with a few of
10996 its own.  It usually sets @code{KSH_VERSION}, except if invoked as
10997 @command{/bin/sh} on Open@acronym{BSD}, and similarly to Bash you can require
10998 Posix compatibility by running @samp{set -o posix}.  Unfortunately, with
10999 @command{pdksh} 5.2.14 (the latest stable version as of February 2006)
11000 Posix mode is buggy and causes @command{pdksh} to depart from Posix in
11001 at least one respect:
11003 @example
11004 $ @kbd{echo "`echo \"hello\"`"}
11005 hello
11006 $ @kbd{set -o posix}
11007 $ @kbd{echo "`echo \"hello\"`"}
11008 "hello"
11009 @end example
11011 The last line of output contains spurious quotes.  This is yet another
11012 reason why portable shell code should not contain
11013 @code{"`@dots{}\"@dots{}\"@dots{}`"} constructs (@pxref{Shell
11014 Substitutions}).
11016 @item Zsh
11017 @cindex Zsh
11018 To detect whether you are running @command{zsh}, test whether
11019 @code{ZSH_VERSION} is set.  By default @command{zsh} is @emph{not}
11020 compatible with the Bourne shell: you must execute @samp{emulate sh},
11021 and for @command{zsh} versions before 3.1.6-dev-18 you must also
11022 set @code{NULLCMD} to @samp{:}.  @xref{Compatibility, , Compatibility,
11023 zsh, The Z Shell Manual}, for details.
11025 The default Mac OS X @command{sh} was originally Zsh; it was changed to
11026 Bash in Mac OS X 10.2.
11027 @end table
11029 The following discussion between Russ Allbery and Robert Lipe is worth
11030 reading:
11032 @noindent
11033 Russ Allbery:
11035 @quotation
11036 The @acronym{GNU} assumption that @command{/bin/sh} is the one and only shell
11037 leads to a permanent deadlock.  Vendors don't want to break users'
11038 existing shell scripts, and there are some corner cases in the Bourne
11039 shell that are not completely compatible with a Posix shell.  Thus,
11040 vendors who have taken this route will @emph{never} (OK@dots{}``never say
11041 never'') replace the Bourne shell (as @command{/bin/sh}) with a
11042 Posix shell.
11043 @end quotation
11045 @noindent
11046 Robert Lipe:
11048 @quotation
11049 This is exactly the problem.  While most (at least most System V's) do
11050 have a Bourne shell that accepts shell functions most vendor
11051 @command{/bin/sh} programs are not the Posix shell.
11053 So while most modern systems do have a shell @emph{somewhere} that meets the
11054 Posix standard, the challenge is to find it.
11055 @end quotation
11057 @node Here-Documents
11058 @section Here-Documents
11059 @cindex Here-documents
11060 @cindex Shell here-documents
11062 Don't rely on @samp{\} being preserved just because it has no special
11063 meaning together with the next symbol.  In the native @command{sh}
11064 on Open@acronym{BSD} 2.7 @samp{\"} expands to @samp{"} in here-documents with
11065 unquoted delimiter.  As a general rule, if @samp{\\} expands to @samp{\}
11066 use @samp{\\} to get @samp{\}.
11068 With Open@acronym{BSD} 2.7's @command{sh}
11070 @example
11071 @group
11072 $ @kbd{cat <<EOF
11073 > \" \\
11074 > EOF}
11075 " \
11076 @end group
11077 @end example
11079 @noindent
11080 and with Bash:
11082 @example
11083 @group
11084 bash-2.04$ @kbd{cat <<EOF
11085 > \" \\
11086 > EOF}
11087 \" \
11088 @end group
11089 @end example
11091 Some shells mishandle large here-documents: for example,
11092 Solaris 10 @command{dtksh} and the UnixWare 7.1.1 Posix shell, which are
11093 derived from Korn shell version M-12/28/93d, mishandle braced variable
11094 expansion that crosses a 1024- or 4096-byte buffer boundary
11095 within a here-document.  Only the part of the variable name after the boundary
11096 is used.  For example, @code{$@{variable@}} could be replaced by the expansion
11097 of @code{$@{ble@}}.  If the end of the variable name is aligned with the block
11098 boundary, the shell reports an error, as if you used @code{$@{@}}.
11099 Instead of @code{$@{variable-default@}}, the shell may expand
11100 @code{$@{riable-default@}}, or even @code{$@{fault@}}.  This bug can often
11101 be worked around by omitting the braces: @code{$variable}.  The bug was fixed in
11102 @samp{ksh93g} (1998-04-30) but as of 2006 many operating systems were
11103 still shipping older versions with the bug.
11105 Many older shells (including the Bourne shell) implement here-documents
11106 inefficiently.  In particular, some shells can be extremely inefficient when
11107 a single statement contains many here-documents.  For instance if your
11108 @file{configure.ac} includes something like:
11110 @example
11111 @group
11112 if <cross_compiling>; then
11113   assume this and that
11114 else
11115   check this
11116   check that
11117   check something else
11118   @dots{}
11119   on and on forever
11120   @dots{}
11122 @end group
11123 @end example
11125 A shell parses the whole @code{if}/@code{fi} construct, creating
11126 temporary files for each here-document in it.  Some shells create links
11127 for such here-documents on every @code{fork}, so that the clean-up code
11128 they had installed correctly removes them.  It is creating the links
11129 that can take the shell forever.
11131 Moving the tests out of the @code{if}/@code{fi}, or creating multiple
11132 @code{if}/@code{fi} constructs, would improve the performance
11133 significantly.  Anyway, this kind of construct is not exactly the
11134 typical use of Autoconf.  In fact, it's even not recommended, because M4
11135 macros can't look into shell conditionals, so we may fail to expand a
11136 macro when it was expanded before in a conditional path, and the
11137 condition turned out to be false at runtime, and we end up not
11138 executing the macro at all.
11140 @node File Descriptors
11141 @section File Descriptors
11142 @cindex Descriptors
11143 @cindex File descriptors
11144 @cindex Shell file descriptors
11146 Most shells, if not all (including Bash, Zsh, Ash), output traces on
11147 stderr, even for subshells.  This might result in undesirable content
11148 if you meant to capture the standard-error output of the inner command:
11150 @example
11151 $ @kbd{ash -x -c '(eval "echo foo >&2") 2>stderr'}
11152 $ @kbd{cat stderr}
11153 + eval echo foo >&2
11154 + echo foo
11156 $ @kbd{bash -x -c '(eval "echo foo >&2") 2>stderr'}
11157 $ @kbd{cat stderr}
11158 + eval 'echo foo >&2'
11159 ++ echo foo
11161 $ @kbd{zsh -x -c '(eval "echo foo >&2") 2>stderr'}
11162 @i{# Traces on startup files deleted here.}
11163 $ @kbd{cat stderr}
11164 +zsh:1> eval echo foo >&2
11165 +zsh:1> echo foo
11167 @end example
11169 @noindent
11170 One workaround is to grep out uninteresting lines, hoping not to remove
11171 good ones.
11173 If you intend to redirect both standard error and standard output,
11174 redirect standard output first.  This works better with @acronym{HP-UX},
11175 since its shell mishandles tracing if standard error is redirected
11176 first:
11178 @example
11179 $ @kbd{sh -x -c ': 2>err >out'}
11180 + :
11181 + 2> err $ @kbd{cat err}
11182 1> out
11183 @end example
11185 Don't try to redirect the standard error of a command substitution.  It
11186 must be done @emph{inside} the command substitution.  When running
11187 @samp{: `cd /zorglub` 2>/dev/null} expect the error message to
11188 escape, while @samp{: `cd /zorglub 2>/dev/null`} works properly.
11190 It is worth noting that Zsh (but not Ash nor Bash) makes it possible
11191 in assignments though: @samp{foo=`cd /zorglub` 2>/dev/null}.
11193 Don't redirect the same file descriptor several times, as you are doomed
11194 to failure under Ultrix.
11196 @example
11197 ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995
11198 UWS V4.4 (Rev. 11)
11199 $ @kbd{eval 'echo matter >fullness' >void}
11200 illegal io
11201 $ @kbd{eval '(echo matter >fullness)' >void}
11202 illegal io
11203 $ @kbd{(eval '(echo matter >fullness)') >void}
11204 Ambiguous output redirect.
11205 @end example
11207 @noindent
11208 In each case the expected result is of course @file{fullness} containing
11209 @samp{matter} and @file{void} being empty.
11211 Don't rely on file descriptors 0, 1, and 2 remaining closed in a
11212 subsidiary program.  If any of these descriptors is closed, the
11213 operating system may open an unspecified file for the descriptor in the
11214 new process image.  Posix says this may be done only if the subsidiary
11215 program is set-user-ID or set-group-ID, but @acronym{HP-UX} 11.23 does it even for
11216 ordinary programs.
11218 Don't rely on open file descriptors being open in child processes.  In
11219 @command{ksh}, file descriptors above 2 which are opened using
11220 @samp{exec @var{n}>file} are closed by a subsequent @samp{exec} (such as
11221 that involved in the fork-and-exec which runs a program or script).
11222 Thus, using @command{sh}, we have:
11224 @example
11225 $ @kbd{cat ./descrips}
11226 #!/bin/sh -
11227 echo hello >&5
11228 $ @kbd{exec 5>t}
11229 $ @kbd{./descrips}
11230 $ @kbd{cat t}
11232 hello
11233 @end example
11235 @noindent
11236 But using ksh:
11238 @example
11239 $ @kbd{exec 5>t}
11240 $ @kbd{./descrips}
11241 hello
11242 $ @kbd{cat t}
11244 @end example
11246 @noindent
11247 Within the process which runs the @samp{descrips} script, file
11248 descriptor 5 is closed.
11250 @acronym{DOS} variants cannot rename or remove open files, such as in
11251 @samp{mv foo bar >foo} or @samp{rm foo >foo}, even though this is
11252 perfectly portable among Posix hosts.
11254 A few ancient systems reserved some file descriptors.  By convention,
11255 file descriptor 3 was opened to @file{/dev/tty} when you logged into
11256 Eighth Edition (1985) through Tenth Edition Unix (1989).  File
11257 descriptor 4 had a special use on the Stardent/Kubota Titan (circa
11258 1990), though we don't now remember what it was.  Both these systems are
11259 obsolete, so it's now safe to treat file descriptors 3 and 4 like any
11260 other file descriptors.
11262 @node File System Conventions
11263 @section File System Conventions
11264 @cindex File system conventions
11266 Autoconf uses shell-script processing extensively, so the file names
11267 that it processes should not contain characters that are special to the
11268 shell.  Special characters include space, tab, newline, @sc{nul}, and
11269 the following:
11271 @example
11272 " # $ & ' ( ) * ; < = > ? [ \ ` |
11273 @end example
11275 Also, file names should not begin with @samp{~} or @samp{-}, and should
11276 contain neither @samp{-} immediately after @samp{/} nor @samp{~}
11277 immediately after @samp{:}.  On Posix-like platforms, directory names
11278 should not contain @samp{:}, as this runs afoul of @samp{:} used as the
11279 path separator.
11281 These restrictions apply not only to the files that you distribute, but
11282 also to the absolute file names of your source, build, and destination
11283 directories.
11285 On some Posix-like platforms, @samp{!} and @samp{^} are special too, so
11286 they should be avoided.
11288 Posix lets implementations treat leading @file{//} specially, but
11289 requires leading @file{///} and beyond to be equivalent to @file{/}.
11290 Most Unix variants treat @file{//} like @file{/}.  However, some treat
11291 @file{//} as a ``super-root'' that can provide access to files that are
11292 not otherwise reachable from @file{/}.  The super-root tradition began
11293 with Apollo Domain/OS, which died out long ago, but unfortunately Cygwin
11294 has revived it.
11296 While @command{autoconf} and friends are usually run on some Posix
11297 variety, they can be used on other systems, most notably @acronym{DOS}
11298 variants.  This impacts several assumptions regarding file names.
11300 @noindent
11301 For example, the following code:
11303 @example
11304 case $foo_dir in
11305   /*) # Absolute
11306      ;;
11307   *)
11308      foo_dir=$dots$foo_dir ;;
11309 esac
11310 @end example
11312 @noindent
11313 fails to properly detect absolute file names on those systems, because
11314 they can use a drivespec, and usually use a backslash as directory
11315 separator.  If you want to be portable to @acronym{DOS} variants (at the
11316 price of rejecting valid but oddball Posix file names like @file{a:\b}),
11317 you can check for absolute file names like this:
11319 @example
11320 case $foo_dir in
11321   [\\/]* | ?:[\\/]* ) # Absolute
11322      ;;
11323   *)
11324      foo_dir=$dots$foo_dir ;;
11325 esac
11326 @end example
11328 @noindent
11329 Make sure you quote the brackets if appropriate and keep the backslash as
11330 first character (@pxref{Limitations of Builtins}).
11332 Also, because the colon is used as part of a drivespec, these systems don't
11333 use it as path separator.  When creating or accessing paths, you can use the
11334 @code{PATH_SEPARATOR} output variable instead.  @command{configure} sets this
11335 to the appropriate value (@samp{:} or @samp{;}) when it starts up.
11337 File names need extra care as well.  While @acronym{DOS} variants
11338 that are Posixy enough to run @command{autoconf} (such as @acronym{DJGPP})
11339 are usually able to handle long file names properly, there are still
11340 limitations that can seriously break packages.  Several of these issues
11341 can be easily detected by the
11342 @uref{ftp://ftp.gnu.org/gnu/non-gnu/doschk/doschk-1.1.tar.gz, doschk}
11343 package.
11345 A short overview follows; problems are marked with @sc{sfn}/@sc{lfn} to
11346 indicate where they apply: @sc{sfn} means the issues are only relevant to
11347 plain @acronym{DOS}, not to @acronym{DOS} under Microsoft Windows
11348 variants, while @sc{lfn} identifies problems that exist even under
11349 Microsoft Windows variants.
11351 @table @asis
11352 @item No multiple dots (@sc{sfn})
11353 @acronym{DOS} cannot handle multiple dots in file names.  This is an especially
11354 important thing to remember when building a portable configure script,
11355 as @command{autoconf} uses a .in suffix for template files.
11357 This is perfectly OK on Posix variants:
11359 @example
11360 AC_CONFIG_HEADERS([config.h])
11361 AC_CONFIG_FILES([source.c foo.bar])
11362 AC_OUTPUT
11363 @end example
11365 @noindent
11366 but it causes problems on @acronym{DOS}, as it requires @samp{config.h.in},
11367 @samp{source.c.in} and @samp{foo.bar.in}.  To make your package more portable
11368 to @acronym{DOS}-based environments, you should use this instead:
11370 @example
11371 AC_CONFIG_HEADERS([config.h:config.hin])
11372 AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in])
11373 AC_OUTPUT
11374 @end example
11376 @item No leading dot (@sc{sfn})
11377 @acronym{DOS} cannot handle file names that start with a dot.  This is usually
11378 not important for @command{autoconf}.
11380 @item Case insensitivity (@sc{lfn})
11381 @acronym{DOS} is case insensitive, so you cannot, for example, have both a
11382 file called @samp{INSTALL} and a directory called @samp{install}.  This
11383 also affects @command{make}; if there's a file called @samp{INSTALL} in
11384 the directory, @samp{make install} does nothing (unless the
11385 @samp{install} target is marked as PHONY).
11387 @item The 8+3 limit (@sc{sfn})
11388 Because the @acronym{DOS} file system only stores the first 8 characters of
11389 the file name and the first 3 of the extension, those must be unique.
11390 That means that @file{foobar-part1.c}, @file{foobar-part2.c} and
11391 @file{foobar-prettybird.c} all resolve to the same file name
11392 (@file{FOOBAR-P.C}).  The same goes for @file{foo.bar} and
11393 @file{foo.bartender}.
11395 The 8+3 limit is not usually a problem under Microsoft Windows, as it
11396 uses numeric
11397 tails in the short version of file names to make them unique.  However, a
11398 registry setting can turn this behavior off.  While this makes it
11399 possible to share file trees containing long file names between @sc{sfn}
11400 and @sc{lfn} environments, it also means the above problem applies there
11401 as well.
11403 @item Invalid characters (@sc{lfn})
11404 Some characters are invalid in @acronym{DOS} file names, and should therefore
11405 be avoided.  In a @sc{lfn} environment, these are @samp{/}, @samp{\},
11406 @samp{?}, @samp{*}, @samp{:}, @samp{<}, @samp{>}, @samp{|} and @samp{"}.
11407 In a @sc{sfn} environment, other characters are also invalid.  These
11408 include @samp{+}, @samp{,}, @samp{[} and @samp{]}.
11410 @item Invalid names (@sc{lfn})
11411 Some @acronym{DOS} file names are reserved, and cause problems if you
11412 try to use files with those names.  These names include @file{CON},
11413 @file{AUX}, @file{COM1}, @file{COM2}, @file{COM3}, @file{COM4},
11414 @file{LPT1}, @file{LPT2}, @file{LPT3}, @file{NUL}, and @file{PRN}.
11415 File names are case insensitive, so even names like
11416 @file{aux/config.guess} are disallowed.
11418 @end table
11420 @node Shell Substitutions
11421 @section Shell Substitutions
11422 @cindex Shell substitutions
11424 Contrary to a persistent urban legend, the Bourne shell does not
11425 systematically split variables and back-quoted expressions, in particular
11426 on the right-hand side of assignments and in the argument of @code{case}.
11427 For instance, the following code:
11429 @example
11430 case "$given_srcdir" in
11431 .)  top_srcdir="`echo "$dots" | sed 's,/$,,'`" ;;
11432 *)  top_srcdir="$dots$given_srcdir" ;;
11433 esac
11434 @end example
11436 @noindent
11437 is more readable when written as:
11439 @example
11440 case $given_srcdir in
11441 .)  top_srcdir=`echo "$dots" | sed 's,/$,,'` ;;
11442 *)  top_srcdir=$dots$given_srcdir ;;
11443 esac
11444 @end example
11446 @noindent
11447 and in fact it is even @emph{more} portable: in the first case of the
11448 first attempt, the computation of @code{top_srcdir} is not portable,
11449 since not all shells properly understand @code{"`@dots{}"@dots{}"@dots{}`"}.
11450 Worse yet, not all shells understand @code{"`@dots{}\"@dots{}\"@dots{}`"}
11451 the same way.  There is just no portable way to use double-quoted
11452 strings inside double-quoted back-quoted expressions (pfew!).
11454 @table @code
11455 @item $@@
11456 @cindex @samp{"$@@"}
11457 One of the most famous shell-portability issues is related to
11458 @samp{"$@@"}.  When there are no positional arguments, Posix says
11459 that @samp{"$@@"} is supposed to be equivalent to nothing, but the
11460 original Unix version 7 Bourne shell treated it as equivalent to
11461 @samp{""} instead, and this behavior survives in later implementations
11462 like Digital Unix 5.0.
11464 The traditional way to work around this portability problem is to use
11465 @samp{$@{1+"$@@"@}}.  Unfortunately this method does not work with
11466 Zsh (3.x and 4.x), which is used on Mac OS X@.  When emulating
11467 the Bourne shell, Zsh performs word splitting on @samp{$@{1+"$@@"@}}:
11469 @example
11470 zsh $ @kbd{emulate sh}
11471 zsh $ @kbd{for i in "$@@"; do echo $i; done}
11472 Hello World
11474 zsh $ @kbd{for i in $@{1+"$@@"@}; do echo $i; done}
11475 Hello
11476 World
11478 @end example
11480 @noindent
11481 Zsh handles plain @samp{"$@@"} properly, but we can't use plain
11482 @samp{"$@@"} because of the portability problems mentioned above.
11483 One workaround relies on Zsh's ``global aliases'' to convert
11484 @samp{$@{1+"$@@"@}} into @samp{"$@@"} by itself:
11486 @example
11487 test "$@{ZSH_VERSION+set@}" = set && alias -g '$@{1+"$@@"@}'='"$@@"'
11488 @end example
11490 A more conservative workaround is to avoid @samp{"$@@"} if it is
11491 possible that there may be no positional arguments.  For example,
11492 instead of:
11494 @example
11495 cat conftest.c "$@@"
11496 @end example
11498 you can use this instead:
11500 @example
11501 case $# in
11502 0) cat conftest.c;;
11503 *) cat conftest.c "$@@";;
11504 esac
11505 @end example
11507 Autoconf macros often use the @command{set} command to update
11508 @samp{$@@}, so if you are writing shell code intended for
11509 @command{configure} you should not assume that the value of @samp{$@@}
11510 persists for any length of time.
11513 @item $@{10@}
11514 @cindex positional parameters
11515 The 10th, 11th, @dots{} positional parameters can be accessed only after
11516 a @code{shift}.  The 7th Edition shell reported an error if given
11517 @code{$@{10@}}, and
11518 Solaris 10 @command{/bin/sh} still acts that way:
11520 @example
11521 $ @kbd{set 1 2 3 4 5 6 7 8 9 10}
11522 $ @kbd{echo $@{10@}}
11523 bad substitution
11524 @end example
11526 @item $@{@var{var}:-@var{value}@}
11527 @c Info cannot handle `:' in index entries.
11528 @c @cindex $@{@var{var}:-@var{value}@}
11529 Old @acronym{BSD} shells, including the Ultrix @code{sh}, don't accept the
11530 colon for any shell substitution, and complain and die.
11532 @item $@{@var{var}=@var{literal}@}
11533 @cindex $@{@var{var}=@var{literal}@}
11534 Be sure to quote:
11536 @example
11537 : $@{var='Some words'@}
11538 @end example
11540 @noindent
11541 otherwise some shells, such as on Digital Unix V 5.0, die because
11542 of a ``bad substitution''.
11544 @sp 1
11546 Solaris @command{/bin/sh} has a frightening bug in its interpretation
11547 of this.  Imagine you need set a variable to a string containing
11548 @samp{@}}.  This @samp{@}} character confuses Solaris @command{/bin/sh}
11549 when the affected variable was already set.  This bug can be exercised
11550 by running:
11552 @example
11553 $ @kbd{unset foo}
11554 $ @kbd{foo=$@{foo='@}'@}}
11555 $ @kbd{echo $foo}
11557 $ @kbd{foo=$@{foo='@}'   # no error; this hints to what the bug is}
11558 $ @kbd{echo $foo}
11560 $ @kbd{foo=$@{foo='@}'@}}
11561 $ @kbd{echo $foo}
11562 @}@}
11563  ^ ugh!
11564 @end example
11566 It seems that @samp{@}} is interpreted as matching @samp{$@{}, even
11567 though it is enclosed in single quotes.  The problem doesn't happen
11568 using double quotes.
11570 @item $@{@var{var}=@var{expanded-value}@}
11571 @cindex $@{@var{var}=@var{expanded-value}@}
11572 On Ultrix,
11573 running
11575 @example
11576 default="yu,yaa"
11577 : $@{var="$default"@}
11578 @end example
11580 @noindent
11581 sets @var{var} to @samp{M-yM-uM-,M-yM-aM-a}, i.e., the 8th bit of
11582 each char is set.  You don't observe the phenomenon using a simple
11583 @samp{echo $var} since apparently the shell resets the 8th bit when it
11584 expands $var.  Here are two means to make this shell confess its sins:
11586 @example
11587 $ @kbd{cat -v <<EOF
11588 $var
11589 EOF}
11590 @end example
11592 @noindent
11595 @example
11596 $ @kbd{set | grep '^var=' | cat -v}
11597 @end example
11599 One classic incarnation of this bug is:
11601 @example
11602 default="a b c"
11603 : $@{list="$default"@}
11604 for c in $list; do
11605   echo $c
11606 done
11607 @end example
11609 @noindent
11610 You'll get @samp{a b c} on a single line.  Why?  Because there are no
11611 spaces in @samp{$list}: there are @samp{M- }, i.e., spaces with the 8th
11612 bit set, hence no IFS splitting is performed!!!
11614 One piece of good news is that Ultrix works fine with @samp{:
11615 $@{list=$default@}}; i.e., if you @emph{don't} quote.  The bad news is
11616 then that @acronym{QNX} 4.25 then sets @var{list} to the @emph{last} item of
11617 @var{default}!
11619 The portable way out consists in using a double assignment, to switch
11620 the 8th bit twice on Ultrix:
11622 @example
11623 list=$@{list="$default"@}
11624 @end example
11626 @noindent
11627 @dots{}but beware of the @samp{@}} bug from Solaris (see above).  For safety,
11628 use:
11630 @example
11631 test "$@{var+set@}" = set || var=@var{@{value@}}
11632 @end example
11635 @item `@var{commands}`
11636 @cindex `@var{commands}`
11637 @cindex Command Substitution
11638 Posix requires shells to trim all trailing newlines from command
11639 output before substituting it, so assignments like
11640 @samp{dir=`echo "$file" | tr a A`} do not work as expected if
11641 @samp{$file} ends in a newline.
11643 While in general it makes no sense, do not substitute a single builtin
11644 with side effects, because Ash 0.2, trying to optimize, does not fork a
11645 subshell to perform the command.
11647 For instance, if you wanted to check that @command{cd} is silent, do not
11648 use @samp{test -z "`cd /`"} because the following can happen:
11650 @example
11651 $ @kbd{pwd}
11652 /tmp
11653 $ @kbd{test -z "`cd /`" && pwd}
11655 @end example
11657 @noindent
11658 The result of @samp{foo=`exit 1`} is left as an exercise to the reader.
11660 The MSYS shell leaves a stray byte in the expansion of a double-quoted
11661 command substitution of a native program, if the end of the substution
11662 is not aligned with the end of the double quote.  This may be worked
11663 around by inserting another pair of quotes:
11665 @example
11666 $ @kbd{echo "`printf 'foo\r\n'` bar" > broken}
11667 $ @kbd{echo "`printf 'foo\r\n'`"" bar" | cmp - broken}
11668 - broken differ: char 4, line 1
11669 @end example
11672 @item $(@var{commands})
11673 @cindex $(@var{commands})
11674 This construct is meant to replace @samp{`@var{commands}`},
11675 and it has most of the problems listed under @code{`@var{commands}`}.
11677 This construct can be
11678 nested while this is impossible to do portably with back quotes.
11679 Unfortunately it is not yet universally supported.  Most notably, even recent
11680 releases of Solaris don't support it:
11682 @example
11683 $ @kbd{showrev -c /bin/sh | grep version}
11684 Command version: SunOS 5.10 Generic 121004-01 Oct 2005
11685 $ @kbd{echo $(echo blah)}
11686 syntax error: `(' unexpected
11687 @end example
11689 @noindent
11690 nor does @sc{irix} 6.5's Bourne shell:
11691 @example
11692 $ @kbd{uname -a}
11693 IRIX firebird-image 6.5 07151432 IP22
11694 $ @kbd{echo $(echo blah)}
11695 $(echo blah)
11696 @end example
11698 If you do use @samp{$(@var{commands})}, make sure that the commands
11699 do not start with a parenthesis, as that would cause confusion with
11700 a different notation @samp{$((@var{expression}))} that in modern
11701 shells is an arithmetic expression not a command.  To avoid the
11702 confusion, insert a space between the two opening parentheses.
11704 Avoid @var{commands} that contain unbalanced parentheses in
11705 here-documents, comments, or case statement patterns, as many shells
11706 mishandle them.  For example, Bash 3.1, @samp{ksh88}, @command{pdksh}
11707 5.2.14, and Zsh 4.2.6 all mishandle the following valid command:
11709 @example
11710 echo $(case x in x) echo hello;; esac)
11711 @end example
11713 @item ^
11714 @cindex ^ quoting
11715 Always quote @samp{^}, otherwise traditional shells such as
11716 @command{/bin/sh} on Solaris 10 treat this like @samp{|}.
11718 @end table
11721 @node Assignments
11722 @section Assignments
11723 @cindex Shell assignments
11725 When setting several variables in a row, be aware that the order of the
11726 evaluation is undefined.  For instance @samp{foo=1 foo=2; echo $foo}
11727 gives @samp{1} with Solaris @command{/bin/sh}, but @samp{2} with Bash.
11728 You must use
11729 @samp{;} to enforce the order: @samp{foo=1; foo=2; echo $foo}.
11731 Don't rely on the following to find @file{subdir/program}:
11733 @example
11734 PATH=subdir$PATH_SEPARATOR$PATH program
11735 @end example
11737 @noindent
11738 as this does not work with Zsh 3.0.6.  Use something like this
11739 instead:
11741 @example
11742 (PATH=subdir$PATH_SEPARATOR$PATH; export PATH; exec program)
11743 @end example
11745 Don't rely on the exit status of an assignment: Ash 0.2 does not change
11746 the status and propagates that of the last statement:
11748 @example
11749 $ @kbd{false || foo=bar; echo $?}
11751 $ @kbd{false || foo=`:`; echo $?}
11753 @end example
11755 @noindent
11756 and to make things even worse, @acronym{QNX} 4.25 just sets the exit status
11757 to 0 in any case:
11759 @example
11760 $ @kbd{foo=`exit 1`; echo $?}
11762 @end example
11764 To assign default values, follow this algorithm:
11766 @enumerate
11767 @item
11768 If the default value is a literal and does not contain any closing
11769 brace, use:
11771 @example
11772 : $@{var='my literal'@}
11773 @end example
11775 @item
11776 If the default value contains no closing brace, has to be expanded, and
11777 the variable being initialized is not intended to be IFS-split
11778 (i.e., it's not a list), then use:
11780 @example
11781 : $@{var="$default"@}
11782 @end example
11784 @item
11785 If the default value contains no closing brace, has to be expanded, and
11786 the variable being initialized is intended to be IFS-split (i.e., it's a list),
11787 then use:
11789 @example
11790 var=$@{var="$default"@}
11791 @end example
11793 @item
11794 If the default value contains a closing brace, then use:
11796 @example
11797 test "$@{var+set@}" = set || var="has a '@}'"
11798 @end example
11799 @end enumerate
11801 In most cases @samp{var=$@{var="$default"@}} is fine, but in case of
11802 doubt, just use the last form.  @xref{Shell Substitutions}, items
11803 @samp{$@{@var{var}:-@var{value}@}} and @samp{$@{@var{var}=@var{value}@}}
11804 for the rationale.
11806 @node Parentheses
11807 @section Parentheses in Shell Scripts
11808 @cindex Shell parentheses
11810 Beware of two opening parentheses in a row, as some shell
11811 implementations mishandle them.  For example, @samp{pdksh} 5.2.14
11812 misparses the following code:
11814 @example
11815 if ((true) || false); then
11816   echo ok
11818 @end example
11820 @noindent
11821 To work around this problem, insert a space between the two opening
11822 parentheses.  There is a similar problem and workaround with
11823 @samp{$((}; see @ref{Shell Substitutions}.
11825 Posix requires support for @code{case} patterns with opening
11826 parentheses like this:
11828 @example
11829 case $file_name in
11830 (*.c) echo "C source code";;
11831 esac
11832 @end example
11834 @noindent
11835 but the @code{(} in this example is not portable to many older Bourne
11836 shell implementations.  It can be omitted safely.
11838 @node Slashes
11839 @section Slashes in Shell Scripts
11840 @cindex Shell slashes
11842 Unpatched Tru64 5.1 @command{sh} omits the last slash of command-line
11843 arguments that contain two trailing slashes:
11845 @example
11846 $ @kbd{echo / // /// //// .// //.}
11847 / / // /// ./ //.
11848 $ @kbd{x=//}
11849 $ @kbd{eval "echo \$x"}
11851 $ @kbd{set -x}
11852 $ @kbd{echo abc | tr -t ab //}
11853 + echo abc
11854 + tr -t ab /
11856 @end example
11858 However, our understanding is that patches are available, so perhaps
11859 it's not worth worrying about working around this horrendous bug.
11861 @node Special Shell Variables
11862 @section Special Shell Variables
11863 @cindex Shell variables
11864 @cindex Special shell variables
11866 Some shell variables should not be used, since they can have a deep
11867 influence on the behavior of the shell.  In order to recover a sane
11868 behavior from the shell, some variables should be unset, but
11869 @command{unset} is not portable (@pxref{Limitations of Builtins}) and a
11870 fallback value is needed.
11872 As a general rule, shell variable names containing a lower-case letter
11873 are safe; you can define and use these variables without worrying about
11874 their effect on the underlying system, and without worrying about
11875 whether the shell changes them unexpectedly.  (The exception is the
11876 shell variable @code{status}, as described below.)
11878 Here is a list of names that are known to cause trouble.  This list is
11879 not exhaustive, but you should be safe if you avoid the name
11880 @code{status} and names containing only upper-case letters and
11881 underscores.
11883 @c Alphabetical order, case insensitive, `A' before `a'.
11884 @table @code
11885 @item _
11886 Many shells reserve @samp{$_} for various purposes, e.g., the name of
11887 the last command executed.
11889 @item BIN_SH
11890 @evindex BIN_SH
11891 In Tru64, if @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of
11892 the standard shell conform to Posix.
11893 Autoconf-generated scripts export this variable when they start up.
11895 @item CDPATH
11896 @evindex CDPATH
11897 When this variable is set it specifies a list of directories to search
11898 when invoking @code{cd} with a relative file name that did not start
11899 with @samp{./} or @samp{../}.  Posix
11900 1003.1-2001 says that if a nonempty directory name from @env{CDPATH}
11901 is used successfully, @code{cd} prints the resulting absolute
11902 file name.  Unfortunately this output can break idioms like
11903 @samp{abs=`cd src && pwd`} because @code{abs} receives the name twice.
11904 Also, many shells do not conform to this part of Posix; for
11905 example, @command{zsh} prints the result only if a directory name
11906 other than @file{.} was chosen from @env{CDPATH}.
11908 In practice the shells that have this problem also support
11909 @command{unset}, so you can work around the problem as follows:
11911 @example
11912 (unset CDPATH) >/dev/null 2>&1 && unset CDPATH
11913 @end example
11915 You can also avoid output by ensuring that your directory name is
11916 absolute or anchored at @samp{./}, as in @samp{abs=`cd ./src && pwd`}.
11918 Autoconf-generated scripts automatically unset @env{CDPATH} if
11919 possible, so you need not worry about this problem in those scripts.
11921 @item DUALCASE
11922 @evindex DUALCASE
11923 In the MKS shell, case statements and file name generation are
11924 case-insensitive unless @env{DUALCASE} is nonzero.
11925 Autoconf-generated scripts export this variable when they start up.
11927 @item ENV
11928 @itemx MAIL
11929 @itemx MAILPATH
11930 @itemx PS1
11931 @itemx PS2
11932 @itemx PS4
11933 @evindex ENV
11934 @evindex MAIL
11935 @evindex MAILPATH
11936 @evindex PS1
11937 @evindex PS2
11938 @evindex PS4
11939 These variables should not matter for shell scripts, since they are
11940 supposed to affect only interactive shells.  However, at least one
11941 shell (the pre-3.0 @sc{uwin} Korn shell) gets confused about
11942 whether it is interactive, which means that (for example) a @env{PS1}
11943 with a side effect can unexpectedly modify @samp{$?}.  To work around
11944 this bug, Autoconf-generated scripts do something like this:
11946 @example
11947 (unset ENV) >/dev/null 2>&1 && unset ENV MAIL MAILPATH
11948 PS1='$ '
11949 PS2='> '
11950 PS4='+ '
11951 @end example
11953 @item IFS
11954 @evindex IFS
11955 Long ago, shell scripts inherited @env{IFS} from the environment,
11956 but this caused many problems so modern shells ignore any environment
11957 settings for @env{IFS}.
11959 Don't set the first character of @code{IFS} to backslash.  Indeed,
11960 Bourne shells use the first character (backslash) when joining the
11961 components in @samp{"$@@"} and some shells then reinterpret (!)@: the
11962 backslash escapes, so you can end up with backspace and other strange
11963 characters.
11965 The proper value for @code{IFS} (in regular code, not when performing
11966 splits) is @samp{@key{SPC}@key{TAB}@key{RET}}.  The first character is
11967 especially important, as it is used to join the arguments in @samp{$*};
11968 however, note that traditional shells, but also bash-2.04, fail to adhere
11969 to this and join with a space anyway.
11971 @item LANG
11972 @itemx LC_ALL
11973 @itemx LC_COLLATE
11974 @itemx LC_CTYPE
11975 @itemx LC_MESSAGES
11976 @itemx LC_MONETARY
11977 @itemx LC_NUMERIC
11978 @itemx LC_TIME
11979 @evindex LANG
11980 @evindex LC_ALL
11981 @evindex LC_COLLATE
11982 @evindex LC_CTYPE
11983 @evindex LC_MESSAGES
11984 @evindex LC_MONETARY
11985 @evindex LC_NUMERIC
11986 @evindex LC_TIME
11988 Autoconf-generated scripts normally set all these variables to
11989 @samp{C} because so much configuration code assumes the C locale and
11990 Posix requires that locale environment variables be set to
11991 @samp{C} if the C locale is desired.  However, some older, nonstandard
11992 systems (notably @acronym{SCO}) break if locale environment variables
11993 are set to @samp{C}, so when running on these systems
11994 Autoconf-generated scripts unset the variables instead.
11996 @item LANGUAGE
11997 @evindex LANGUAGE
11999 @env{LANGUAGE} is not specified by Posix, but it is a @acronym{GNU}
12000 extension that overrides @env{LC_ALL} in some cases, so
12001 Autoconf-generated scripts set it too.
12003 @item LC_ADDRESS
12004 @itemx LC_IDENTIFICATION
12005 @itemx LC_MEASUREMENT
12006 @itemx LC_NAME
12007 @itemx LC_PAPER
12008 @itemx LC_TELEPHONE
12009 @evindex LC_ADDRESS
12010 @evindex LC_IDENTIFICATION
12011 @evindex LC_MEASUREMENT
12012 @evindex LC_NAME
12013 @evindex LC_PAPER
12014 @evindex LC_TELEPHONE
12016 These locale environment variables are @acronym{GNU} extensions.  They
12017 are treated like their Posix brethren (@env{LC_COLLATE},
12018 etc.)@: as described above.
12020 @item LINENO
12021 Most modern shells provide the current line number in @code{LINENO}.
12022 Its value is the line number of the beginning of the current command.
12023 Autoconf attempts to execute @command{configure} with a shell that
12024 supports @code{LINENO}.
12025 If no such shell is available, it attempts to implement @code{LINENO}
12026 with a Sed prepass that replaces each instance of the string
12027 @code{$LINENO} (not followed by an alphanumeric character) with the
12028 line's number.
12030 You should not rely on @code{LINENO} within @command{eval}, as the
12031 behavior differs in practice.  Also, the possibility of the Sed
12032 prepass means that you should not rely on @code{$LINENO} when quoted,
12033 when in here-documents, or when in long commands that cross line
12034 boundaries.  Subshells should be OK, though.  In the following
12035 example, lines 1, 6, and 9 are portable, but the other instances of
12036 @code{LINENO} are not:
12038 @example
12039 @group
12040 $ @kbd{cat lineno}
12041 echo 1. $LINENO
12042 cat <<EOF
12043 3. $LINENO
12044 4. $LINENO
12046 ( echo 6. $LINENO )
12047 eval 'echo 7. $LINENO'
12048 echo 8. '$LINENO'
12049 echo 9. $LINENO '
12050 10.' $LINENO
12051 @end group
12052 @group
12053 $ @kbd{bash-2.05 lineno}
12054 1. 1
12055 3. 2
12056 4. 2
12057 6. 6
12058 7. 1
12059 8. $LINENO
12060 9. 9
12061 10. 9
12062 @end group
12063 @group
12064 $ @kbd{zsh-3.0.6 lineno}
12065 1. 1
12066 3. 2
12067 4. 2
12068 6. 6
12069 7. 7
12070 8. $LINENO
12071 9. 9
12072 10. 9
12073 @end group
12074 @group
12075 $ @kbd{pdksh-5.2.14 lineno}
12076 1. 1
12077 3. 2
12078 4. 2
12079 6. 6
12080 7. 0
12081 8. $LINENO
12082 9. 9
12083 10. 9
12084 @end group
12085 @group
12086 $ @kbd{sed '=' <lineno |}
12087 > @kbd{  sed '}
12088 > @kbd{    N}
12089 > @kbd{    s,$,-,}
12090 > @kbd{    t loop}
12091 > @kbd{    :loop}
12092 > @kbd{    s,^\([0-9]*\)\(.*\)[$]LINENO\([^a-zA-Z0-9_]\),\1\2\1\3,}
12093 > @kbd{    t loop}
12094 > @kbd{    s,-$,,}
12095 > @kbd{    s,^[0-9]*\n,,}
12096 > @kbd{  ' |}
12097 > @kbd{  sh}
12098 1. 1
12099 3. 3
12100 4. 4
12101 6. 6
12102 7. 7
12103 8. 8
12104 9. 9
12105 10. 10
12106 @end group
12107 @end example
12109 @item NULLCMD
12110 @evindex NULLCMD
12111 When executing the command @samp{>foo}, @command{zsh} executes
12112 @samp{$NULLCMD >foo} unless it is operating in Bourne shell
12113 compatibility mode and the @command{zsh} version is newer
12114 than 3.1.6-dev-18.  If you are using an older @command{zsh}
12115 and forget to set @env{NULLCMD},
12116 your script might be suspended waiting for data on its standard input.
12118 @item PATH_SEPARATOR
12119 @evindex PATH_SEPARATOR
12120 On @acronym{DJGPP} systems, the @env{PATH_SEPARATOR} environment
12121 variable can be set to either @samp{:} or @samp{;} to control the path
12122 separator Bash uses to set up certain environment variables (such as
12123 @env{PATH}).  You can set this variable to @samp{;} if you want
12124 @command{configure} to use @samp{;} as a separator; this might be useful
12125 if you plan to use non-Posix shells to execute files.  @xref{File System
12126 Conventions}, for more information about @code{PATH_SEPARATOR}.
12128 @item PWD
12129 @evindex PWD
12130 Posix 1003.1-2001 requires that @command{cd} and
12131 @command{pwd} must update the @env{PWD} environment variable to point
12132 to the logical name of the current directory, but traditional shells
12133 do not support this.  This can cause confusion if one shell instance
12134 maintains @env{PWD} but a subsidiary and different shell does not know
12135 about @env{PWD} and executes @command{cd}; in this case @env{PWD}
12136 points to the wrong directory.  Use @samp{`pwd`} rather than
12137 @samp{$PWD}.
12139 @item RANDOM
12140 Many shells provide @code{RANDOM}, a variable that returns a different
12141 integer each time it is used.  Most of the time, its value does not
12142 change when it is not used, but on @sc{irix} 6.5 the value changes all
12143 the time.  This can be observed by using @command{set}.  It is common
12144 practice to use @code{$RANDOM} as part of a file name, but code
12145 shouldn't rely on @code{$RANDOM} expanding to a nonempty string.
12147 @item status
12148 This variable is an alias to @samp{$?} for @code{zsh} (at least 3.1.6),
12149 hence read-only.  Do not use it.
12150 @end table
12152 @node Limitations of Builtins
12153 @section Limitations of Shell Builtins
12154 @cindex Shell builtins
12155 @cindex Limitations of shell builtins
12157 No, no, we are serious: some shells do have limitations!  :)
12159 You should always keep in mind that any builtin or command may support
12160 options, and therefore differ in behavior with arguments
12161 starting with a dash.  For instance, the innocent @samp{echo "$word"}
12162 can give unexpected results when @code{word} starts with a dash.  It is
12163 often possible to avoid this problem using @samp{echo "x$word"}, taking
12164 the @samp{x} into account later in the pipe.
12166 @table @asis
12167 @item @command{.}
12168 @prindex @command{.}
12169 Use @command{.} only with regular files (use @samp{test -f}).  Bash
12170 2.03, for instance, chokes on @samp{. /dev/null}.  Also, remember that
12171 @command{.} uses @env{PATH} if its argument contains no slashes, so if
12172 you want to use @command{.} on a file @file{foo} in the current
12173 directory, you must use @samp{. ./foo}.
12175 @item @command{!}
12176 @prindex @command{!}
12177 The Unix version 7 shell did not support
12178 negating the exit status of commands with @command{!}, and this feature
12179 is still absent from some shells (e.g., Solaris @command{/bin/sh}).
12180 Shell code like this:
12182 @example
12183 if ! cmp file1 file2 >/dev/null 2>&1; then
12184   echo files differ or trouble
12186 @end example
12188 is therefore not portable in practice.  Typically it is easy to rewrite
12189 such code, e.g.:
12191 @example
12192 cmp file1 file2 >/dev/null 2>&1 ||
12193   echo files differ or trouble
12194 @end example
12196 More generally, one can always rewrite @samp{! @var{command}} as:
12198 @example
12199 if @var{command}; then (exit 1); else :; fi
12200 @end example
12202 @item @command{break}
12203 @c ------------------
12204 @prindex @command{break}
12205 The use of @samp{break 2} etc.@: is safe.
12208 @item @command{case}
12209 @c -----------------
12210 @prindex @command{case}
12211 You don't need to quote the argument; no splitting is performed.
12213 You don't need the final @samp{;;}, but you should use it.
12215 Because of a bug in its @code{fnmatch}, Bash fails to properly
12216 handle backslashes in character classes:
12218 @example
12219 bash-2.02$ @kbd{case /tmp in [/\\]*) echo OK;; esac}
12220 bash-2.02$
12221 @end example
12223 @noindent
12224 This is extremely unfortunate, since you are likely to use this code to
12225 handle Posix or @sc{ms-dos} absolute file names.  To work around this
12226 bug, always put the backslash first:
12228 @example
12229 bash-2.02$ @kbd{case '\TMP' in [\\/]*) echo OK;; esac}
12231 bash-2.02$ @kbd{case /tmp in [\\/]*) echo OK;; esac}
12233 @end example
12235 Many Bourne shells cannot handle closing brackets in character classes
12236 correctly.
12238 Some shells also have problems with backslash escaping in case you do not want
12239 to match the backslash: both a backslash and the escaped character match this
12240 pattern.  To work around this, specify the character class in a variable, so
12241 that quote removal does not apply afterwards, and the special characters don't
12242 have to be backslash-escaped:
12244 @example
12245 $ @kbd{case '\' in [\<]) echo OK;; esac}
12247 $ @kbd{scanset='[<]'; case '\' in $scanset) echo OK;; esac}
12249 @end example
12251 Even with this, Solaris @command{ksh} matches a backslash if the set
12252 contains any
12253 of the characters @samp{|}, @samp{&}, @samp{(}, or @samp{)}.
12255 Conversely, Tru64 @command{ksh} (circa 2003) erroneously always matches
12256 a closing parenthesis if not specified in a character class:
12258 @example
12259 $ @kbd{case foo in *\)*) echo fail ;; esac}
12260 fail
12261 $ @kbd{case foo in *')'*) echo fail ;; esac}
12262 fail
12263 @end example
12265 Some shells, such as Ash 0.3.8, are confused by an empty
12266 @code{case}/@code{esac}:
12268 @example
12269 ash-0.3.8 $ @kbd{case foo in esac;}
12270 @error{}Syntax error: ";" unexpected (expecting ")")
12271 @end example
12273 Many shells still do not support parenthesized cases, which is a pity
12274 for those of us using tools that rely on balanced parentheses.  For
12275 instance, Solaris @command{/bin/sh}:
12277 @example
12278 $ @kbd{case foo in (foo) echo foo;; esac}
12279 @error{}syntax error: `(' unexpected
12280 @end example
12283 @item @command{cd}
12284 @c ---------------
12285 @prindex @command{cd}
12286 Posix 1003.1-2001 requires that @command{cd} must support
12287 the @option{-L} (``logical'') and @option{-P} (``physical'') options,
12288 with @option{-L} being the default.  However, traditional shells do
12289 not support these options, and their @command{cd} command has the
12290 @option{-P} behavior.
12292 Portable scripts should assume neither option is supported, and should
12293 assume neither behavior is the default.  This can be a bit tricky,
12294 since the Posix default behavior means that, for example,
12295 @samp{ls ..} and @samp{cd ..} may refer to different directories if
12296 the current logical directory is a symbolic link.  It is safe to use
12297 @command{cd @var{dir}} if @var{dir} contains no @file{..} components.
12298 Also, Autoconf-generated scripts check for this problem when computing
12299 variables like @code{ac_top_srcdir} (@pxref{Configuration Actions}),
12300 so it is safe to @command{cd} to these variables.
12302 See @xref{Special Shell Variables}, for portability problems involving
12303 @command{cd} and the @env{CDPATH} environment variable.
12304 Also please see the discussion of the @command{pwd} command.
12307 @item @command{echo}
12308 @c -----------------
12309 @prindex @command{echo}
12310 The simple @command{echo} is probably the most surprising source of
12311 portability troubles.  It is not possible to use @samp{echo} portably
12312 unless both options and escape sequences are omitted.  New applications
12313 which are not aiming at portability should use @samp{printf} instead of
12314 @samp{echo}.
12316 Don't expect any option.  @xref{Preset Output Variables}, @code{ECHO_N}
12317 etc.@: for a means to simulate @option{-n}.
12319 Do not use backslashes in the arguments, as there is no consensus on
12320 their handling.  For @samp{echo '\n' | wc -l}, the @command{sh} of
12321 Solaris outputs 2, but Bash and Zsh (in @command{sh} emulation mode) output 1.
12322 The problem is truly @command{echo}: all the shells
12323 understand @samp{'\n'} as the string composed of a backslash and an
12324 @samp{n}.
12326 Because of these problems, do not pass a string containing arbitrary
12327 characters to @command{echo}.  For example, @samp{echo "$foo"} is safe
12328 if you know that @var{foo}'s value cannot contain backslashes and cannot
12329 start with @samp{-}, but otherwise you should use a here-document like
12330 this:
12332 @example
12333 cat <<EOF
12334 $foo
12336 @end example
12339 @item @command{eval}
12340 @c -----------------
12341 @prindex @command{eval}
12342 The @command{eval} command is useful in limited circumstances, e.g.,
12343 using commands like @samp{eval table_$key=\$value} and @samp{eval
12344 value=table_$key} to simulate a hash table when the key is known to be
12345 alphanumeric.  However, @command{eval} is tricky to use on arbitrary
12346 arguments, even when it is implemented correctly.
12348 It is obviously unwise to use @samp{eval $cmd} if the string value of
12349 @samp{cmd} was derived from an untrustworthy source.  But even if the
12350 string value is valid, @samp{eval $cmd} might not work as intended,
12351 since it causes field splitting and file name expansion to occur twice,
12352 once for the @command{eval} and once for the command itself.  It is
12353 therefore safer to use @samp{eval "$cmd"}.  For example, if @var{cmd}
12354 has the value @samp{cat test?.c}, @samp{eval $cmd} might expand to the
12355 equivalent of @samp{cat test;.c} if there happens to be a file named
12356 @file{test;.c} in the current directory; and this in turn
12357 mistakenly attempts to invoke @command{cat} on the file @file{test} and
12358 then execute the command @command{.c}.  To avoid this problem, use
12359 @samp{eval "$cmd"} rather than @samp{eval $cmd}.
12361 However, suppose that you want to output the text of the evaluated
12362 command just before executing it.  Assuming the previous example,
12363 @samp{echo "Executing: $cmd"} outputs @samp{Executing: cat test?.c}, but
12364 this output doesn't show the user that @samp{test;.c} is the actual name
12365 of the copied file.  Conversely, @samp{eval "echo Executing: $cmd"}
12366 works on this example, but it fails with @samp{cmd='cat foo >bar'},
12367 since it mistakenly replaces the contents of @file{bar} by the
12368 string @samp{cat foo}.  No simple, general, and portable solution to
12369 this problem is known.
12371 You should also be wary of common bugs in @command{eval} implementations.
12372 In some shell implementations (e.g., older @command{ash}, Open@acronym{BSD} 3.8
12373 @command{sh}, @command{pdksh} v5.2.14 99/07/13.2, and @command{zsh}
12374 4.2.5), the arguments of @samp{eval} are evaluated in a context where
12375 @samp{$?} is 0, so they exhibit behavior like this:
12377 @example
12378 $ @kbd{false; eval 'echo $?'}
12380 @end example
12382 The correct behavior here is to output a nonzero value,
12383 but portable scripts should not rely on this.
12385 You should not rely on @code{LINENO} within @command{eval}.
12386 @xref{Special Shell Variables}.
12388 @item @command{exit}
12389 @c -----------------
12390 @prindex @command{exit}
12391 The default value of @command{exit} is supposed to be @code{$?};
12392 unfortunately, some shells, such as the @acronym{DJGPP} port of Bash 2.04, just
12393 perform @samp{exit 0}.
12395 @example
12396 bash-2.04$ @kbd{foo=`exit 1` || echo fail}
12397 fail
12398 bash-2.04$ @kbd{foo=`(exit 1)` || echo fail}
12399 fail
12400 bash-2.04$ @kbd{foo=`(exit 1); exit` || echo fail}
12401 bash-2.04$
12402 @end example
12404 Using @samp{exit $?} restores the expected behavior.
12406 Some shell scripts, such as those generated by @command{autoconf}, use a
12407 trap to clean up before exiting.  If the last shell command exited with
12408 nonzero status, the trap also exits with nonzero status so that the
12409 invoker can tell that an error occurred.
12411 Unfortunately, in some shells, such as Solaris @command{/bin/sh}, an exit
12412 trap ignores the @code{exit} command's argument.  In these shells, a trap
12413 cannot determine whether it was invoked by plain @code{exit} or by
12414 @code{exit 1}.  Instead of calling @code{exit} directly, use the
12415 @code{AC_MSG_ERROR} macro that has a workaround for this problem.
12418 @item @command{export}
12419 @c -------------------
12420 @prindex @command{export}
12421 The builtin @command{export} dubs a shell variable @dfn{environment
12422 variable}.  Each update of exported variables corresponds to an update
12423 of the environment variables.  Conversely, each environment variable
12424 received by the shell when it is launched should be imported as a shell
12425 variable marked as exported.
12427 Alas, many shells, such as Solaris @command{/bin/sh},
12428 @sc{irix} 6.3, @sc{irix} 5.2,
12429 @acronym{AIX} 4.1.5, and Digital Unix 4.0, forget to
12430 @command{export} the environment variables they receive.  As a result,
12431 two variables coexist: the environment variable and the shell
12432 variable.  The following code demonstrates this failure:
12434 @example
12435 #!/bin/sh
12436 echo $FOO
12437 FOO=bar
12438 echo $FOO
12439 exec /bin/sh $0
12440 @end example
12442 @noindent
12443 when run with @samp{FOO=foo} in the environment, these shells print
12444 alternately @samp{foo} and @samp{bar}, although they should print only
12445 @samp{foo} and then a sequence of @samp{bar}s.
12447 Therefore you should @command{export} again each environment variable
12448 that you update.
12451 @item @command{false}
12452 @c ------------------
12453 @prindex @command{false}
12454 Don't expect @command{false} to exit with status 1: in native
12455 Solaris @file{/bin/false} exits with status 255.
12458 @item @command{for}
12459 @c ----------------
12460 @prindex @command{for}
12461 To loop over positional arguments, use:
12463 @example
12464 for arg
12466   echo "$arg"
12467 done
12468 @end example
12470 @noindent
12471 You may @emph{not} leave the @code{do} on the same line as @code{for},
12472 since some shells improperly grok:
12474 @example
12475 for arg; do
12476   echo "$arg"
12477 done
12478 @end example
12480 If you want to explicitly refer to the positional arguments, given the
12481 @samp{$@@} bug (@pxref{Shell Substitutions}), use:
12483 @example
12484 for arg in $@{1+"$@@"@}; do
12485   echo "$arg"
12486 done
12487 @end example
12489 @noindent
12490 But keep in mind that Zsh, even in Bourne shell emulation mode, performs
12491 word splitting on @samp{$@{1+"$@@"@}}; see @ref{Shell Substitutions},
12492 item @samp{$@@}, for more.
12495 @item @command{if}
12496 @c ---------------
12497 @prindex @command{if}
12498 Using @samp{!} is not portable.  Instead of:
12500 @example
12501 if ! cmp -s file file.new; then
12502   mv file.new file
12504 @end example
12506 @noindent
12507 use:
12509 @example
12510 if cmp -s file file.new; then :; else
12511   mv file.new file
12513 @end example
12515 There are shells that do not reset the exit status from an @command{if}:
12517 @example
12518 $ @kbd{if (exit 42); then true; fi; echo $?}
12520 @end example
12522 @noindent
12523 whereas a proper shell should have printed @samp{0}.  This is especially
12524 bad in makefiles since it produces false failures.  This is why properly
12525 written makefiles, such as Automake's, have such hairy constructs:
12527 @example
12528 if test -f "$file"; then
12529   install "$file" "$dest"
12530 else
12531   :
12533 @end example
12536 @item @command{printf}
12537 @c ------------------
12538 @prindex @command{printf}
12539 A format string starting with a @samp{-} can cause problems.
12540 Bash (e.g., 2.05b) interprets it as an options argument and
12541 gives an error.  And @samp{--} to mark the end of options is not good
12542 in the Net@acronym{BSD} Almquist shell (e.g., 0.4.6) which takes that
12543 literally as the format string.  Putting the @samp{-} in a @samp{%c}
12544 or @samp{%s} is probably the easiest way to avoid doubt,
12546 @example
12547 printf %s -foo
12548 @end example
12551 @item @command{read}
12552 @c ------------------
12553 @prindex @command{read}
12554 Not all shells support @option{-r} (Solaris @command{/bin/sh} for example).
12557 @item @command{pwd}
12558 @c ----------------
12559 @prindex @command{pwd}
12560 With modern shells, plain @command{pwd} outputs a ``logical''
12561 directory name, some of whose components may be symbolic links.  These
12562 directory names are in contrast to ``physical'' directory names, whose
12563 components are all directories.
12565 Posix 1003.1-2001 requires that @command{pwd} must support
12566 the @option{-L} (``logical'') and @option{-P} (``physical'') options,
12567 with @option{-L} being the default.  However, traditional shells do
12568 not support these options, and their @command{pwd} command has the
12569 @option{-P} behavior.
12571 Portable scripts should assume neither option is supported, and should
12572 assume neither behavior is the default.  Also, on many hosts
12573 @samp{/bin/pwd} is equivalent to @samp{pwd -P}, but Posix
12574 does not require this behavior and portable scripts should not rely on
12577 Typically it's best to use plain @command{pwd}.  On modern hosts this
12578 outputs logical directory names, which have the following advantages:
12580 @itemize @bullet
12581 @item
12582 Logical names are what the user specified.
12583 @item
12584 Physical names may not be portable from one installation
12585 host to another due to network file system gymnastics.
12586 @item
12587 On modern hosts @samp{pwd -P} may fail due to lack of permissions to
12588 some parent directory, but plain @command{pwd} cannot fail for this
12589 reason.
12590 @end itemize
12592 Also please see the discussion of the @command{cd} command.
12595 @item @command{set}
12596 @c ----------------
12597 @prindex @command{set}
12598 With the Free@acronym{BSD} 6.0 shell, the @command{set} command (without
12599 any options) does not sort its output.
12601 The @command{set} builtin faces the usual problem with arguments starting with a
12602 dash.  Modern shells such as Bash or Zsh understand @option{--} to specify
12603 the end of the options (any argument after @option{--} is a parameter,
12604 even @samp{-x} for instance), but many traditional shells (e.g., Solaris
12605 10 @command{/bin/sh}) simply stop option
12606 processing as soon as a non-option argument is found.  Therefore, use
12607 @samp{dummy} or simply @samp{x} to end the option processing, and use
12608 @command{shift} to pop it out:
12610 @example
12611 set x $my_list; shift
12612 @end example
12614 Avoid @samp{set -}, e.g., @samp{set - $my_list}.  Posix no
12615 longer requires support for this command, and in traditional shells
12616 @samp{set - $my_list} resets the @option{-v} and @option{-x} options, which
12617 makes scripts harder to debug.
12619 Some nonstandard shells do not recognize more than one option
12620 (e.g., @samp{set -e -x} assigns @samp{-x} to the command line).  It is
12621 better to combine them:
12623 @example
12624 set -ex
12625 @end example
12627 The @acronym{BSD} shell has had several problems with the @option{-e}
12628 option, partly because @acronym{BSD} @command{make} traditionally used
12629 @option{-e} even though this was incompatible with Posix
12630 (@pxref{Failure in Make Rules}).  Older versions of the @acronym{BSD}
12631 shell (circa 1990) mishandled @samp{&&}, @samp{||}, @samp{if}, and
12632 @samp{case} when @option{-e} was in effect, causing the shell to exit
12633 unexpectedly in some cases.  This was particularly a problem with
12634 makefiles, and led to circumlocutions like @samp{sh -c 'test -f file ||
12635 touch file'}, where the seemingly-unnecessary @samp{sh -c '@dots{}'}
12636 wrapper works around the bug.
12638 Even relatively-recent versions of the @acronym{BSD} shell (e.g.,
12639 Open@acronym{BSD} 3.4) wrongly exit with @option{-e} if a command within
12640 @samp{&&} fails inside a compound statement.  For example:
12642 @example
12643 #! /bin/sh
12644 set -e
12645 foo=''
12646 test -n "$foo" && exit 1
12647 echo one
12648 if :; then
12649   test -n "$foo" && exit 1
12651 echo two
12652 @end example
12654 @noindent
12655 does not print @samp{two}.  One workaround is to use @samp{if test -n
12656 "$foo"; then exit 1; fi} rather than @samp{test -n "$foo" && exit 1}.
12657 Another possibility is to warn @acronym{BSD} users not to use @samp{sh -e}.
12660 @item @command{shift}
12661 @c ------------------
12662 @prindex @command{shift}
12663 Not only is @command{shift}ing a bad idea when there is nothing left to
12664 shift, but in addition it is not portable: the shell of @acronym{MIPS
12665 RISC/OS} 4.52 refuses to do it.
12667 Don't use @samp{shift 2} etc.; it was not in the 7th Edition Bourne shell,
12668 and it is also absent in many pre-Posix shells.
12671 @item @command{source}
12672 @c -------------------
12673 @prindex @command{source}
12674 This command is not portable, as Posix does not require it; use
12675 @command{.} instead.
12678 @item @command{test}
12679 @c -----------------
12680 @prindex @command{test}
12681 The @code{test} program is the way to perform many file and string
12682 tests.  It is often invoked by the alternate name @samp{[}, but using
12683 that name in Autoconf code is asking for trouble since it is an M4 quote
12684 character.
12686 If you need to make multiple checks using @code{test}, combine them with
12687 the shell operators @samp{&&} and @samp{||} instead of using the
12688 @code{test} operators @option{-a} and @option{-o}.  On System V, the
12689 precedence of @option{-a} and @option{-o} is wrong relative to the unary
12690 operators; consequently, Posix does not specify them, so using them
12691 is nonportable.  If you combine @samp{&&} and @samp{||} in the same
12692 statement, keep in mind that they have equal precedence.
12694 It is safe to use @samp{!} as a @command{test} operator.  For example,
12695 @samp{if test ! -d foo; @dots{}} is portable even though @samp{if ! test
12696 -d foo; @dots{}} is not.
12699 @item @command{test} (files)
12700 @c -------------------------
12701 To enable @command{configure} scripts to support cross-compilation, they
12702 shouldn't do anything that tests features of the build system instead of
12703 the host system.  But occasionally you may find it necessary to check
12704 whether some arbitrary file exists.  To do so, use @samp{test -f} or
12705 @samp{test -r}.  Do not use @samp{test -x}, because 4.3@acronym{BSD} does not
12706 have it.  Do not use @samp{test -e} either, because Solaris @command{/bin/sh}
12707 lacks it.  To test for symbolic links on systems that have them, use
12708 @samp{test -h} rather than @samp{test -L}; either form conforms to
12709 Posix 1003.1-2001, but older shells like Solaris 8
12710 @code{/bin/sh} support only @option{-h}.
12712 @item @command{test} (strings)
12713 @c ---------------------------
12714 Avoid @samp{test "@var{string}"}, in particular if @var{string} might
12715 start with a dash, since @code{test} might interpret its argument as an
12716 option (e.g., @samp{@var{string} = "-n"}).
12718 Contrary to a common belief, @samp{test -n @var{string}} and
12719 @samp{test -z @var{string}} @strong{are} portable.  Nevertheless many
12720 shells (such as Solaris, @acronym{AIX} 3.2, @sc{unicos} 10.0.0.6,
12721 Digital Unix 4, etc.)@: have bizarre precedence and may be confused if
12722 @var{string} looks like an operator:
12724 @example
12725 $ @kbd{test -n =}
12726 test: argument expected
12727 @end example
12729 If there are risks, use @samp{test "x@var{string}" = x} or @samp{test
12730 "x@var{string}" != x} instead.
12732 It is common to find variations of the following idiom:
12734 @example
12735 test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" &&
12736   @var{action}
12737 @end example
12739 @noindent
12740 to take an action when a token matches a given pattern.  Such constructs
12741 should always be avoided by using:
12743 @example
12744 echo "$ac_feature" | grep '[^-a-zA-Z0-9_]' >/dev/null 2>&1 &&
12745   @var{action}
12746 @end example
12748 @noindent
12749 Use @code{case} where possible since it is faster, being a shell builtin:
12752 @example
12753 case $ac_feature in
12754   *[!-a-zA-Z0-9_]*) @var{action};;
12755 esac
12756 @end example
12758 Alas, negated character classes are probably not portable, although no
12759 shell is known to not support the Posix syntax @samp{[!@dots{}]}
12760 (when in interactive mode, @command{zsh} is confused by the
12761 @samp{[!@dots{}]} syntax and looks for an event in its history because of
12762 @samp{!}).  Many shells do not support the alternative syntax
12763 @samp{[^@dots{}]} (Solaris, Digital Unix, etc.).
12765 One solution can be:
12767 @example
12768 expr "$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
12769   @var{action}
12770 @end example
12772 @noindent
12773 or better yet
12775 @example
12776 expr "X$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
12777   @var{action}
12778 @end example
12780 @samp{expr "X@var{foo}" : "X@var{bar}"} is more robust than @samp{echo
12781 "X@var{foo}" | grep "^X@var{bar}"}, because it avoids problems when
12782 @samp{@var{foo}} contains backslashes.
12785 @item @command{trap}
12786 @c -----------------
12787 @prindex @command{trap}
12788 It is safe to trap at least the signals 1, 2, 13, and 15.  You can also
12789 trap 0, i.e., have the @command{trap} run when the script ends (either via an
12790 explicit @command{exit}, or the end of the script).
12792 Posix says that @samp{trap - 1 2 13 15} resets the traps for the
12793 specified signals to their default values, but many common shells (e.g.,
12794 Solaris @command{/bin/sh}) misinterpret this and attempt to execute a
12795 ``command'' named @command{-} when the specified conditions arise.
12796 There is no portable workaround, except for @samp{trap - 0}, for which
12797 @samp{trap '' 0} is a portable substitute.
12799 Although Posix is not absolutely clear on this point, it is widely
12800 admitted that when entering the trap @samp{$?} should be set to the exit
12801 status of the last command run before the trap.  The ambiguity can be
12802 summarized as: ``when the trap is launched by an @command{exit}, what is
12803 the @emph{last} command run: that before @command{exit}, or
12804 @command{exit} itself?''
12806 Bash considers @command{exit} to be the last command, while Zsh and
12807 Solaris @command{/bin/sh} consider that when the trap is run it is
12808 @emph{still} in the @command{exit}, hence it is the previous exit status
12809 that the trap receives:
12811 @example
12812 $ @kbd{cat trap.sh}
12813 trap 'echo $?' 0
12814 (exit 42); exit 0
12815 $ @kbd{zsh trap.sh}
12817 $ @kbd{bash trap.sh}
12819 @end example
12821 The portable solution is then simple: when you want to @samp{exit 42},
12822 run @samp{(exit 42); exit 42}, the first @command{exit} being used to
12823 set the exit status to 42 for Zsh, and the second to trigger the trap
12824 and pass 42 as exit status for Bash.
12826 The shell in Free@acronym{BSD} 4.0 has the following bug: @samp{$?} is
12827 reset to 0 by empty lines if the code is inside @command{trap}.
12829 @example
12830 $ @kbd{trap 'false}
12832 echo $?' 0
12833 $ @kbd{exit}
12835 @end example
12837 @noindent
12838 Fortunately, this bug only affects @command{trap}.
12840 @item @command{true}
12841 @c -----------------
12842 @prindex @command{true}
12843 @c Info cannot handle `:' in index entries.
12844 @c @prindex @command{:}
12845 Don't worry: as far as we know @command{true} is portable.
12846 Nevertheless, it's not always a builtin (e.g., Bash 1.x), and the
12847 portable shell community tends to prefer using @command{:}.  This has a
12848 funny side effect: when asked whether @command{false} is more portable
12849 than @command{true} Alexandre Oliva answered:
12851 @quotation
12852 In a sense, yes, because if it doesn't exist, the shell will produce an
12853 exit status of failure, which is correct for @command{false}, but not
12854 for @command{true}.
12855 @end quotation
12858 @item @command{unset}
12859 @c ------------------
12860 @prindex @command{unset}
12861 In some nonconforming shells (e.g., Bash 2.05a), @code{unset FOO} fails
12862 when @code{FOO} is not set.  Also, Bash 2.01 mishandles @code{unset
12863 MAIL} in some cases and dumps core.
12865 A few ancient shells lack @command{unset} entirely.  Nevertheless, because
12866 it is extremely useful to disable embarrassing variables such as
12867 @code{PS1}, you can test for its existence and use
12868 it @emph{provided} you give a neutralizing value when @command{unset} is
12869 not supported:
12871 @smallexample
12872 # "|| exit" suppresses any "Segmentation fault" message.
12873 if ( (MAIL=60; unset MAIL) || exit) >/dev/null 2>&1; then
12874   unset=unset
12875 else
12876   unset=false
12878 $unset PS1 || PS1='$ '
12879 @end smallexample
12881 @noindent
12882 @xref{Special Shell Variables}, for some neutralizing values.  Also, see
12883 @ref{Limitations of Builtins}, documentation of @command{export}, for
12884 the case of environment variables.
12885 @end table
12887 @node Limitations of Usual Tools
12888 @section Limitations of Usual Tools
12889 @cindex Limitations of usual tools
12891 The small set of tools you can expect to find on any machine can still
12892 include some limitations you should be aware of.
12894 @table @asis
12895 @item Awk
12896 @c ------
12897 @prindex Awk
12898 Don't leave white space before the opening parenthesis in a user function call.
12899 Posix does not allow this and @acronym{GNU} Awk rejects it:
12901 @example
12902 $ @kbd{gawk 'function die () @{ print "Aaaaarg!"  @}
12903         BEGIN @{ die () @}'}
12904 gawk: cmd. line:2:         BEGIN @{ die () @}
12905 gawk: cmd. line:2:                      ^ parse error
12906 $ @kbd{gawk 'function die () @{ print "Aaaaarg!"  @}
12907         BEGIN @{ die() @}'}
12908 Aaaaarg!
12909 @end example
12911 If you want your program to be deterministic, don't depend on @code{for}
12912 on arrays:
12914 @example
12915 $ @kbd{cat for.awk}
12916 END @{
12917   arr["foo"] = 1
12918   arr["bar"] = 1
12919   for (i in arr)
12920     print i
12922 $ @kbd{gawk -f for.awk </dev/null}
12925 $ @kbd{nawk -f for.awk </dev/null}
12928 @end example
12930 Some Awk implementations, such as @acronym{HP-UX} 11.0's native one, mishandle anchors:
12932 @example
12933 $ @kbd{echo xfoo | $AWK '/foo|^bar/ @{ print @}'}
12934 $ @kbd{echo bar | $AWK '/foo|^bar/ @{ print @}'}
12936 $ @kbd{echo xfoo | $AWK '/^bar|foo/ @{ print @}'}
12937 xfoo
12938 $ @kbd{echo bar | $AWK '/^bar|foo/ @{ print @}'}
12940 @end example
12942 @noindent
12943 Either do not depend on such patterns (i.e., use @samp{/^(.*foo|bar)/},
12944 or use a simple test to reject such implementations.
12946 @acronym{AIX} version 5.2 has an arbitrary limit of 399 on the
12947 length of regular expressions and literal strings in an Awk program.
12949 Traditional Awk implementations derived from Unix version 7, such as
12950 Solaris @command{/bin/awk}, have many limitations and do not
12951 conform to Posix.  Nowadays @code{AC_PROG_AWK} (@pxref{Particular
12952 Programs}) finds you an Awk that doesn't have these problems, but if
12953 for some reason you prefer not to use @code{AC_PROG_AWK} you may need to
12954 address them.
12956 Traditional Awk does not support multidimensional arrays or user-defined
12957 functions.
12959 Traditional Awk does not support the @option{-v} option.  You can use
12960 assignments after the program instead, e.g., @command{$AWK '@{print v
12961 $1@}' v=x}; however, don't forget that such assignments are not
12962 evaluated until they are encountered (e.g., after any @code{BEGIN}
12963 action).
12965 Traditional Awk does not support the keywords @code{delete} or @code{do}.
12967 Traditional Awk does not support the expressions
12968 @code{@var{a}?@var{b}:@var{c}}, @code{!@var{a}}, @code{@var{a}^@var{b}},
12969 or @code{@var{a}^=@var{b}}.
12971 Traditional Awk does not support the predefined @code{CONVFMT} variable.
12973 Traditional Awk supports only the predefined functions @code{exp},
12974 @code{int}, @code{length}, @code{log}, @code{split}, @code{sprintf},
12975 @code{sqrt}, and @code{substr}.
12977 Traditional Awk @code{getline} is not at all compatible with Posix;
12978 avoid it.
12980 Traditional Awk @code{split} supports only two arguments.
12982 Traditional Awk has a limit of 99
12983 fields in a record.  You may be able to circumvent this problem by using
12984 @code{split}.
12987 @item @command{basename}
12988 @c ---------------------
12989 @prindex @command{basename}
12990 Not all hosts have a working @command{basename}.
12991 You can use @command{expr} instead.
12993 @c AS_BASENAME is to be replaced by a better API.
12994 @ignore
12995 Not all hosts have a working @command{basename}, and you should instead
12996 use @code{AS_BASENAME} (@pxref{Programming in M4sh}), followed by
12997 @command{expr} if you need to strip a suffix.  For example:
12999 @example
13000 a=`basename "$aname"`       # This is not portable.
13001 a=`AS_BASENAME(["$aname"])` # This is more portable.
13003 # This is not portable.
13004 c=`basename "$cname" .c`
13006 # This is more portable.
13007 c=`AS_BASENAME(["$cname"])`
13008 case $c in
13009 ?*.c) c=`expr "X$c" : 'X\(.*\)\.c'`;;
13010 esac
13011 @end example
13012 @end ignore
13015 @item @command{cat}
13016 @c ----------------
13017 @prindex @command{cat}
13018 Don't rely on any option.
13021 @item @command{cc}
13022 @c ---------------
13023 @prindex @command{cc}
13024 The command @samp{cc -c foo.c} traditionally produces an object file
13025 named @file{foo.o}.  Most compilers allow @option{-c} to be combined
13026 with @option{-o} to specify a different object file name, but
13027 Posix does not require this combination and a few compilers
13028 lack support for it.  @xref{C Compiler}, for how @acronym{GNU} Make
13029 tests for this feature with @code{AC_PROG_CC_C_O}.
13031 When a compilation such as @samp{cc -o foo foo.c} fails, some compilers
13032 (such as @sc{cds} on Reliant Unix) leave a @file{foo.o}.
13034 @acronym{HP-UX} @command{cc} doesn't accept @file{.S} files to preprocess and
13035 assemble.  @samp{cc -c foo.S} appears to succeed, but in fact does
13036 nothing.
13038 The default executable, produced by @samp{cc foo.c}, can be
13040 @itemize
13041 @item @file{a.out} --- usual Posix convention.
13042 @item @file{b.out} --- i960 compilers (including @command{gcc}).
13043 @item @file{a.exe} --- @acronym{DJGPP} port of @command{gcc}.
13044 @item @file{a_out.exe} --- GNV @command{cc} wrapper for DEC C on OpenVMS.
13045 @item @file{foo.exe} --- various MS-DOS compilers.
13046 @end itemize
13048 The C compiler's traditional name is @command{cc}, but other names like
13049 @command{gcc} are common.  Posix 1003.1-2001 specifies the
13050 name @command{c99}, but older Posix editions specified
13051 @command{c89} and anyway these standard names are rarely used in
13052 practice.  Typically the C compiler is invoked from makefiles that use
13053 @samp{$(CC)}, so the value of the @samp{CC} make variable selects the
13054 compiler name.
13057 @item @command{chmod}
13058 @c ------------------
13059 @prindex @command{chmod}
13060 Avoid usages like @samp{chmod -w file}; use @samp{chmod a-w file}
13061 instead, for two reasons.  First, plain @option{-w} does not necessarily
13062 make the file unwritable, since it does not affect mode bits that
13063 correspond to bits in the file mode creation mask.  Second,
13064 Posix says that the @option{-w} might be interpreted as an
13065 implementation-specific option, not as a mode; Posix suggests
13066 using @samp{chmod -- -w file} to avoid this confusion, but unfortunately
13067 @samp{--} does not work on some older hosts.
13070 @item @command{cmp}
13071 @c ----------------
13072 @prindex @command{cmp}
13073 @command{cmp} performs a raw data comparison of two files, while
13074 @command{diff} compares two text files.  Therefore, if you might compare
13075 DOS files, even if only checking whether two files are different, use
13076 @command{diff} to avoid spurious differences due to differences of
13077 newline encoding.
13080 @item @command{cp}
13081 @c ---------------
13082 @prindex @command{cp}
13083 Avoid the @option{-r} option, since Posix 1003.1-2004 marks it as
13084 obsolescent and its behavior on special files is implementation-defined.
13085 Use @option{-R} instead.  On @acronym{GNU} hosts the two options
13086 are equivalent, but on Solaris hosts (for example) @command{cp -r}
13087 reads from pipes instead of replicating them.
13089 Some @command{cp} implementations (e.g., @acronym{BSD/OS} 4.2) do not allow
13090 trailing slashes at the end of nonexistent destination directories.  To
13091 avoid this problem, omit the trailing slashes.  For example, use
13092 @samp{cp -R source /tmp/newdir} rather than @samp{cp -R source
13093 /tmp/newdir/} if @file{/tmp/newdir} does not exist.
13095 @c This is thanks to Ian.
13096 The ancient SunOS 4 @command{cp} does not support @option{-f}, although
13097 its @command{mv} does.
13099 @cindex timestamp resolution
13100 Traditionally, file timestamps had 1-second resolution, and @samp{cp
13101 -p} copied the timestamps exactly.  However, many modern file systems
13102 have timestamps with 1-nanosecond resolution.  Unfortunately, @samp{cp
13103 -p} implementations truncate timestamps when copying files, so this
13104 can result in the destination file appearing to be older than the
13105 source.  The exact amount of truncation depends on the resolution of
13106 the system calls that @command{cp} uses; traditionally this was
13107 @code{utime}, which has 1-second resolution, but some newer
13108 @command{cp} implementations use @code{utimes}, which has
13109 1-microsecond resolution.  These newer implementations include @acronym{GNU}
13110 Core Utilities 5.0.91 or later, and Solaris 8 (sparc) patch 109933-02 or
13111 later.  Unfortunately as of January 2006 there is still no system
13112 call to set timestamps to the full nanosecond resolution.
13114 Bob Proulx notes that @samp{cp -p} always @emph{tries} to copy
13115 ownerships.  But whether it actually does copy ownerships or not is a
13116 system dependent policy decision implemented by the kernel.  If the
13117 kernel allows it then it happens.  If the kernel does not allow it then
13118 it does not happen.  It is not something @command{cp} itself has control
13119 over.
13121 In Unix System V any user can chown files to any other user, and System
13122 V also has a non-sticky @file{/tmp}.  That probably derives from the
13123 heritage of System V in a business environment without hostile users.
13124 @acronym{BSD} changed this
13125 to be a more secure model where only root can @command{chown} files and
13126 a sticky @file{/tmp} is used.  That undoubtedly derives from the heritage
13127 of @acronym{BSD} in a campus environment.
13129 @acronym{GNU}/Linux and Solaris by default follow @acronym{BSD}, but
13130 can be configured to allow a System V style @command{chown}.  On the
13131 other hand, @acronym{HP-UX} follows System V, but can
13132 be configured to use the modern security model and disallow
13133 @command{chown}.  Since it is an administrator-configurable parameter
13134 you can't use the name of the kernel as an indicator of the behavior.
13138 @item @command{date}
13139 @c -----------------
13140 @prindex @command{date}
13141 Some versions of @command{date} do not recognize special @samp{%} directives,
13142 and unfortunately, instead of complaining, they just pass them through,
13143 and exit with success:
13145 @example
13146 $ @kbd{uname -a}
13147 OSF1 medusa.sis.pasteur.fr V5.1 732 alpha
13148 $ @kbd{date "+%s"}
13150 @end example
13153 @item @command{diff}
13154 @c -----------------
13155 @prindex @command{diff}
13156 Option @option{-u} is nonportable.
13158 Some implementations, such as Tru64's, fail when comparing to
13159 @file{/dev/null}.  Use an empty file instead.
13162 @item @command{dirname}
13163 @c --------------------
13164 @prindex @command{dirname}
13165 Not all hosts have a working @command{dirname}, and you should instead
13166 use @code{AS_DIRNAME} (@pxref{Programming in M4sh}).  For example:
13168 @example
13169 dir=`dirname "$file"`       # This is not portable.
13170 dir=`AS_DIRNAME(["$file"])` # This is more portable.
13171 @end example
13174 @item @command{egrep}
13175 @c ------------------
13176 @prindex @command{egrep}
13177 Posix 1003.1-2001 no longer requires @command{egrep},
13178 but many older hosts do not yet support the Posix
13179 replacement @code{grep -E}.  Also, some traditional implementations do
13180 not work on long input lines.  To work around these problems, invoke
13181 @code{AC_PROG_EGREP} and then use @code{$EGREP}.
13183 Portable extended regular expressions should use @samp{\} only to escape
13184 characters in the string @samp{$()*+.?[\^@{|}.  For example, @samp{\@}}
13185 is not portable, even though it typically matches @samp{@}}.
13187 The empty alternative is not portable.  Use @samp{?} instead.  For
13188 instance with Digital Unix v5.0:
13190 @example
13191 > printf "foo\n|foo\n" | $EGREP '^(|foo|bar)$'
13192 |foo
13193 > printf "bar\nbar|\n" | $EGREP '^(foo|bar|)$'
13194 bar|
13195 > printf "foo\nfoo|\n|bar\nbar\n" | $EGREP '^(foo||bar)$'
13197 |bar
13198 @end example
13200 @command{$EGREP} also suffers the limitations of @command{grep}.
13202 @item @command{expr}
13203 @c -----------------
13204 @prindex @command{expr}
13205 No @command{expr} keyword starts with @samp{X}, so use @samp{expr
13206 X"@var{word}" : 'X@var{regex}'} to keep @command{expr} from
13207 misinterpreting @var{word}.
13209 Don't use @code{length}, @code{substr}, @code{match} and @code{index}.
13211 @item @command{expr} (@samp{|})
13212 @prindex @command{expr} (@samp{|})
13213 You can use @samp{|}.  Although Posix does require that @samp{expr
13214 ''} return the empty string, it does not specify the result when you
13215 @samp{|} together the empty string (or zero) with the empty string.  For
13216 example:
13218 @example
13219 expr '' \| ''
13220 @end example
13222 Posix 1003.2-1992 returns the empty string
13223 for this case, but traditional Unix returns @samp{0} (Solaris is
13224 one such example).  In Posix 1003.1-2001, the specification was
13225 changed to match traditional Unix's behavior (which is
13226 bizarre, but it's too late to fix this).  Please note that the same
13227 problem does arise when the empty string results from a computation,
13228 as in:
13230 @example
13231 expr bar : foo \| foo : bar
13232 @end example
13234 @noindent
13235 Avoid this portability problem by avoiding the empty string.
13238 @item @command{expr} (@samp{:})
13239 @c ----------------------------
13240 @prindex @command{expr}
13241 Portable @command{expr} regular expressions should use @samp{\} to
13242 escape only characters in the string @samp{$()*.0123456789[\^n@{@}}.
13243 For example, alternation, @samp{\|}, is common but Posix does not
13244 require its support, so it should be avoided in portable scripts.
13245 Similarly, @samp{\+} and @samp{\?} should be avoided.
13247 Portable @command{expr} regular expressions should not begin with
13248 @samp{^}.  Patterns are automatically anchored so leading @samp{^} is
13249 not needed anyway.
13251 The Posix standard is ambiguous as to whether
13252 @samp{expr 'a' : '\(b\)'} outputs @samp{0} or the empty string.
13253 In practice, it outputs the empty string on most platforms, but portable
13254 scripts should not assume this.  For instance, the @acronym{QNX} 4.25 native
13255 @command{expr} returns @samp{0}.
13257 One might think that a way to get a uniform behavior would be to use
13258 the empty string as a default value:
13260 @example
13261 expr a : '\(b\)' \| ''
13262 @end example
13264 @noindent
13265 Unfortunately this behaves exactly as the original expression; see the
13266 @command{expr} (@samp{|}) entry for more information.
13268 Ancient @command{expr} implementations (e.g., SunOS 4 @command{expr} and
13269 Solaris 8 @command{/usr/ucb/expr}) have a silly length limit that causes
13270 @command{expr} to fail if the matched substring is longer than 120
13271 bytes.  In this case, you might want to fall back on @samp{echo|sed} if
13272 @command{expr} fails.  Nowadays this is of practical importance only for
13273 the rare installer who mistakenly puts @file{/usr/ucb} before
13274 @file{/usr/bin} in @env{PATH}.
13276 On Mac OS X 10.4, @command{expr} mishandles the pattern @samp{[^-]} in
13277 some cases.  For example, the command
13278 @example
13279 expr Xpowerpc-apple-darwin8.1.0 : 'X[^-]*-[^-]*-\(.*\)'
13280 @end example
13282 @noindent
13283 outputs @samp{apple-darwin8.1.0} rather than the correct @samp{darwin8.1.0}.
13284 This particular case can be worked around by substituting @samp{[^--]}
13285 for @samp{[^-]}.
13287 Don't leave, there is some more!
13289 The @acronym{QNX} 4.25 @command{expr}, in addition of preferring @samp{0} to
13290 the empty string, has a funny behavior in its exit status: it's always 1
13291 when parentheses are used!
13293 @example
13294 $ @kbd{val=`expr 'a' : 'a'`; echo "$?: $val"}
13295 0: 1
13296 $ @kbd{val=`expr 'a' : 'b'`; echo "$?: $val"}
13297 1: 0
13299 $ @kbd{val=`expr 'a' : '\(a\)'`; echo "?: $val"}
13300 1: a
13301 $ @kbd{val=`expr 'a' : '\(b\)'`; echo "?: $val"}
13302 1: 0
13303 @end example
13305 @noindent
13306 In practice this can be a big problem if you are ready to catch failures
13307 of @command{expr} programs with some other method (such as using
13308 @command{sed}), since you may get twice the result.  For instance
13310 @example
13311 $ @kbd{expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/'}
13312 @end example
13314 @noindent
13315 outputs @samp{a} on most hosts, but @samp{aa} on @acronym{QNX} 4.25.  A
13316 simple workaround consists of testing @command{expr} and using a variable
13317 set to @command{expr} or to @command{false} according to the result.
13319 Tru64 @command{expr} incorrectly treats the result as a number, if it
13320 can be interpreted that way:
13322 @example
13323 $ @kbd{expr 00001 : '.*\(...\)'}
13325 @end example
13328 @item @command{fgrep}
13329 @c ------------------
13330 @prindex @command{fgrep}
13331 Posix 1003.1-2001 no longer requires @command{fgrep},
13332 but many older hosts do not yet support the Posix
13333 replacement @code{grep -F}.  Also, some traditional implementations do
13334 not work on long input lines.  To work around these problems, invoke
13335 @code{AC_PROG_FGREP} and then use @code{$FGREP}.
13338 @item @command{find}
13339 @c -----------------
13340 @prindex @command{find}
13341 The option @option{-maxdepth} seems to be @acronym{GNU} specific.
13342 Tru64 v5.1, Net@acronym{BSD} 1.5 and Solaris @command{find}
13343 commands do not understand it.
13345 The replacement of @samp{@{@}} is guaranteed only if the argument is
13346 exactly @emph{@{@}}, not if it's only a part of an argument.  For
13347 instance on DU, and @acronym{HP-UX} 10.20 and @acronym{HP-UX} 11:
13349 @example
13350 $ @kbd{touch foo}
13351 $ @kbd{find . -name foo -exec echo "@{@}-@{@}" \;}
13352 @{@}-@{@}
13353 @end example
13355 @noindent
13356 while @acronym{GNU} @command{find} reports @samp{./foo-./foo}.
13359 @item @command{grep}
13360 @c -----------------
13361 @prindex @command{grep}
13362 Portable scripts can rely on the @command{grep} options @option{-c},
13363 @option{-l}, @option{-n}, and @option{-v}, but should avoid other
13364 options.  For example, don't use @option{-w}, as Posix does not require
13365 it and Irix 6.5.16m's @command{grep} does not support it.  Also,
13366 portable scripts should not combine @option{-c} with @option{-l},
13367 as Posix does not allow this.
13369 Some of the options required by Posix are not portable in practice.
13370 Don't use @samp{grep -q} to suppress output, because many @command{grep}
13371 implementations (e.g., Solaris) do not support @option{-q}.
13372 Don't use @samp{grep -s} to suppress output either, because Posix
13373 says @option{-s} does not suppress output, only some error messages;
13374 also, the @option{-s} option of traditional @command{grep} behaved
13375 like @option{-q} does in most modern implementations.  Instead,
13376 redirect the standard output and standard error (in case the file
13377 doesn't exist) of @code{grep} to @file{/dev/null}.  Check the exit
13378 status of @code{grep} to determine whether it found a match.
13380 Some traditional @command{grep} implementations do not work on long
13381 input lines.  On AIX the default @code{grep} silently truncates long
13382 lines on the input before matching.
13384 Also, many implementations do not support multiple regexps
13385 with @option{-e}: they either reject @option{-e} entirely (e.g., Solaris)
13386 or honor only the last pattern (e.g., @acronym{IRIX} 6.5 and NeXT).  To
13387 work around these problems, invoke @code{AC_PROG_GREP} and then use
13388 @code{$GREP}.
13390 Another possible workaround for the multiple @option{-e} problem is to
13391 separate the patterns by newlines, for example:
13393 @example
13394 grep 'foo
13395 bar' in.txt
13396 @end example
13398 @noindent
13399 except that this fails with traditional @command{grep}
13400 implementations and with Open@acronym{BSD} 3.8 @command{grep}.
13402 Traditional @command{grep} implementations (e.g., Solaris) do not
13403 support the @option{-E} or @option{-F} options.  To work around these
13404 problems, invoke @code{AC_PROG_EGREP} and then use @code{$EGREP}, and
13405 similarly for @code{AC_PROG_FGREP} and @code{$FGREP}.  Even if you are
13406 willing to require support for Posix @command{grep}, your script should
13407 not use both @option{-E} and @option{-F}, since Posix does not allow
13408 this combination.
13410 Portable @command{grep} regular expressions should use @samp{\} only to
13411 escape characters in the string @samp{$()*.0123456789[\^@{@}}.  For example,
13412 alternation, @samp{\|}, is common but Posix does not require its
13413 support in basic regular expressions, so it should be avoided in
13414 portable scripts.  Solaris @command{grep} does not support it.
13415 Similarly, @samp{\+} and @samp{\?} should be avoided.
13418 @item @command{join}
13419 @c -----------------
13420 @prindex @command{join}
13421 Solaris 8 @command{join} has bugs when the second operand is standard
13422 input, and when standard input is a pipe.  For example, the following
13423 shell script causes Solaris 8 @command{join} to loop forever:
13425 @example
13426 cat >file <<'EOF'
13427 1 x
13428 2 y
13430 cat file | join file -
13431 @end example
13433 Use @samp{join - file} instead.
13436 @item @command{ln}
13437 @c ---------------
13438 @prindex @command{ln}
13439 @cindex Symbolic links
13440 Don't rely on @command{ln} having a @option{-f} option.  Symbolic links
13441 are not available on old systems; use @samp{$(LN_S)} as a portable substitute.
13443 For versions of the @acronym{DJGPP} before 2.04,
13444 @command{ln} emulates symbolic links
13445 to executables by generating a stub that in turn calls the real
13446 program.  This feature also works with nonexistent files like in the
13447 Posix spec.  So @samp{ln -s file link} generates @file{link.exe},
13448 which attempts to call @file{file.exe} if run.  But this feature only
13449 works for executables, so @samp{cp -p} is used instead for these
13450 systems.  @acronym{DJGPP} versions 2.04 and later have full support
13451 for symbolic links.
13454 @item @command{ls}
13455 @c ---------------
13456 @prindex @command{ls}
13457 @cindex Listing directories
13458 The portable options are @option{-acdilrtu}.  Current practice is for
13459 @option{-l} to output both owner and group, even though ancient versions
13460 of @command{ls} omitted the group.
13462 On ancient hosts, @samp{ls foo} sent the diagnostic @samp{foo not found}
13463 to standard output if @file{foo} did not exist.  Hence a shell command
13464 like @samp{sources=`ls *.c 2>/dev/null`} did not always work, since it
13465 was equivalent to @samp{sources='*.c not found'} in the absence of
13466 @samp{.c} files.  This is no longer a practical problem, since current
13467 @command{ls} implementations send diagnostics to standard error.
13469 @item @command{mkdir}
13470 @c ------------------
13471 @prindex @command{mkdir}
13472 @cindex Making directories
13473 No @command{mkdir} option is portable to older systems.  Instead of
13474 @samp{mkdir -p @var{file-name}}, you should use use
13475 @code{AS_MKDIR_P(@var{file-name})} (@pxref{Programming in M4sh})
13476 or @code{AC_PROG_MKDIR_P} (@pxref{Particular Programs}).
13478 Posix does not clearly specify whether @samp{mkdir -p foo}
13479 should succeed when @file{foo} is a symbolic link to an already-existing
13480 directory.  The @acronym{GNU} Core Utilities 5.1.0 @command{mkdir}
13481 succeeds, but Solaris @command{mkdir} fails.
13483 Traditional @code{mkdir -p} implementations suffer from race conditions.
13484 For example, if you invoke @code{mkdir -p a/b} and @code{mkdir -p a/c}
13485 at the same time, both processes might detect that @file{a} is missing,
13486 one might create @file{a}, then the other might try to create @file{a}
13487 and fail with a @code{File exists} diagnostic.  The @acronym{GNU} Core
13488 Utilities (@samp{fileutils} version 4.1), Free@acronym{BSD} 5.0,
13489 Net@acronym{BSD} 2.0.2, and Open@acronym{BSD} 2.4 are known to be
13490 race-free when two processes invoke @code{mkdir -p} simultaneously, but
13491 earlier versions are vulnerable.  Solaris @command{mkdir} is still
13492 vulnerable as of Solaris 10, and other traditional Unix systems are
13493 probably vulnerable too.  This possible race is harmful in parallel
13494 builds when several Make rules call @code{mkdir -p} to
13495 construct directories.  You may use
13496 @code{install-sh -d} as a safe replacement, provided this script is
13497 recent enough; the copy shipped with Autoconf 2.60 and Automake 1.10 is
13498 OK, but copies from older versions are vulnerable.
13501 @item @command{mktemp}
13502 @c -------------------
13503 @prindex @command{mktemp}
13504 @cindex Creating temporary files
13505 Shell scripts can use temporary files safely with @command{mktemp}, but
13506 it does not exist on all systems.  A portable way to create a safe
13507 temporary file name is to create a temporary directory with mode 700 and
13508 use a file inside this directory.  Both methods prevent attackers from
13509 gaining control, though @command{mktemp} is far less likely to fail
13510 gratuitously under attack.
13512 Here is sample code to create a new temporary directory safely:
13514 @example
13515 # Create a temporary directory $tmp in $TMPDIR (default /tmp).
13516 # Use mktemp if possible; otherwise fall back on mkdir,
13517 # with $RANDOM to make collisions less likely.
13518 : $@{TMPDIR=/tmp@}
13520   tmp=`
13521     (umask 077 && mktemp -d "$TMPDIR/fooXXXXXX") 2>/dev/null
13522   ` &&
13523   test -n "$tmp" && test -d "$tmp"
13524 @} || @{
13525   tmp=$TMPDIR/foo$$-$RANDOM
13526   (umask 077 && mkdir "$tmp")
13527 @} || exit $?
13528 @end example
13531 @item @command{mv}
13532 @c ---------------
13533 @prindex @command{mv}
13534 @cindex Moving open files
13535 The only portable options are @option{-f} and @option{-i}.
13537 Moving individual files between file systems is portable (it was in Unix
13538 version 6),
13539 but it is not always atomic: when doing @samp{mv new existing}, there's
13540 a critical section where neither the old nor the new version of
13541 @file{existing} actually exists.
13543 On some systems moving files from @file{/tmp} can sometimes cause
13544 undesirable (but perfectly valid) warnings, even if you created these
13545 files.  This is because @file{/tmp} belongs to a group that ordinary
13546 users are not members of, and files created in @file{/tmp} inherit
13547 the group of @file{/tmp}.  When the file is copied, @command{mv} issues
13548 a diagnostic without failing:
13550 @smallexample
13551 $ @kbd{touch /tmp/foo}
13552 $ @kbd{mv /tmp/foo .}
13553 @error{}mv: ./foo: set owner/group (was: 100/0): Operation not permitted
13554 $ @kbd{echo $?}
13556 $ @kbd{ls foo}
13558 @end smallexample
13560 @noindent
13561 This annoying behavior conforms to Posix, unfortunately.
13563 Moving directories across mount points is not portable, use @command{cp}
13564 and @command{rm}.
13566 @acronym{DOS} variants cannot rename or remove open files, and do not
13567 support commands like @samp{mv foo bar >foo}, even though this is
13568 perfectly portable among Posix hosts.
13571 @item @command{od}
13572 @c ---------------
13573 @prindex @command{od}
13575 In Mac OS X 10.3, @command{od} does not support the
13576 standard Posix options @option{-A}, @option{-j}, @option{-N}, or
13577 @option{-t}, or the @acronym{XSI} option @option{-s}.  The only
13578 supported Posix option is @option{-v}, and the only supported
13579 @acronym{XSI} options are those in @option{-bcdox}.  The @acronym{BSD}
13580 @command{hexdump} program can be used instead.
13582 This problem no longer exists in Mac OS X 10.4.3.
13585 @item @command{rm}
13586 @c ---------------
13587 @prindex @command{rm}
13588 The @option{-f} and @option{-r} options are portable.
13590 A file might not be be removed even if its parent directory is writable
13591 and searchable.  Many Posix hosts cannot remove a mount point, a named
13592 stream, a working directory, or a last link to a file that is being
13593 executed.
13595 @acronym{DOS} variants cannot rename or remove open files, and do not
13596 support commands like @samp{rm foo >foo}, even though this is
13597 perfectly portable among Posix hosts.
13600 @item @command{sed}
13601 @c ----------------
13602 @prindex @command{sed}
13603 Patterns should not include the separator (unless escaped), even as part
13604 of a character class.  In conformance with Posix, the Cray
13605 @command{sed} rejects @samp{s/[^/]*$//}: use @samp{s,[^/]*$,,}.
13607 Avoid empty patterns within parentheses (i.e., @samp{\(\)}).  Posix does
13608 not require support for empty patterns, and Unicos 9 @command{sed} rejects
13609 them.
13611 Unicos 9 @command{sed} loops endlessly on patterns like @samp{.*\n.*}.
13613 Sed scripts should not use branch labels longer than 8 characters and
13614 should not contain comments.  @acronym{HP-UX} sed has a limit of 99 commands
13615 (not counting @samp{:} commands) and
13616 48 labels, which can not be circumvented by using more than one script
13617 file.  It can execute up to 19 reads with the @samp{r} command per cycle.
13618 Solaris @command{/usr/ucb/sed} rejects usages that exceed an limit of
13619 about 6000 bytes for the internal representation of commands.
13621 Avoid redundant @samp{;}, as some @command{sed} implementations, such as
13622 Net@acronym{BSD} 1.4.2's, incorrectly try to interpret the second
13623 @samp{;} as a command:
13625 @example
13626 $ @kbd{echo a | sed 's/x/x/;;s/x/x/'}
13627 sed: 1: "s/x/x/;;s/x/x/": invalid command code ;
13628 @end example
13630 Input should not have unreasonably long lines, since some @command{sed}
13631 implementations have an input buffer limited to 4000 bytes.
13633 Portable @command{sed} regular expressions should use @samp{\} only to escape
13634 characters in the string @samp{$()*.0123456789[\^n@{@}}.  For example,
13635 alternation, @samp{\|}, is common but Posix does not require its
13636 support, so it should be avoided in portable scripts.  Solaris
13637 @command{sed} does not support alternation; e.g., @samp{sed '/a\|b/d'}
13638 deletes only lines that contain the literal string @samp{a|b}.
13639 Similarly, @samp{\+} and @samp{\?} should be avoided.
13641 Anchors (@samp{^} and @samp{$}) inside groups are not portable.
13643 Nested parenthesization in patterns (e.g., @samp{\(\(a*\)b*)\)}) is
13644 quite portable to current hosts, but was not supported by some ancient
13645 @command{sed} implementations like SVR3.
13647 Some @command{sed} implementations, e.g., Solaris,
13648 restrict the special role of the asterisk to one-character regular expressions.
13649 This may lead to unexpected behavior:
13651 @example
13652 $ @kbd{echo '1*23*4' | /usr/bin/sed 's/\(.\)*/x/g'}
13653 x2x4
13654 $ @kbd{echo '1*23*4' | /usr/xpg4/bin/sed 's/\(.\)*/x/g'}
13656 @end example
13658 The @option{-e} option is portable, so long as its argument
13659 does not begin with @samp{a}, @samp{c}, or @samp{i}
13660 (as this runs afoul of a Tru64 5.1 bug).
13661 Some people prefer to use @samp{-e}:
13663 @example
13664 sed -e '@var{command-1}' \
13665     -e '@var{command-2}'
13666 @end example
13668 @noindent
13669 as opposed to the equivalent:
13671 @example
13672 sed '
13673   @var{command-1}
13674   @var{command-2}
13676 @end example
13678 @noindent
13679 The following usage is sometimes equivalent:
13681 @example
13682 sed '@var{command-1};@var{command-2}'
13683 @end example
13685 but Posix says that this use of a semicolon has undefined effect if
13686 @var{command-1}'s verb is @samp{@{}, @samp{a}, @samp{b}, @samp{c},
13687 @samp{i}, @samp{r}, @samp{t}, @samp{w}, @samp{:}, or @samp{#}, so you
13688 should use semicolon only with simple scripts that do not use these
13689 verbs.
13691 Commands inside @{ @} brackets are further restricted.  Posix says that
13692 they cannot be preceded by addresses, @samp{!}, or @samp{;}, and that
13693 each command must be followed immediately by a newline, without any
13694 intervening blanks or semicolons.  The closing bracket must be alone on
13695 a line, other than white space preceding or following it.
13697 Contrary to yet another urban legend, you may portably use @samp{&} in
13698 the replacement part of the @code{s} command to mean ``what was
13699 matched''.  All descendants of Unix version 7 @command{sed}
13700 (at least; we
13701 don't have first hand experience with older @command{sed} implementations) have
13702 supported it.
13704 Posix requires that you must not have any white space between
13705 @samp{!} and the following command.  It is OK to have blanks between
13706 the address and the @samp{!}.  For instance, on Solaris:
13708 @example
13709 $ @kbd{echo "foo" | sed -n '/bar/ ! p'}
13710 @error{}Unrecognized command: /bar/ ! p
13711 $ @kbd{echo "foo" | sed -n '/bar/! p'}
13712 @error{}Unrecognized command: /bar/! p
13713 $ @kbd{echo "foo" | sed -n '/bar/ !p'}
13715 @end example
13717 Posix also says that you should not combine @samp{!} and @samp{;}.  If
13718 you use @samp{!}, it is best to put it on a command that is delimited by
13719 newlines rather than @samp{;}.
13721 Also note that Posix requires that the @samp{b}, @samp{t}, @samp{r}, and
13722 @samp{w} commands be followed by exactly one space before their argument.
13723 On the other hand, no white space is allowed between @samp{:} and the
13724 subsequent label name.
13726 If a sed script is specified on the command line and ends in an
13727 @samp{a}, @samp{c}, or @samp{i} command, the last line of inserted text
13728 should be followed by a newline.  Otherwise some @command{sed}
13729 implementations (e.g., Open@acronym{BSD} 3.9) do not append a newline to the
13730 inserted text.
13732 Many @command{sed} implementations (e.g., MacOS X 10.4,
13733 Open@acronym{BSD} 3.9, Solaris 10
13734 @command{/usr/ucb/sed}) strip leading white space from the text of
13735 @samp{a}, @samp{c}, and @samp{i} commands.  Prepend a backslash to
13736 work around this incompatibility with Posix:
13738 @example
13739 $ @kbd{echo flushleft | sed 'a\}
13740 > @kbd{   indented}
13741 > @kbd{'}
13742 flushleft
13743 indented
13744 $ @kbd{echo foo | sed 'a\}
13745 > @kbd{\   indented}
13746 > @kbd{'}
13747 flushleft
13748    indented
13749 @end example
13752 @item @command{sed} (@samp{t})
13753 @c ---------------------------
13754 @prindex @command{sed} (@samp{t})
13755 Some old systems have @command{sed} that ``forget'' to reset their
13756 @samp{t} flag when starting a new cycle.  For instance on @acronym{MIPS
13757 RISC/OS}, and on @sc{irix} 5.3, if you run the following @command{sed}
13758 script (the line numbers are not actual part of the texts):
13760 @example
13761 s/keep me/kept/g  # a
13762 t end             # b
13763 s/.*/deleted/g    # c
13764 :end              # d
13765 @end example
13767 @noindent
13770 @example
13771 delete me         # 1
13772 delete me         # 2
13773 keep me           # 3
13774 delete me         # 4
13775 @end example
13777 @noindent
13778 you get
13780 @example
13781 deleted
13782 delete me
13783 kept
13784 deleted
13785 @end example
13787 @noindent
13788 instead of
13790 @example
13791 deleted
13792 deleted
13793 kept
13794 deleted
13795 @end example
13797 Why?  When processing line 1, (c) matches, therefore sets the @samp{t}
13798 flag, and the output is produced.  When processing
13799 line 2, the @samp{t} flag is still set (this is the bug).  Command (a)
13800 fails to match, but @command{sed} is not supposed to clear the @samp{t}
13801 flag when a substitution fails.  Command (b) sees that the flag is set,
13802 therefore it clears it, and jumps to (d), hence you get @samp{delete me}
13803 instead of @samp{deleted}.  When processing line (3), @samp{t} is clear,
13804 (a) matches, so the flag is set, hence (b) clears the flags and jumps.
13805 Finally, since the flag is clear, line 4 is processed properly.
13807 There are two things one should remember about @samp{t} in @command{sed}.
13808 Firstly, always remember that @samp{t} jumps if @emph{some} substitution
13809 succeeded, not only the immediately preceding substitution.  Therefore,
13810 always use a fake @samp{t clear} followed by a @samp{:clear} on the next
13811 line, to reset the @samp{t} flag where needed.
13813 Secondly, you cannot rely on @command{sed} to clear the flag at each new
13814 cycle.
13816 One portable implementation of the script above is:
13818 @example
13819 t clear
13820 :clear
13821 s/keep me/kept/g
13822 t end
13823 s/.*/deleted/g
13824 :end
13825 @end example
13827 @item @command{touch}
13828 @c ------------------
13829 @prindex @command{touch}
13830 @cindex timestamp resolution
13831 If you specify the desired timestamp (e.g., with the @option{-r}
13832 option), @command{touch} typically uses the @code{utime} or
13833 @code{utimes} system call, which can result in the same kind of
13834 timestamp truncation problems that @samp{cp -p} has.
13836 On ancient @acronym{BSD} systems, @command{touch} or any command that
13837 results in an empty file does not update the timestamps, so use a
13838 command like @command{echo} as a workaround.
13839 Also,
13840 @acronym{GNU} @command{touch} 3.16r (and presumably all before that)
13841 fails to work on SunOS 4.1.3 when the empty file is on an
13842 @acronym{NFS}-mounted 4.2 volume.
13843 However, these problems are no longer of practical concern.
13845 @end table
13848 @node Portable Make
13849 @chapter Portable Make Programming
13850 @prindex @command{make}
13851 @cindex Limitations of @command{make}
13853 Writing portable makefiles is an art.  Since a makefile's commands are
13854 executed by the shell, you must consider the shell portability issues
13855 already mentioned.  However, other issues are specific to @command{make}
13856 itself.
13858 @menu
13859 * $< in Ordinary Make Rules::   $< in ordinary rules
13860 * Failure in Make Rules::       Failing portably in rules
13861 * Special Chars in Names::      Special Characters in Macro Names
13862 * Backslash-Newline-Newline::   Empty last lines in macro definitions
13863 * Backslash-Newline Comments::  Spanning comments across line boundaries
13864 * Long Lines in Makefiles::     Line length limitations
13865 * Macros and Submakes::         @code{make macro=value} and submakes
13866 * The Make Macro MAKEFLAGS::    @code{$(MAKEFLAGS)} portability issues
13867 * The Make Macro SHELL::        @code{$(SHELL)} portability issues
13868 * Comments in Make Rules::      Other problems with Make comments
13869 * obj/ and Make::               Don't name a subdirectory @file{obj}
13870 * make -k Status::              Exit status of @samp{make -k}
13871 * VPATH and Make::              @code{VPATH} woes
13872 * Single Suffix Rules::         Single suffix rules and separated dependencies
13873 * Timestamps and Make::         Subsecond timestamp resolution
13874 @end menu
13876 @node $< in Ordinary Make Rules
13877 @section @code{$<} in Ordinary Make Rules
13879 Posix says that the @samp{$<} construct in makefiles can be
13880 used only in inference rules and in the @samp{.DEFAULT} rule; its
13881 meaning in ordinary rules is unspecified.  Solaris @command{make}
13882 for instance replaces it with the empty string.  Open@acronym{BSD} (3.0 and
13883 later) @command{make} diagnoses these uses and errors out.
13885 @node Failure in Make Rules
13886 @section Failure in Make Rules
13888 Since 1992 Posix has required that @command{make} must invoke
13889 each command with the equivalent of a @samp{sh -c} subshell.  However,
13890 many @command{make} implementations, including @acronym{BSD} make through 2004,
13891 use @samp{sh -e -c} instead, and the @option{-e} option causes the
13892 subshell to exit immediately if a subsidiary simple-command fails.  For
13893 example, the command @samp{touch T; rm -f U} always attempts to
13894 remove @file{U} with Posix make, but incompatible
13895 @command{make} implementations skip the @command{rm} if the
13896 @command{touch} fails.  One way to work around this is to reword the
13897 affected simple-commands so that they always succeed, e.g., @samp{touch
13898 T || :; rm -f U}.
13899 However, even this approach can run into common bugs in @acronym{BSD}
13900 implementations of the @option{-e} option of @command{sh} and
13901 @command{set} (@pxref{Limitations of Builtins}), so if you are worried
13902 about porting to buggy @acronym{BSD} shells it may be simpler to migrate
13903 complicated @command{make} actions into separate scripts.
13905 @node Special Chars in Names
13906 @section Special Characters in Make Macro Names
13908 Posix limits macro names to nonempty strings containing only
13909 @acronym{ASCII} letters and digits, @samp{.}, and @samp{_}.  Many
13910 @command{make} implementations allow a wider variety of characters, but
13911 portable makefiles should avoid them.  It is portable to start a name
13912 with a special character, e.g., @samp{$(.FOO)}.
13914 Some ancient @command{make} implementations don't support leading
13915 underscores in macro names.  An example is @acronym{NEWS-OS} 4.2R.
13917 @example
13918 $ @kbd{cat Makefile}
13919 _am_include = #
13920 _am_quote =
13921 all:; @@echo this is test
13922 $ @kbd{make}
13923 Make: Must be a separator on rules line 2.  Stop.
13924 $ @kbd{cat Makefile2}
13925 am_include = #
13926 am_quote =
13927 all:; @@echo this is test
13928 $ @kbd{make -f Makefile2}
13929 this is test
13930 @end example
13932 @noindent
13933 However, this problem is no longer of practical concern.
13935 @node Backslash-Newline-Newline
13936 @section Backslash-Newline-Newline in Make Macro Values
13938 @c  This has been seen on ia64 hpux 11.20, and on one hppa hpux 10.20,
13939 @c  but another hppa hpux 10.20 didn't have it.  Bob Proulx
13940 @c  <bob@proulx.com> thinks it was in hpux 8.0 too.
13941 On some versions of @acronym{HP-UX}, @command{make} reads multiple newlines
13942 following a backslash, continuing to the next non-empty line.  For
13943 example,
13945 @example
13946 FOO = one \
13948 BAR = two
13950 test:
13951         : FOO is "$(FOO)"
13952         : BAR is "$(BAR)"
13953 @end example
13955 @noindent
13956 shows @code{FOO} equal to @code{one BAR = two}.  Other implementations
13957 sensibly let a backslash continue only to the immediately following
13958 line.
13960 @node Backslash-Newline Comments
13961 @section Backslash-Newline in Make Comments
13963 According to Posix, Make comments start with @code{#}
13964 and continue until an unescaped newline is reached.
13966 @example
13967 $ @kbd{cat Makefile}
13968 # A = foo \
13969       bar \
13970       baz
13972 all:
13973         @@echo ok
13974 $ @kbd{make}   # GNU make
13976 @end example
13978 @noindent
13979 However this is not always the case.  Some implementations
13980 discard everything from @code{#} through the end of the line, ignoring any
13981 trailing backslash.
13983 @example
13984 $ @kbd{pmake}  # BSD make
13985 "Makefile", line 3: Need an operator
13986 Fatal errors encountered -- cannot continue
13987 @end example
13989 @noindent
13990 Therefore, if you want to comment out a multi-line definition, prefix each
13991 line with @code{#}, not only the first.
13993 @example
13994 # A = foo \
13995 #     bar \
13996 #     baz
13997 @end example
13999 @node Long Lines in Makefiles
14000 @section Long Lines in Makefiles
14002 Tru64 5.1's @command{make} has been reported to crash when given a
14003 makefile with lines longer than around 20 kB.  Earlier versions are
14004 reported to exit with @code{Line too long} diagnostics.
14006 @node Macros and Submakes
14007 @section @code{make macro=value} and Submakes
14009 A command-line variable definition such as @code{foo=bar} overrides any
14010 definition of @code{foo} in a makefile.  Some @command{make}
14011 implementations (such as @acronym{GNU} @command{make}) propagate this
14012 override to subsidiary invocations of @command{make}.  Some other
14013 implementations do not pass the substitution along to submakes.
14015 @example
14016 $ @kbd{cat Makefile}
14017 foo = foo
14018 one:
14019         @@echo $(foo)
14020         $(MAKE) two
14021 two:
14022         @@echo $(foo)
14023 $ @kbd{make foo=bar}            # GNU make 3.79.1
14025 make two
14026 make[1]: Entering directory `/home/adl'
14028 make[1]: Leaving directory `/home/adl'
14029 $ @kbd{pmake foo=bar}           # BSD make
14031 pmake two
14033 @end example
14035 You have a few possibilities if you do want the @code{foo=bar} override
14036 to propagate to submakes.  One is to use the @option{-e}
14037 option, which causes all environment variables to have precedence over
14038 the makefile macro definitions, and declare foo as an environment
14039 variable:
14041 @example
14042 $ @kbd{env foo=bar make -e}
14043 @end example
14045 The @option{-e} option is propagated to submakes automatically,
14046 and since the environment is inherited between @command{make}
14047 invocations, the @code{foo} macro is overridden in
14048 submakes as expected.
14050 This syntax (@code{foo=bar make -e}) is portable only when used
14051 outside of a makefile, for instance from a script or from the
14052 command line.  When run inside a @command{make} rule, @acronym{GNU}
14053 @command{make} 3.80 and prior versions forget to propagate the
14054 @option{-e} option to submakes.
14056 Moreover, using @option{-e} could have unexpected side effects if your
14057 environment contains some other macros usually defined by the
14058 makefile.  (See also the note about @code{make -e} and @code{SHELL}
14059 below.)
14061 Another way to propagate overrides to submakes is to do it
14062 manually, from your makefile:
14064 @example
14065 foo = foo
14066 one:
14067         @@echo $(foo)
14068         $(MAKE) foo=$(foo) two
14069 two:
14070         @@echo $(foo)
14071 @end example
14073 You need to foresee all macros that a user might want to override if
14074 you do that.
14076 @node The Make Macro MAKEFLAGS
14077 @section The Make Macro MAKEFLAGS
14078 @cindex @code{MAKEFLAGS} and @command{make}
14079 @cindex @command{make} and @code{MAKEFLAGS}
14081 Posix requires @command{make} to use @code{MAKEFLAGS} to affect the
14082 current and recursive invocations of make, but allows implementations
14083 several formats for the variable.  It is tricky to parse
14084 @code{$MAKEFLAGS} to determine whether @option{-s} for silent execution
14085 or @option{-k} for continued execution are in effect.  For example, you
14086 cannot assume that the first space-separated word in @code{$MAKEFLAGS}
14087 contains single-letter options, since in the Cygwin version of
14088 @acronym{GNU} @command{make} it is either @option{--unix} or
14089 @option{--win32} with the second word containing single-letter options.
14091 @example
14092 $ @kbd{cat Makefile}
14093 all:
14094         @@echo MAKEFLAGS = $(MAKEFLAGS)
14095 $ @kbd{make}
14096 MAKEFLAGS = --unix
14097 $ @kbd{make -k}
14098 MAKEFLAGS = --unix -k
14099 @end example
14101 @node The Make Macro SHELL
14102 @section The Make Macro @code{SHELL}
14103 @cindex @code{SHELL} and @command{make}
14104 @cindex @command{make} and @code{SHELL}
14106 Posix-compliant @command{make} internally uses the @code{$(SHELL)}
14107 macro to spawn shell processes and execute Make rules.  This
14108 is a builtin macro supplied by @command{make}, but it can be modified
14109 by a makefile or by a command-line argument.
14111 Not all @command{make} implementations define this @code{SHELL} macro.
14112 Tru64
14113 @command{make} is an example; this implementation always uses
14114 @code{/bin/sh}.  So it's a good idea to always define @code{SHELL} in
14115 your makefiles.  If you use Autoconf, do
14117 @example
14118 SHELL = @@SHELL@@
14119 @end example
14121 Do not force @code{SHELL = /bin/sh} because that is not correct
14122 everywhere.  For instance @acronym{DJGPP} lacks @code{/bin/sh}, and when
14123 its @acronym{GNU} @code{make} port sees such a setting it enters a special
14124 emulation mode where features like pipes and redirections are emulated
14125 on top of DOS's @command{command.com}.  Unfortunately this emulation is
14126 incomplete; for instance it does not handle command substitutions.
14127 On @acronym{DJGPP} @code{SHELL} should point to Bash.
14129 Posix-compliant @command{make} should never acquire the value of
14130 $(SHELL) from the environment, even when @code{make -e} is used
14131 (otherwise, think about what would happen to your rules if
14132 @code{SHELL=/bin/tcsh}).
14134 However not all @command{make} implementations have this exception.
14135 For instance it's not surprising that Tru64 @command{make} doesn't
14136 protect @code{SHELL}, since it doesn't use it.
14138 @example
14139 $ @kbd{cat Makefile}
14140 SHELL = /bin/sh
14141 FOO = foo
14142 all:
14143         @@echo $(SHELL)
14144         @@echo $(FOO)
14145 $ @kbd{env SHELL=/bin/tcsh FOO=bar make -e}   # Tru64 Make
14146 /bin/tcsh
14148 $ @kbd{env SHELL=/bin/tcsh FOO=bar gmake -e}  # GNU make
14149 /bin/sh
14151 @end example
14153 @node Comments in Make Rules
14154 @section Comments in Make Rules
14155 @cindex Comments in @file{Makefile} rules
14156 @cindex @file{Makefile} rules and comments
14158 Never put comments in a rule.
14160 Some @command{make} treat anything starting with a tab as a command for
14161 the current rule, even if the tab is immediately followed by a @code{#}.
14162 The @command{make} from Tru64 Unix V5.1 is one of them.  The following
14163 makefile runs @code{# foo} through the shell.
14165 @example
14166 all:
14167         # foo
14168 @end example
14170 @node obj/ and Make
14171 @section The @file{obj/} Subdirectory and Make
14172 @cindex @file{obj/}, subdirectory
14173 @cindex @acronym{BSD} @command{make} and @file{obj/}
14175 Never name one of your subdirectories @file{obj/} if you don't like
14176 surprises.
14178 If an @file{obj/} directory exists, @acronym{BSD} @command{make} enters it
14179 before reading the makefile.  Hence the makefile in the
14180 current directory is not read.
14182 @example
14183 $ @kbd{cat Makefile}
14184 all:
14185         echo Hello
14186 $ @kbd{cat obj/Makefile}
14187 all:
14188         echo World
14189 $ @kbd{make}      # GNU make
14190 echo Hello
14191 Hello
14192 $ @kbd{pmake}     # BSD make
14193 echo World
14194 World
14195 @end example
14197 @node make -k Status
14198 @section Exit Status of @code{make -k}
14199 @cindex @code{make -k}
14201 Do not rely on the exit status of @code{make -k}.  Some implementations
14202 reflect whether they encountered an error in their exit status; other
14203 implementations always succeed.
14205 @example
14206 $ @kbd{cat Makefile}
14207 all:
14208         false
14209 $ @kbd{make -k; echo exit status: $?}    # GNU make
14210 false
14211 make: *** [all] Error 1
14212 exit status: 2
14213 $ @kbd{pmake -k; echo exit status: $?}   # BSD make
14214 false
14215 *** Error code 1 (continuing)
14216 exit status: 0
14217 @end example
14219 @node VPATH and Make
14220 @section @code{VPATH} and Make
14221 @cindex @code{VPATH}
14223 Posix does not specify the semantics of @code{VPATH}.  Typically,
14224 @command{make} supports @code{VPATH}, but its implementation is not
14225 consistent.
14227 Autoconf and Automake support makefiles whose usages of @code{VPATH} are
14228 portable to recent-enough popular implementations of @command{make}, but
14229 to keep the resulting makefiles portable, a package's makefile
14230 prototypes must take the following issues into account.  These issues
14231 are complicated and are often poorly understood, and installers who use
14232 @code{VPATH} should expect to find many bugs in this area.  If you use
14233 @code{VPATH}, the simplest way to avoid these portability bugs is to
14234 stick with @acronym{GNU} @command{make}, since it is the most
14235 commonly-used @command{make} among Autoconf users.
14237 Here are some known issues with some @code{VPATH}
14238 implementations.
14240 @menu
14241 * VPATH and Double-colon::      Problems with @samp{::} on ancient hosts
14242 * $< in Explicit Rules::        @code{$<} does not work in ordinary rules
14243 * Automatic Rule Rewriting::    @code{VPATH} goes wild on Solaris
14244 * Tru64 Directory Magic::       @command{mkdir} goes wild on Tru64
14245 * Make Target Lookup::          More details about @code{VPATH} lookup
14246 @end menu
14248 @node VPATH and Double-colon
14249 @subsection @code{VPATH} and Double-colon Rules
14250 @cindex @code{VPATH} and double-colon rules
14251 @cindex double-colon rules and @code{VPATH}
14253 With ancient versions of Sun @command{make},
14254 any assignment to @code{VPATH} causes @command{make} to execute only
14255 the first set of double-colon rules.
14256 However, this problem is no longer of practical concern.
14258 @node $< in Explicit Rules
14259 @subsection @code{$<} Not Supported in Explicit Rules
14260 @cindex explicit rules, @code{$<}, and @code{VPATH}
14261 @cindex @code{$<}, explicit rules, and @code{VPATH}
14262 @cindex @code{VPATH}, explicit rules, and @code{$<}
14264 Using @code{$<} in explicit rules is not portable.
14265 The prerequisite file must be named explicitly in the rule.  If you want
14266 to find the prerequisite via a @code{VPATH} search, you have to code the
14267 whole thing manually.  @xref{Build Directories}.
14269 @node Automatic Rule Rewriting
14270 @subsection Automatic Rule Rewriting
14271 @cindex @code{VPATH} and automatic rule rewriting
14272 @cindex automatic rule rewriting and @code{VPATH}
14274 Some @command{make} implementations, such as Solaris and Tru64,
14275 search for prerequisites in @code{VPATH} and
14276 then rewrite each occurrence as a plain word in the rule.
14277 For instance:
14279 @example
14280 # This isn't portable to GNU make.
14281 VPATH = ../pkg/src
14282 f.c: if.c
14283         cp if.c f.c
14284 @end example
14286 @noindent
14287 executes @code{cp ../pkg/src/if.c f.c} if @file{if.c} is
14288 found in @file{../pkg/src}.
14290 However, this rule leads to real problems in practice.  For example, if
14291 the source directory contains an ordinary file named @file{test} that is
14292 used in a dependency, Solaris @command{make} rewrites commands like
14293 @samp{if test -r foo; @dots{}} to @samp{if ../pkg/src/test -r foo;
14294 @dots{}}, which is typically undesirable.  To avoid this problem,
14295 portable makefiles should never mention a source file whose name is that
14296 of a shell keyword like @file{until} or a shell command like
14297 @command{cat} or @command{gcc} or @command{test}.
14299 Because of these problems @acronym{GNU} @command{make} and many other
14300 @command{make} implementations do not rewrite commands, so portable
14301 makefiles should
14302 search @code{VPATH} manually.  It is tempting to write this:
14304 @smallexample
14305 # This isn't portable to Solaris make.
14306 VPATH = ../pkg/src
14307 f.c: if.c
14308         cp `test -f if.c || echo $(VPATH)/`if.c f.c
14309 @end smallexample
14311 @noindent
14312 However, the ``prerequisite rewriting'' still applies here.  So if
14313 @file{if.c} is in @file{../pkg/src}, Solaris and Tru64 @command{make}
14314 execute
14316 @smallexample
14317 cp `test -f ../pkg/src/if.c || echo ../pkg/src/`if.c f.c
14318 @end smallexample
14320 @noindent
14321 which reduces to
14323 @example
14324 cp if.c f.c
14325 @end example
14327 @noindent
14328 and thus fails.  Oops.
14330 A simple workaround, and good practice anyway, is to use @samp{$?} and
14331 @samp{$@@} when possible:
14333 @smallexample
14334 VPATH = ../pkg/src
14335 f.c: if.c
14336         cp $? $@@
14337 @end smallexample
14339 @noindent
14340 but this does not generalize well to commands with multiple
14341 prerequisites.  A more general workaround is to rewrite the rule so that
14342 the prerequisite @file{if.c} never appears as a plain word.  For
14343 example, these three rules would be safe, assuming @file{if.c} is in
14344 @file{../pkg/src} and the other files are in the working directory:
14346 @smallexample
14347 VPATH = ../pkg/src
14348 f.c: if.c f1.c
14349         cat `test -f ./if.c || echo $(VPATH)/`if.c f1.c >$@@
14350 g.c: if.c g1.c
14351         cat `test -f 'if.c' || echo $(VPATH)/`if.c g1.c >$@@
14352 h.c: if.c h1.c
14353         cat `test -f "if.c" || echo $(VPATH)/`if.c h1.c >$@@
14354 @end smallexample
14356 Things get worse when your prerequisites are in a macro.
14358 @example
14359 VPATH = ../pkg/src
14360 HEADERS = f.h g.h h.h
14361 install-HEADERS: $(HEADERS)
14362         for i in $(HEADERS); do \
14363           $(INSTALL) -m 644 \
14364             `test -f $$i || echo $(VPATH)/`$$i \
14365             $(DESTDIR)$(includedir)/$$i; \
14366         done
14367 @end example
14369 The above @code{install-HEADERS} rule is not Solaris-proof because @code{for
14370 i in $(HEADERS);} is expanded to @code{for i in f.h g.h h.h;}
14371 where @code{f.h} and @code{g.h} are plain words and are hence
14372 subject to @code{VPATH} adjustments.
14374 If the three files are in @file{../pkg/src}, the rule is run as:
14376 @example
14377 for i in ../pkg/src/f.h ../pkg/src/g.h h.h; do \
14378   install -m 644 \
14379      `test -f $i || echo ../pkg/src/`$i \
14380      /usr/local/include/$i; \
14381 done
14382 @end example
14384 where the two first @command{install} calls fail.  For instance,
14385 consider the @code{f.h} installation:
14387 @example
14388 install -m 644 \
14389   `test -f ../pkg/src/f.h || \
14390     echo ../pkg/src/ \
14391   `../pkg/src/f.h \
14392   /usr/local/include/../pkg/src/f.h;
14393 @end example
14395 @noindent
14396 It reduces to:
14398 @example
14399 install -m 644 \
14400   ../pkg/src/f.h \
14401   /usr/local/include/../pkg/src/f.h;
14402 @end example
14404 Note that the manual @code{VPATH} search did not cause any problems here;
14405 however this command installs @file{f.h} in an incorrect directory.
14407 Trying to quote @code{$(HEADERS)} in some way, as we did for
14408 @code{foo.c} a few makefiles ago, does not help:
14410 @example
14411 install-HEADERS: $(HEADERS)
14412         headers='$(HEADERS)'; \
14413         for i in $$headers; do \
14414           $(INSTALL) -m 644 \
14415             `test -f $$i || echo $(VPATH)/`$$i \
14416             $(DESTDIR)$(includedir)/$$i; \
14417         done
14418 @end example
14420 Now, @code{headers='$(HEADERS)'} macroexpands to:
14422 @example
14423 headers='f.h g.h h.h'
14424 @end example
14426 @noindent
14427 but @code{g.h} is still a plain word.  (As an aside, the idiom
14428 @code{headers='$(HEADERS)'; for i in $$headers;} is a good
14429 idea if @code{$(HEADERS)} can be empty, because some shells diagnose a
14430 syntax error on @code{for i in;}.)
14432 One workaround is to strip this unwanted @file{../pkg/src/} prefix manually:
14434 @example
14435 VPATH = ../pkg/src
14436 HEADERS = f.h g.h h.h
14437 install-HEADERS: $(HEADERS)
14438         headers='$(HEADERS)'; \
14439         for i in $$headers; do \
14440           i=`expr "$$i" : '$(VPATH)/\(.*\)'`;
14441           $(INSTALL) -m 644 \
14442             `test -f $$i || echo $(VPATH)/`$$i \
14443             $(DESTDIR)$(includedir)/$$i; \
14444         done
14445 @end example
14447 Automake does something similar.  However the above hack works only if
14448 the files listed in @code{HEADERS} are in the current directory or a
14449 subdirectory; they should not be in an enclosing directory.  If we had
14450 @code{HEADERS = ../f.h}, the above fragment would fail in a VPATH
14451 build with Tru64 @command{make}.  The reason is that not only does
14452 Tru64 @command{make} rewrite dependencies, but it also simplifies
14453 them.  Hence @code{../f.h} becomes @code{../pkg/f.h} instead of
14454 @code{../pkg/src/../f.h}.  This obviously defeats any attempt to strip
14455 a leading @file{../pkg/src/} component.
14457 The following example makes the behavior of Tru64 @command{make}
14458 more apparent.
14460 @example
14461 $ @kbd{cat Makefile}
14462 VPATH = sub
14463 all: ../foo
14464         echo ../foo
14465 $ @kbd{ls}
14466 Makefile foo
14467 $ @kbd{make}
14468 echo foo
14470 @end example
14472 @noindent
14473 Dependency @file{../foo} was found in @file{sub/../foo}, but Tru64
14474 @command{make} simplified it as @file{foo}.  (Note that the @file{sub/}
14475 directory does not even exist, this just means that the simplification
14476 occurred before the file was checked for.)
14478 For the record here is how SunOS 4 @command{make} behaves on this
14479 example.
14481 @smallexample
14482 $ @kbd{make}
14483 make: Fatal error: Don't know how to make target `../foo'
14484 $ @kbd{mkdir sub}
14485 $ @kbd{make}
14486 echo sub/../foo
14487 sub/../foo
14488 @end smallexample
14491 @node Tru64 Directory Magic
14492 @subsection Tru64 @command{make} Creates Prerequisite Directories Magically
14493 @cindex @code{VPATH} and prerequisite directories
14494 @cindex prerequisite directories and @code{VPATH}
14496 When a prerequisite is a subdirectory of @code{VPATH}, Tru64
14497 @command{make} creates it in the current directory.
14499 @example
14500 $ @kbd{mkdir -p foo/bar build}
14501 $ @kbd{cd build}
14502 $ @kbd{cat >Makefile <<END
14503 VPATH = ..
14504 all: foo/bar
14505 END}
14506 $ @kbd{make}
14507 mkdir foo
14508 mkdir foo/bar
14509 @end example
14511 This can yield unexpected results if a rule uses a manual @code{VPATH}
14512 search as presented before.
14514 @example
14515 VPATH = ..
14516 all : foo/bar
14517         command `test -d foo/bar || echo ../`foo/bar
14518 @end example
14520 The above @command{command} is run on the empty @file{foo/bar}
14521 directory that was created in the current directory.
14523 @node Make Target Lookup
14524 @subsection Make Target Lookup
14525 @cindex @code{VPATH}, resolving target pathnames
14527 @acronym{GNU} @command{make} uses a complex algorithm to decide when it
14528 should use files found via a @code{VPATH} search.  @xref{Search
14529 Algorithm, , How Directory Searches are Performed, make, The @acronym{GNU} Make
14530 Manual}.
14532 If a target needs to be rebuilt, @acronym{GNU} @command{make} discards the
14533 file name found during the @code{VPATH} search for this target, and
14534 builds the file locally using the file name given in the makefile.
14535 If a target does not need to be rebuilt, @acronym{GNU} @command{make} uses the
14536 file name found during the @code{VPATH} search.
14538 Other @command{make} implementations, like Net@acronym{BSD} @command{make}, are
14539 easier to describe: the file name found during the @code{VPATH} search
14540 is used whether the target needs to be rebuilt or not.  Therefore
14541 new files are created locally, but existing files are updated at their
14542 @code{VPATH} location.
14544 Open@acronym{BSD} and Free@acronym{BSD} @command{make}, however,
14545 never perform a
14546 @code{VPATH} search for a dependency that has an explicit rule.
14547 This is extremely annoying.
14549 When attempting a @code{VPATH} build for an autoconfiscated package
14550 (e.g., @code{mkdir build && cd build && ../configure}), this means
14551 @acronym{GNU}
14552 @command{make} builds everything locally in the @file{build}
14553 directory, while @acronym{BSD} @command{make} builds new files locally and
14554 updates existing files in the source directory.
14556 @example
14557 $ @kbd{cat Makefile}
14558 VPATH = ..
14559 all: foo.x bar.x
14560 foo.x bar.x: newer.x
14561         @@echo Building $@@
14562 $ @kbd{touch ../bar.x}
14563 $ @kbd{touch ../newer.x}
14564 $ @kbd{make}        # GNU make
14565 Building foo.x
14566 Building bar.x
14567 $ @kbd{pmake}       # NetBSD make
14568 Building foo.x
14569 Building ../bar.x
14570 $ @kbd{fmake}       # FreeBSD make, OpenBSD make
14571 Building foo.x
14572 Building bar.x
14573 $ @kbd{tmake}       # Tru64 make
14574 Building foo.x
14575 Building bar.x
14576 $ @kbd{touch ../bar.x}
14577 $ @kbd{make}        # GNU make
14578 Building foo.x
14579 $ @kbd{pmake}       # NetBSD make
14580 Building foo.x
14581 $ @kbd{fmake}       # FreeBSD make, OpenBSD make
14582 Building foo.x
14583 Building bar.x
14584 $ @kbd{tmake}       # Tru64 make
14585 Building foo.x
14586 Building bar.x
14587 @end example
14589 Note how Net@acronym{BSD} @command{make} updates @file{../bar.x} in its
14590 VPATH location, and how Free@acronym{BSD}, Open@acronym{BSD}, and Tru64
14591 @command{make} always
14592 update @file{bar.x}, even when @file{../bar.x} is up to date.
14594 Another point worth mentioning is that once @acronym{GNU} @command{make} has
14595 decided to ignore a @code{VPATH} file name (e.g., it ignored
14596 @file{../bar.x} in the above example) it continues to ignore it when
14597 the target occurs as a prerequisite of another rule.
14599 The following example shows that @acronym{GNU} @command{make} does not look up
14600 @file{bar.x} in @code{VPATH} before performing the @code{.x.y} rule,
14601 because it ignored the @code{VPATH} result of @file{bar.x} while running
14602 the @code{bar.x: newer.x} rule.
14604 @example
14605 $ @kbd{cat Makefile}
14606 VPATH = ..
14607 all: bar.y
14608 bar.x: newer.x
14609         @@echo Building $@@
14610 .SUFFIXES: .x .y
14611 .x.y:
14612         cp $< $@@
14613 $ @kbd{touch ../bar.x}
14614 $ @kbd{touch ../newer.x}
14615 $ @kbd{make}        # GNU make
14616 Building bar.x
14617 cp bar.x bar.y
14618 cp: cannot stat `bar.x': No such file or directory
14619 make: *** [bar.y] Error 1
14620 $ @kbd{pmake}       # NetBSD make
14621 Building ../bar.x
14622 cp ../bar.x bar.y
14623 $ @kbd{rm bar.y}
14624 $ @kbd{fmake}       # FreeBSD make, OpenBSD make
14625 echo Building bar.x
14626 cp bar.x bar.y
14627 cp: cannot stat `bar.x': No such file or directory
14628 *** Error code 1
14629 $ @kbd{tmake}       # Tru64 make
14630 Building bar.x
14631 cp: bar.x: No such file or directory
14632 *** Exit 1
14633 @end example
14635 Note that if you drop away the command from the @code{bar.x: newer.x}
14636 rule, @acronym{GNU} @command{make} magically starts to work: it
14637 knows that @code{bar.x} hasn't been updated, therefore it doesn't
14638 discard the result from @code{VPATH} (@file{../bar.x}) in succeeding
14639 uses.  Tru64 also works, but Free@acronym{BSD} and Open@acronym{BSD}
14640 still don't.
14642 @example
14643 $ @kbd{cat Makefile}
14644 VPATH = ..
14645 all: bar.y
14646 bar.x: newer.x
14647 .SUFFIXES: .x .y
14648 .x.y:
14649         cp $< $@@
14650 $ @kbd{touch ../bar.x}
14651 $ @kbd{touch ../newer.x}
14652 $ @kbd{make}        # GNU make
14653 cp ../bar.x bar.y
14654 $ @kbd{rm bar.y}
14655 $ @kbd{pmake}       # NetBSD make
14656 cp ../bar.x bar.y
14657 $ @kbd{rm bar.y}
14658 $ @kbd{fmake}       # FreeBSD make, OpenBSD make
14659 cp bar.x bar.y
14660 cp: cannot stat `bar.x': No such file or directory
14661 *** Error code 1
14662 $ @kbd{tmake}       # Tru64 make
14663 cp ../bar.x bar.y
14664 @end example
14666 It seems the sole solution that would please every @command{make}
14667 implementation is to never rely on @code{VPATH} searches for targets.
14668 In other words, @code{VPATH} should be reserved to unbuilt sources.
14671 @node Single Suffix Rules
14672 @section Single Suffix Rules and Separated Dependencies
14673 @cindex Single Suffix Inference Rule
14674 @cindex Rule, Single Suffix Inference
14675 A @dfn{Single Suffix Rule} is basically a usual suffix (inference) rule
14676 (@samp{.from.to:}), but which @emph{destination} suffix is empty
14677 (@samp{.from:}).
14679 @cindex Separated Dependencies
14680 @dfn{Separated dependencies} simply refers to listing the prerequisite
14681 of a target, without defining a rule.  Usually one can list on the one
14682 hand side, the rules, and on the other hand side, the dependencies.
14684 Solaris @command{make} does not support separated dependencies for
14685 targets defined by single suffix rules:
14687 @example
14688 $ @kbd{cat Makefile}
14689 .SUFFIXES: .in
14690 foo: foo.in
14691 .in:
14692         cp $< $@@
14693 $ @kbd{touch foo.in}
14694 $ @kbd{make}
14695 $ @kbd{ls}
14696 Makefile  foo.in
14697 @end example
14699 @noindent
14700 while @acronym{GNU} Make does:
14702 @example
14703 $ @kbd{gmake}
14704 cp foo.in foo
14705 $ @kbd{ls}
14706 Makefile  foo       foo.in
14707 @end example
14709 Note it works without the @samp{foo: foo.in} dependency.
14711 @example
14712 $ @kbd{cat Makefile}
14713 .SUFFIXES: .in
14714 .in:
14715         cp $< $@@
14716 $ @kbd{make foo}
14717 cp foo.in foo
14718 @end example
14720 @noindent
14721 and it works with double suffix inference rules:
14723 @example
14724 $ @kbd{cat Makefile}
14725 foo.out: foo.in
14726 .SUFFIXES: .in .out
14727 .in.out:
14728         cp $< $@@
14729 $ @kbd{make}
14730 cp foo.in foo.out
14731 @end example
14733 As a result, in such a case, you have to write target rules.
14735 @node Timestamps and Make
14736 @section Timestamp Resolution and Make
14737 @cindex timestamp resolution
14738 Traditionally, file timestamps had 1-second resolution, and
14739 @command{make} used those timestamps to determine whether one file was
14740 newer than the other.  However, many modern file systems have
14741 timestamps with 1-nanosecond resolution.  Some @command{make}
14742 implementations look at the entire timestamp; others ignore the
14743 fractional part, which can lead to incorrect results.  Normally this
14744 is not a problem, but in some extreme cases you may need to use tricks
14745 like @samp{sleep 1} to work around timestamp truncation bugs.
14747 Commands like @samp{cp -p} and @samp{touch -r} typically do not copy
14748 file timestamps to their full resolutions (@pxref{Limitations of Usual
14749 Tools}).  Hence you should be wary of rules like this:
14751 @example
14752 dest: src
14753         cp -p src dest
14754 @end example
14756 as @file{dest} often appears to be older than @file{src} after the
14757 timestamp is truncated, and this can cause @command{make} to do
14758 needless rework the next time it is invoked.  To work around this
14759 problem, you can use a timestamp file, e.g.:
14761 @example
14762 dest-stamp: src
14763         cp -p src dest
14764         date >dest-stamp
14765 @end example
14770 @c ======================================== Portable C and C++ Programming
14772 @node Portable C and C++
14773 @chapter Portable C and C++ Programming
14774 @cindex Portable C and C++ programming
14776 C and C++ programs often use low-level features of the underlying
14777 system, and therefore are often more difficult to make portable to other
14778 platforms.
14780 Several standards have been developed to help make your programs more
14781 portable.  If you write programs with these standards in mind, you can
14782 have greater confidence that your programs work on a wide variety
14783 of systems.  @xref{Standards, , Language Standards Supported by
14784 @acronym{GCC}, gcc, Using the @acronym{GNU} Compiler Collection
14785 (@acronym{GCC})}, for a list of C-related
14786 standards.  Many programs also assume the
14787 @uref{http://www.opengroup.org/susv3, Posix standard}.
14789 Some old code is written to be portable to K&R C, which predates any C
14790 standard.  K&R C compilers are no longer of practical interest, though,
14791 and the rest of section assumes at least C89, the first C standard.
14793 Program portability is a huge topic, and this section can only briefly
14794 introduce common pitfalls.  @xref{System Portability, , Portability
14795 between System Types, standards, @acronym{GNU} Coding Standards}, for
14796 more information.
14798 @menu
14799 * Varieties of Unportability::  How to make your programs unportable
14800 * Integer Overflow::            When integers get too large
14801 * Null Pointers::               Properties of null pointers
14802 * Buffer Overruns::             Subscript errors and the like
14803 * Volatile Objects::            @code{volatile} and signals
14804 * Floating Point Portability::  Portable floating-point arithmetic
14805 * Exiting Portably::            Exiting and the exit status
14806 @end menu
14808 @node Varieties of Unportability
14809 @section Varieties of Unportability
14810 @cindex portability
14812 Autoconf tests and ordinary programs often need to test what is allowed
14813 on a system, and therefore they may need to deliberately exceed the
14814 boundaries of what the standards allow, if only to see whether an
14815 optional feature is present.  When you write such a program, you should
14816 keep in mind the difference between constraints, unspecified behavior,
14817 and undefined behavior.
14819 In C, a @dfn{constraint} is a rule that the compiler must enforce.  An
14820 example constraint is that C programs must not declare a bit-field with
14821 negative width.  Tests can therefore reliably assume that programs with
14822 negative-width bit-fields are rejected by a compiler that conforms
14823 to the standard.
14825 @dfn{Unspecified behavior} is valid behavior, where the standard allows
14826 multiple possibilities.  For example, the order of evaluation of
14827 function arguments is unspecified.  Some unspecified behavior is
14828 @dfn{implementation-defined}, i.e., documented by the implementation,
14829 but since Autoconf tests cannot read the documentation they cannot
14830 distinguish between implementation-defined and other unspecified
14831 behavior.  It is common for Autoconf tests to probe implementations to
14832 determine otherwise-unspecified behavior.
14834 @dfn{Undefined behavior} is invalid behavior, where the standard allows
14835 the implementation to do anything it pleases.  For example,
14836 dereferencing a null pointer leads to undefined behavior.  If possible,
14837 test programs should avoid undefined behavior, since a program with
14838 undefined behavior might succeed on a test that should fail.
14840 The above rules apply to programs that are intended to conform to the
14841 standard.  However, strictly-conforming programs are quite rare, since
14842 the standards are so limiting.  A major goal of Autoconf is to support
14843 programs that use implementation features not described by the standard,
14844 and it is fairly common for test programs to violate the above rules, if
14845 the programs work well enough in practice.
14847 @node Integer Overflow
14848 @section Integer Overflow
14849 @cindex overflow, arithmetic
14851 In C, signed integer overflow leads to undefined behavior.  However,
14852 many programs and Autoconf tests assume that signed integer overflow after
14853 addition, subtraction, or multiplication silently
14854 wraps around modulo a power of two, using two's complement arithmetic,
14855 so long as you cast the resulting value
14856 to an integer type or store it into an integer variable.  Such programs
14857 are portable to the vast majority of modern platforms.  However, signed
14858 integer division is not always harmless: for example, on CPUs of the
14859 i386 family, dividing @code{INT_MIN} by @code{-1} yields a SIGFPE signal
14860 which by default terminates the program.  Worse, taking the remainder
14861 of these two values typically yields the same signal on these CPUs,
14862 even though the C standard requires @code{INT_MIN % -1} to yield zero
14863 because the expression does not overflow.
14865 @acronym{GCC} users might consider using the
14866 @option{-ftrapv} option if they are worried about porting their code to
14867 the rare platforms where signed integer overflow does not wrap around
14868 after addition, subtraction, or multiplication.
14870 Unsigned integer overflow reliably wraps around modulo the word size.
14871 This is guaranteed by the C standard and is portable in practice.
14873 @node Null Pointers
14874 @section Properties of Null Pointers
14875 @cindex null pointers
14877 Most modern hosts reliably fail when you attempt to dereference a null
14878 pointer.
14880 On almost all modern hosts, null pointers use an all-bits-zero internal
14881 representation, so you can reliably use @code{memset} with 0 to set all
14882 the pointers in an array to null values.
14884 If @code{p} is a null pointer to an object type, the C expression
14885 @code{p + 0} always evaluates to @code{p} on modern hosts, even though
14886 the standard says that it has undefined behavior.
14888 @node Buffer Overruns
14889 @section Buffer Overruns and Subscript Errors
14890 @cindex buffer overruns
14892 Buffer overruns and subscript errors are the most common dangerous
14893 errors in C programs.  They result in undefined behavior because storing
14894 outside an array typically modifies storage that is used by some other
14895 object, and most modern systems lack runtime checks to catch these
14896 errors.  Programs should not rely on buffer overruns being caught.
14898 There is one exception to the usual rule that a portable program cannot
14899 address outside an array.  In C, it is valid to compute the address just
14900 past an object, e.g., @code{&a[N]} where @code{a} has @code{N} elements,
14901 so long as you do not dereference the resulting pointer.  But it is not
14902 valid to compute the address just before an object, e.g., @code{&a[-1]};
14903 nor is it valid to compute two past the end, e.g., @code{&a[N+1]}.  On
14904 most platforms @code{&a[-1] < &a[0] && &a[N] < &a[N+1]}, but this is not
14905 reliable in general, and it is usually easy enough to avoid the
14906 potential portability problem, e.g., by allocating an extra unused array
14907 element at the start or end.
14909 @uref{http://valgrind.org/, Valgrind} can catch many overruns.
14910 @acronym{GCC}
14911 users might also consider using the @option{-fmudflap} option to catch
14912 overruns.
14914 Buffer overruns are usually caused by off-by-one errors, but there are
14915 more subtle ways to get them.
14917 Using @code{int} values to index into an array or compute array sizes
14918 causes problems on typical 64-bit hosts where an array index might
14919 be @math{2^31} or larger.  Index values of type @code{size_t} avoid this
14920 problem, but cannot be negative.  Index values of type @code{ptrdiff_t}
14921 are signed, and are wide enough in practice.
14923 If you add or multiply two numbers to calculate an array size, e.g.,
14924 @code{malloc (x * sizeof y + z)}, havoc ensues if the addition or
14925 multiplication overflows.
14927 Many implementations of the @code{alloca} function silently misbehave
14928 and can generate buffer overflows if given sizes that are too large.
14929 The size limits are implementation dependent, but are at least 4000
14930 bytes on all platforms that we know about.
14932 The standard functions @code{asctime}, @code{asctime_r}, @code{ctime},
14933 @code{ctime_r}, and @code{gets} are prone to buffer overflows, and
14934 portable code should not use them unless the inputs are known to be
14935 within certain limits.  The time-related functions can overflow their
14936 buffers if given timestamps out of range (e.g., a year less than -999
14937 or greater than 9999).  Time-related buffer overflows cannot happen with
14938 recent-enough versions of the @acronym{GNU} C library, but are possible
14939 with other
14940 implementations.  The @code{gets} function is the worst, since it almost
14941 invariably overflows its buffer when presented with an input line larger
14942 than the buffer.
14944 @node Volatile Objects
14945 @section Volatile Objects
14946 @cindex volatile objects
14948 The keyword @code{volatile} is often misunderstood in portable code.
14949 Its use inhibits some memory-access optimizations, but programmers often
14950 wish that it had a different meaning than it actually does.
14952 @code{volatile} was designed for code that accesses special objects like
14953 memory-mapped device registers whose contents spontaneously change.
14954 Such code is inherently low-level, and it is difficult to specify
14955 portably what @code{volatile} means in these cases.  The C standard
14956 says, ``What constitutes an access to an object that has
14957 volatile-qualified type is implementation-defined,'' so in theory each
14958 implementation is supposed to fill in the gap by documenting what
14959 @code{volatile} means for that implementation.  In practice, though,
14960 this documentation is usually absent or incomplete.
14962 One area of confusion is the distinction between objects defined with
14963 volatile types, and volatile lvalues.  From the C standard's point of
14964 view, an object defined with a volatile type has externally visible
14965 behavior.  You can think of such objects as having little oscilloscope
14966 probes attached to them, so that the user can observe some properties of
14967 accesses to them, just as the user can observe data written to output
14968 files.  However, the standard does not make it clear whether users can
14969 observe accesses by volatile lvalues to ordinary objects.  For example:
14971 @example
14972 /* Declare and access a volatile object.
14973    Accesses to X are "visible" to users.  */
14974 static int volatile x;
14975 x = 1;
14977 /* Access two ordinary objects via a volatile lvalue.
14978    It's not clear whether accesses to *P are "visible".  */
14979 int y;
14980 int *z = malloc (sizeof (int));
14981 int volatile *p;
14982 p = &y;
14983 *p = 1;
14984 p = z;
14985 *p = 1;
14986 @end example
14988 Programmers often wish that @code{volatile} meant ``Perform the memory
14989 access here and now, without merging several memory accesses, without
14990 changing the memory word size, and without reordering.''  But the C
14991 standard does not require this.  For objects defined with a volatile
14992 type, accesses must be done before the next sequence point; but
14993 otherwise merging, reordering, and word-size change is allowed.  Worse,
14994 it is not clear from the standard whether volatile lvalues provide more
14995 guarantees in general than nonvolatile lvalues, if the underlying
14996 objects are ordinary.
14998 Even when accessing objects defined with a volatile type,
14999 the C standard allows only
15000 extremely limited signal handlers: the behavior is undefined if a signal
15001 handler reads any nonlocal object, or writes to any nonlocal object
15002 whose type is not @code{sig_atomic_t volatile}, or calls any standard
15003 library function other than @code{abort}, @code{signal}, and (if C99)
15004 @code{_Exit}.  Hence C compilers need not worry about a signal handler
15005 disturbing ordinary computation, unless the computation accesses a
15006 @code{sig_atomic_t volatile} lvalue that is not a local variable.
15007 (There is an obscure exception for accesses via a pointer to a volatile
15008 character, since it may point into part of a @code{sig_atomic_t
15009 volatile} object.)  Posix
15010 adds to the list of library functions callable from a portable signal
15011 handler, but otherwise is like the C standard in this area.
15013 Some C implementations allow memory-access optimizations within each
15014 translation unit, such that actual behavior agrees with the behavior
15015 required by the standard only when calling a function in some other
15016 translation unit, and a signal handler acts like it was called from a
15017 different translation unit.  The C standard hints that in these
15018 implementations, objects referred to by signal handlers ``would require
15019 explicit specification of @code{volatile} storage, as well as other
15020 implementation-defined restrictions.''  But unfortunately even for this
15021 special case these other restrictions are often not documented well.
15022 @xref{Volatiles, , When is a Volatile Object Accessed?, gcc, Using the
15023 @acronym{GNU} Compiler Collection (@acronym{GCC})}, for some
15024 restrictions imposed by @acronym{GCC}.  @xref{Defining Handlers, ,
15025 Defining Signal Handlers, libc, The @acronym{GNU} C Library}, for some
15026 restrictions imposed by the @acronym{GNU} C library.  Restrictions
15027 differ on other platforms.
15029 If possible, it is best to use a signal handler that fits within the
15030 limits imposed by the C and Posix standards.
15032 If this is not practical, you can try the following rules of thumb.  A
15033 signal handler should access only volatile lvalues, preferably lvalues
15034 that refer to objects defined with a volatile type, and should not
15035 assume that the accessed objects have an internally consistent state
15036 if they are larger than a machine word.  Furthermore, installers
15037 should employ compilers and compiler options that are commonly used
15038 for building operating system kernels, because kernels often need more
15039 from @code{volatile} than the C Standard requires, and installers who
15040 compile an application in a similar environment can sometimes benefit
15041 from the extra constraints imposed by kernels on compilers.
15042 Admittedly we are handwaving somewhat here, as there are few
15043 guarantees in this area; the rules of thumb may help to fix some bugs
15044 but there is a good chance that they will not fix them all.
15046 For @code{volatile}, C++ has the same problems that C does.
15047 Multithreaded applications have even more problems with @code{volatile},
15048 but they are beyond the scope of this section.
15050 The bottom line is that using @code{volatile} typically hurts
15051 performance but should not hurt correctness.  In some cases its use
15052 does help correctness, but these cases are often so poorly understood
15053 that all too often adding @code{volatile} to a data structure merely
15054 alleviates some symptoms of a bug while not fixing the bug in general.
15056 @node Floating Point Portability
15057 @section Floating Point Portability
15058 @cindex floating point
15060 Almost all modern systems use IEEE-754 floating point, and it is safe to
15061 assume IEEE-754 in most portable code these days.  For more information,
15062 please see David Goldberg's classic paper
15063 @uref{http://www.validlab.com/goldberg/paper.pdf, What Every Computer
15064 Scientist Should Know About Floating-Point Arithmetic}.
15066 @node Exiting Portably
15067 @section Exiting Portably
15068 @cindex exiting portably
15070 A C or C++ program can exit with status @var{N} by returning
15071 @var{N} from the @code{main} function.  Portable programs are supposed
15072 to exit either with status 0 or @code{EXIT_SUCCESS} to succeed, or with
15073 status @code{EXIT_FAILURE} to fail, but in practice it is portable to
15074 fail by exiting with status 1, and test programs that assume Posix can
15075 fail by exiting with status values from 1 through 255.  Programs on
15076 SunOS 2.0 (1985) through 3.5.2 (1988) incorrectly exited with zero
15077 status when @code{main} returned nonzero, but ancient systems like these
15078 are no longer of practical concern.
15080 A program can also exit with status @var{N} by passing @var{N} to the
15081 @code{exit} function, and a program can fail by calling the @code{abort}
15082 function.  If a program is specialized to just some platforms, it can fail
15083 by calling functions specific to those platforms, e.g., @code{_exit}
15084 (Posix) and @code{_Exit} (C99).  However, like other functions, an exit
15085 function should be declared, typically by including a header.  For
15086 example, if a C program calls @code{exit}, it should include @file{stdlib.h}
15087 either directly or via the default includes (@pxref{Default Includes}).
15089 A program can fail due to undefined behavior such as dereferencing a null
15090 pointer, but this is not recommended as undefined behavior allows an
15091 implementation to do whatever it pleases and this includes exiting
15092 successfully.
15095 @c ================================================== Manual Configuration
15097 @node Manual Configuration
15098 @chapter Manual Configuration
15100 A few kinds of features can't be guessed automatically by running test
15101 programs.  For example, the details of the object-file format, or
15102 special options that need to be passed to the compiler or linker.  You
15103 can check for such features using ad-hoc means, such as having
15104 @command{configure} check the output of the @code{uname} program, or
15105 looking for libraries that are unique to particular systems.  However,
15106 Autoconf provides a uniform method for handling unguessable features.
15108 @menu
15109 * Specifying Names::            Specifying the system type
15110 * Canonicalizing::              Getting the canonical system type
15111 * Using System Type::           What to do with the system type
15112 @end menu
15114 @node Specifying Names
15115 @section Specifying the System Type
15116 @cindex System type
15118 Like other @acronym{GNU} @command{configure} scripts, Autoconf-generated
15119 @command{configure} scripts can make decisions based on a canonical name
15120 for the system type, which has the form:
15121 @samp{@var{cpu}-@var{vendor}-@var{os}}, where @var{os} can be
15122 @samp{@var{system}} or @samp{@var{kernel}-@var{system}}
15124 @command{configure} can usually guess the canonical name for the type of
15125 system it's running on.  To do so it runs a script called
15126 @command{config.guess}, which infers the name using the @code{uname}
15127 command or symbols predefined by the C preprocessor.
15129 Alternately, the user can specify the system type with command line
15130 arguments to @command{configure}.  Doing so is necessary when
15131 cross-compiling.  In the most complex case of cross-compiling, three
15132 system types are involved.  The options to specify them are:
15134 @table @option
15135 @item --build=@var{build-type}
15136 the type of system on which the package is being configured and
15137 compiled.  It defaults to the result of running @command{config.guess}.
15139 @item --host=@var{host-type}
15140 the type of system on which the package runs.  By default it is the
15141 same as the build machine.  Specifying it enables the cross-compilation
15142 mode.
15144 @item --target=@var{target-type}
15145 the type of system for which any compiler tools in the package
15146 produce code (rarely needed).  By default, it is the same as host.
15147 @end table
15149 If you mean to override the result of @command{config.guess}, use
15150 @option{--build}, not @option{--host}, since the latter enables
15151 cross-compilation.  For historical reasons, passing @option{--host} also
15152 changes the build type.  Therefore, whenever you specify @option{--host},
15153 be sure to specify @option{--build} too; this will be fixed in the
15154 future.  So, to enter cross-compilation mode, use a command like this
15156 @example
15157 ./configure --build=i686-pc-linux-gnu --host=m68k-coff
15158 @end example
15160 @noindent
15161 Note that if you do not specify @option{--host}, @command{configure}
15162 fails if it can't run the code generated by the specified compiler.  For
15163 example, configuring as follows fails:
15165 @example
15166 ./configure CC=m68k-coff-gcc
15167 @end example
15169 In the future, when cross-compiling Autoconf will @emph{not}
15170 accept tools (compilers, linkers, assemblers) whose name is not
15171 prefixed with the host type.  The only case when this may be
15172 useful is when you really are not cross-compiling, but only
15173 building for a least-common-denominator architecture: an example
15174 is building for @code{i386-pc-linux-gnu} while running on an
15175 @code{i686-pc-linux-gnu} architecture.  In this case, some particular
15176 pairs might be similar enough to let you get away with the system
15177 compilers, but in general the compiler might make bogus assumptions
15178 on the host: if you know what you are doing, please create symbolic
15179 links from the host compiler to the build compiler.
15181 @cindex @command{config.sub}
15182 @command{configure} recognizes short aliases for many system types; for
15183 example, @samp{decstation} can be used instead of
15184 @samp{mips-dec-ultrix4.2}.  @command{configure} runs a script called
15185 @command{config.sub} to canonicalize system type aliases.
15187 This section deliberately omits the description of the obsolete
15188 interface; see @ref{Hosts and Cross-Compilation}.
15191 @node Canonicalizing
15192 @section Getting the Canonical System Type
15193 @cindex System type
15194 @cindex Canonical system type
15196 The following macros make the system type available to @command{configure}
15197 scripts.
15199 @ovindex build_alias
15200 @ovindex host_alias
15201 @ovindex target_alias
15203 The variables @samp{build_alias}, @samp{host_alias}, and
15204 @samp{target_alias} are always exactly the arguments of @option{--build},
15205 @option{--host}, and @option{--target}; in particular, they are left empty
15206 if the user did not use them, even if the corresponding
15207 @code{AC_CANONICAL} macro was run.  Any configure script may use these
15208 variables anywhere.  These are the variables that should be used when in
15209 interaction with the user.
15211 If you need to recognize some special environments based on their system
15212 type, run the following macros to get canonical system names.  These
15213 variables are not set before the macro call.
15215 If you use these macros, you must distribute @command{config.guess} and
15216 @command{config.sub} along with your source code.  @xref{Output}, for
15217 information about the @code{AC_CONFIG_AUX_DIR} macro which you can use
15218 to control in which directory @command{configure} looks for those scripts.
15221 @defmac AC_CANONICAL_BUILD
15222 @acindex{CANONICAL_BUILD}
15223 @ovindex build
15224 @ovindex build_cpu
15225 @ovindex build_vendor
15226 @ovindex build_os
15227 Compute the canonical build-system type variable, @code{build}, and its
15228 three individual parts @code{build_cpu}, @code{build_vendor}, and
15229 @code{build_os}.
15231 If @option{--build} was specified, then @code{build} is the
15232 canonicalization of @code{build_alias} by @command{config.sub},
15233 otherwise it is determined by the shell script @command{config.guess}.
15234 @end defmac
15236 @defmac AC_CANONICAL_HOST
15237 @acindex{CANONICAL_HOST}
15238 @ovindex host
15239 @ovindex host_cpu
15240 @ovindex host_vendor
15241 @ovindex host_os
15242 Compute the canonical host-system type variable, @code{host}, and its
15243 three individual parts @code{host_cpu}, @code{host_vendor}, and
15244 @code{host_os}.
15246 If @option{--host} was specified, then @code{host} is the
15247 canonicalization of @code{host_alias} by @command{config.sub},
15248 otherwise it defaults to @code{build}.
15249 @end defmac
15251 @defmac AC_CANONICAL_TARGET
15252 @acindex{CANONICAL_TARGET}
15253 @ovindex target
15254 @ovindex target_cpu
15255 @ovindex target_vendor
15256 @ovindex target_os
15257 Compute the canonical target-system type variable, @code{target}, and its
15258 three individual parts @code{target_cpu}, @code{target_vendor}, and
15259 @code{target_os}.
15261 If @option{--target} was specified, then @code{target} is the
15262 canonicalization of @code{target_alias} by @command{config.sub},
15263 otherwise it defaults to @code{host}.
15264 @end defmac
15266 Note that there can be artifacts due to the backward compatibility
15267 code.  See @xref{Hosts and Cross-Compilation}, for more.
15269 @node Using System Type
15270 @section Using the System Type
15272 In @file{configure.ac} the system type is generally used by one or more
15273 @code{case} statements to select system-specifics.  Shell wildcards can
15274 be used to match a group of system types.
15276 For example, an extra assembler code object file could be chosen, giving
15277 access to a CPU cycle counter register.  @code{$(CYCLE_OBJ)} in the
15278 following would be used in a makefile to add the object to a
15279 program or library.
15281 @example
15282 case $host in
15283   alpha*-*-*) CYCLE_OBJ=rpcc.o ;;
15284   i?86-*-*)   CYCLE_OBJ=rdtsc.o ;;
15285   *)          CYCLE_OBJ= ;;
15286 esac
15287 AC_SUBST([CYCLE_OBJ])
15288 @end example
15290 @code{AC_CONFIG_LINKS} (@pxref{Configuration Links}) is another good way
15291 to select variant source files, for example optimized code for some
15292 CPUs.  The configured CPU type doesn't always indicate exact CPU types,
15293 so some runtime capability checks may be necessary too.
15295 @example
15296 case $host in
15297   alpha*-*-*)   AC_CONFIG_LINKS([dither.c:alpha/dither.c]) ;;
15298   powerpc*-*-*) AC_CONFIG_LINKS([dither.c:powerpc/dither.c]) ;;
15299   *-*-*)        AC_CONFIG_LINKS([dither.c:generic/dither.c]) ;;
15300 esac
15301 @end example
15303 The host system type can also be used to find cross-compilation tools
15304 with @code{AC_CHECK_TOOL} (@pxref{Generic Programs}).
15306 The above examples all show @samp{$host}, since this is where the code
15307 is going to run.  Only rarely is it necessary to test @samp{$build}
15308 (which is where the build is being done).
15310 Whenever you're tempted to use @samp{$host} it's worth considering
15311 whether some sort of probe would be better.  New system types come along
15312 periodically or previously missing features are added.  Well-written
15313 probes can adapt themselves to such things, but hard-coded lists of
15314 names can't.  Here are some guidelines,
15316 @itemize @bullet
15317 @item
15318 Availability of libraries and library functions should always be checked
15319 by probing.
15320 @item
15321 Variant behavior of system calls is best identified with runtime tests
15322 if possible, but bug workarounds or obscure difficulties might have to
15323 be driven from @samp{$host}.
15324 @item
15325 Assembler code is inevitably highly CPU-specific and is best selected
15326 according to @samp{$host_cpu}.
15327 @item
15328 Assembler variations like underscore prefix on globals or ELF versus
15329 COFF type directives are however best determined by probing, perhaps
15330 even examining the compiler output.
15331 @end itemize
15333 @samp{$target} is for use by a package creating a compiler or similar.
15334 For ordinary packages it's meaningless and should not be used.  It
15335 indicates what the created compiler should generate code for, if it can
15336 cross-compile.  @samp{$target} generally selects various hard-coded CPU
15337 and system conventions, since usually the compiler or tools under
15338 construction themselves determine how the target works.
15341 @c ===================================================== Site Configuration.
15343 @node Site Configuration
15344 @chapter Site Configuration
15346 @command{configure} scripts support several kinds of local configuration
15347 decisions.  There are ways for users to specify where external software
15348 packages are, include or exclude optional features, install programs
15349 under modified names, and set default values for @command{configure}
15350 options.
15352 @menu
15353 * Help Formatting::             Customizing @samp{configure --help}
15354 * External Software::           Working with other optional software
15355 * Package Options::             Selecting optional features
15356 * Pretty Help Strings::         Formatting help string
15357 * Site Details::                Configuring site details
15358 * Transforming Names::          Changing program names when installing
15359 * Site Defaults::               Giving @command{configure} local defaults
15360 @end menu
15362 @node Help Formatting
15363 @section Controlling Help Output
15365 Users consult @samp{configure --help} to learn of configuration
15366 decisions specific to your package.  By default, @command{configure}
15367 breaks this output into sections for each type of option; within each
15368 section, help strings appear in the order @file{configure.ac} defines
15369 them:
15371 @example
15372 Optional Features:
15373   @dots{}
15374   --enable-bar            include bar
15376 Optional Packages:
15377   @dots{}
15378   --with-foo              use foo
15379 @end example
15381 @defmac AC_PRESERVE_HELP_ORDER
15382 @acindex{PRESERVE_HELP_ORDER}
15384 Request an alternate @option{--help} format, in which options of all
15385 types appear together, in the order defined.  Call this macro before any
15386 @code{AC_ARG_ENABLE} or @code{AC_ARG_WITH}.
15388 @example
15389 Optional Features and Packages:
15390   @dots{}
15391   --enable-bar            include bar
15392   --with-foo              use foo
15393 @end example
15395 @end defmac
15397 @node External Software
15398 @section Working With External Software
15399 @cindex External software
15401 Some packages require, or can optionally use, other software packages
15402 that are already installed.  The user can give @command{configure}
15403 command line options to specify which such external software to use.
15404 The options have one of these forms:
15406 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
15407 @c awful.
15408 @example
15409 --with-@var{package}[=@var{arg}]
15410 --without-@var{package}
15411 @end example
15413 For example, @option{--with-gnu-ld} means work with the @acronym{GNU} linker
15414 instead of some other linker.  @option{--with-x} means work with The X
15415 Window System.
15417 The user can give an argument by following the package name with
15418 @samp{=} and the argument.  Giving an argument of @samp{no} is for
15419 packages that are used by default; it says to @emph{not} use the
15420 package.  An argument that is neither @samp{yes} nor @samp{no} could
15421 include a name or number of a version of the other package, to specify
15422 more precisely which other package this program is supposed to work
15423 with.  If no argument is given, it defaults to @samp{yes}.
15424 @option{--without-@var{package}} is equivalent to
15425 @option{--with-@var{package}=no}.
15427 @command{configure} scripts do not complain about
15428 @option{--with-@var{package}} options that they do not support.  This
15429 behavior permits configuring a source tree containing multiple packages
15430 with a top-level @command{configure} script when the packages support
15431 different options, without spurious error messages about options that
15432 some of the packages support.  An unfortunate side effect is that option
15433 spelling errors are not diagnosed.  No better approach to this problem
15434 has been suggested so far.
15436 For each external software package that may be used, @file{configure.ac}
15437 should call @code{AC_ARG_WITH} to detect whether the @command{configure}
15438 user asked to use it.  Whether each package is used or not by default,
15439 and which arguments are valid, is up to you.
15441 @defmac AC_ARG_WITH (@var{package}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given})
15442 @acindex{ARG_WITH}
15443 If the user gave @command{configure} the option @option{--with-@var{package}}
15444 or @option{--without-@var{package}}, run shell commands
15445 @var{action-if-given}.  If neither option was given, run shell commands
15446 @var{action-if-not-given}.  The name @var{package} indicates another
15447 software package that this program should work with.  It should consist
15448 only of alphanumeric characters and dashes.
15450 The option's argument is available to the shell commands
15451 @var{action-if-given} in the shell variable @code{withval}, which is
15452 actually just the value of the shell variable @code{with_@var{package}},
15453 with any @option{-} characters changed into @samp{_}.  You may use that
15454 variable instead, if you wish.
15456 The argument @var{help-string} is a description of the option that
15457 looks like this:
15458 @example
15459   --with-readline         support fancy command line editing
15460 @end example
15462 @noindent
15463 @var{help-string} may be more than one line long, if more detail is
15464 needed.  Just make sure the columns line up in @samp{configure
15465 --help}.  Avoid tabs in the help string.  You'll need to enclose the
15466 help string in @samp{[} and @samp{]} in order to produce the leading
15467 blanks.
15469 You should format your @var{help-string} with the macro
15470 @code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
15472 The following example shows how to use the @code{AC_ARG_WITH} macro in
15473 a common situation.  You want to let the user decide whether to enable
15474 support for an external library (e.g., the readline library); if the user
15475 specified neither @option{--with-readline} nor @option{--without-readline},
15476 you want to enable support for readline only if the library is available
15477 on the system.
15479 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
15480 @example
15481 AC_ARG_WITH([readline],
15482   [AS_HELP_STRING([--with-readline],
15483     [support fancy command line editing @@<:@@default=check@@:>@@])],
15484   [],
15485   [with_readline=check])
15487 LIBREADLINE=
15488 AS_IF([test "x$with_readline" != xno],
15489   [AC_CHECK_LIB([readline], [main],
15490     [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
15491      AC_DEFINE([HAVE_LIBREADLINE], [1],
15492                [Define if you have libreadline])
15493     ],
15494     [if test "x$with_readline" != xcheck; then
15495        AC_MSG_FAILURE(
15496          [--with-readline was given, but test for readline failed])
15497      fi
15498     ], -lncurses)])
15499 @end example
15501 The next example shows how to use @code{AC_ARG_WITH} to give the user the
15502 possibility to enable support for the readline library, in case it is still
15503 experimental and not well tested, and is therefore disabled by default.
15505 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
15506 @example
15507 AC_ARG_WITH([readline],
15508   [AS_HELP_STRING([--with-readline],
15509     [enable experimental support for readline])],
15510   [],
15511   [with_readline=no])
15513 LIBREADLINE=
15514 AS_IF([test "x$with_readline" != xno],
15515   [AC_CHECK_LIB([readline], [main],
15516     [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
15517      AC_DEFINE([HAVE_LIBREADLINE], [1],
15518                [Define if you have libreadline])
15519     ],
15520     [AC_MSG_FAILURE(
15521        [--with-readline was given, but test for readline failed])],
15522     [-lncurses])])
15523 @end example
15525 The last example shows how to use @code{AC_ARG_WITH} to give the user the
15526 possibility to disable support for the readline library, given that it is
15527 an important feature and that it should be enabled by default.
15529 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
15530 @example
15531 AC_ARG_WITH([readline],
15532   [AS_HELP_STRING([--without-readline],
15533     [disable support for readline])],
15534   [],
15535   [with_readline=yes])
15537 LIBREADLINE=
15538 AS_IF([test "x$with_readline" != xno],
15539   [AC_CHECK_LIB([readline], [main],
15540     [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
15541      AC_DEFINE([HAVE_LIBREADLINE], [1],
15542                [Define if you have libreadline])
15543     ],
15544     [AC_MSG_FAILURE(
15545        [readline test failed (--without-readline to disable)])],
15546     [-lncurses])])
15547 @end example
15549 These three examples can be easily adapted to the case where
15550 @code{AC_ARG_ENABLE} should be preferred to @code{AC_ARG_WITH} (see
15551 @ref{Package Options}).
15552 @end defmac
15554 @defmac AC_WITH (@var{package}, @var{action-if-given}, @ovar{action-if-not-given})
15555 @acindex{WITH}
15556 This is an obsolete version of @code{AC_ARG_WITH} that does not
15557 support providing a help string.
15558 @end defmac
15560 @node Package Options
15561 @section Choosing Package Options
15562 @cindex Package options
15563 @cindex Options, package
15565 If a software package has optional compile-time features, the user can
15566 give @command{configure} command line options to specify whether to
15567 compile them.  The options have one of these forms:
15569 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
15570 @c awful.
15571 @example
15572 --enable-@var{feature}[=@var{arg}]
15573 --disable-@var{feature}
15574 @end example
15576 These options allow users to choose which optional features to build and
15577 install.  @option{--enable-@var{feature}} options should never make a
15578 feature behave differently or cause one feature to replace another.
15579 They should only cause parts of the program to be built rather than left
15580 out.
15582 The user can give an argument by following the feature name with
15583 @samp{=} and the argument.  Giving an argument of @samp{no} requests
15584 that the feature @emph{not} be made available.  A feature with an
15585 argument looks like @option{--enable-debug=stabs}.  If no argument is
15586 given, it defaults to @samp{yes}.  @option{--disable-@var{feature}} is
15587 equivalent to @option{--enable-@var{feature}=no}.
15589 @command{configure} scripts do not complain about
15590 @option{--enable-@var{feature}} options that they do not support.
15591 This behavior permits configuring a source tree containing multiple
15592 packages with a top-level @command{configure} script when the packages
15593 support different options, without spurious error messages about options
15594 that some of the packages support.
15595 An unfortunate side effect is that option spelling errors are not diagnosed.
15596 No better approach to this problem has been suggested so far.
15598 For each optional feature, @file{configure.ac} should call
15599 @code{AC_ARG_ENABLE} to detect whether the @command{configure} user asked
15600 to include it.  Whether each feature is included or not by default, and
15601 which arguments are valid, is up to you.
15603 @defmac AC_ARG_ENABLE (@var{feature}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given})
15604 @acindex{ARG_ENABLE}
15605 If the user gave @command{configure} the option
15606 @option{--enable-@var{feature}} or @option{--disable-@var{feature}}, run
15607 shell commands @var{action-if-given}.  If neither option was given, run
15608 shell commands @var{action-if-not-given}.  The name @var{feature}
15609 indicates an optional user-level facility.  It should consist only of
15610 alphanumeric characters and dashes.
15612 The option's argument is available to the shell commands
15613 @var{action-if-given} in the shell variable @code{enableval}, which is
15614 actually just the value of the shell variable
15615 @code{enable_@var{feature}}, with any @option{-} characters changed into
15616 @samp{_}.  You may use that variable instead, if you wish.  The
15617 @var{help-string} argument is like that of @code{AC_ARG_WITH}
15618 (@pxref{External Software}).
15620 You should format your @var{help-string} with the macro
15621 @code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
15623 See the examples suggested with the definition of @code{AC_ARG_WITH}
15624 (@pxref{External Software}) to get an idea of possible applications of
15625 @code{AC_ARG_ENABLE}.
15626 @end defmac
15628 @defmac AC_ENABLE (@var{feature}, @var{action-if-given}, @ovar{action-if-not-given})
15629 @acindex{ENABLE}
15630 This is an obsolete version of @code{AC_ARG_ENABLE} that does not
15631 support providing a help string.
15632 @end defmac
15635 @node Pretty Help Strings
15636 @section Making Your Help Strings Look Pretty
15637 @cindex Help strings
15639 Properly formatting the @samp{help strings} which are used in
15640 @code{AC_ARG_WITH} (@pxref{External Software}) and @code{AC_ARG_ENABLE}
15641 (@pxref{Package Options}) can be challenging.  Specifically, you want
15642 your own @samp{help strings} to line up in the appropriate columns of
15643 @samp{configure --help} just like the standard Autoconf @samp{help
15644 strings} do.  This is the purpose of the @code{AS_HELP_STRING} macro.
15646 @defmac AS_HELP_STRING (@var{left-hand-side}, @var{right-hand-side})
15647 @acindex{HELP_STRING}
15649 Expands into an help string that looks pretty when the user executes
15650 @samp{configure --help}.  It is typically used in @code{AC_ARG_WITH}
15651 (@pxref{External Software}) or @code{AC_ARG_ENABLE} (@pxref{Package
15652 Options}).  The following example makes this clearer.
15654 @example
15655 AC_ARG_WITH([foo],
15656   [AS_HELP_STRING([--with-foo],
15657      [use foo (default is no)])],
15658   [use_foo=$withval],
15659   [use_foo=no])
15660 @end example
15662 The second argument of @code{AS_HELP_STRING} is
15663 not a literal, and should not be double quoted.
15664 @xref{Autoconf Language}, for a more detailed explanation.
15665 Then the last few lines of @samp{configure --help} appear like
15666 this:
15668 @example
15669 --enable and --with options recognized:
15670   --with-foo              use foo (default is no)
15671 @end example
15673 The @code{AS_HELP_STRING} macro is particularly helpful when the
15674 @var{left-hand-side} and/or @var{right-hand-side} are composed of macro
15675 arguments, as shown in the following example.
15677 @example
15678 AC_DEFUN([MY_ARG_WITH],
15679   [AC_ARG_WITH([$1],
15680      [AS_HELP_STRING([--with-$1], [use $1 (default is $2)])],
15681      [use_[]$1=$withval],
15682      [use_[]$1=$2])])
15683 @end example
15684 @end defmac
15687 @node Site Details
15688 @section Configuring Site Details
15689 @cindex Site details
15691 Some software packages require complex site-specific information.  Some
15692 examples are host names to use for certain services, company names, and
15693 email addresses to contact.  Since some configuration scripts generated
15694 by Metaconfig ask for such information interactively, people sometimes
15695 wonder how to get that information in Autoconf-generated configuration
15696 scripts, which aren't interactive.
15698 Such site configuration information should be put in a file that is
15699 edited @emph{only by users}, not by programs.  The location of the file
15700 can either be based on the @code{prefix} variable, or be a standard
15701 location such as the user's home directory.  It could even be specified
15702 by an environment variable.  The programs should examine that file at
15703 runtime, rather than at compile time.  Runtime configuration is more
15704 convenient for users and makes the configuration process simpler than
15705 getting the information while configuring.  @xref{Directory Variables, ,
15706 Variables for Installation Directories, standards, @acronym{GNU} Coding
15707 Standards}, for more information on where to put data files.
15709 @node Transforming Names
15710 @section Transforming Program Names When Installing
15711 @cindex Transforming program names
15712 @cindex Program names, transforming
15714 Autoconf supports changing the names of programs when installing them.
15715 In order to use these transformations, @file{configure.ac} must call the
15716 macro @code{AC_ARG_PROGRAM}.
15718 @defmac AC_ARG_PROGRAM
15719 @acindex{ARG_PROGRAM}
15720 @ovindex program_transform_name
15721 Place in output variable @code{program_transform_name} a sequence of
15722 @code{sed} commands for changing the names of installed programs.
15724 If any of the options described below are given to @command{configure},
15725 program names are transformed accordingly.  Otherwise, if
15726 @code{AC_CANONICAL_TARGET} has been called and a @option{--target} value
15727 is given, the target type followed by a dash is used as a prefix.
15728 Otherwise, no program name transformation is done.
15729 @end defmac
15731 @menu
15732 * Transformation Options::      @command{configure} options to transform names
15733 * Transformation Examples::     Sample uses of transforming names
15734 * Transformation Rules::        Makefile uses of transforming names
15735 @end menu
15737 @node Transformation Options
15738 @subsection Transformation Options
15740 You can specify name transformations by giving @command{configure} these
15741 command line options:
15743 @table @option
15744 @item --program-prefix=@var{prefix}
15745 prepend @var{prefix} to the names;
15747 @item --program-suffix=@var{suffix}
15748 append @var{suffix} to the names;
15750 @item --program-transform-name=@var{expression}
15751 perform @code{sed} substitution @var{expression} on the names.
15752 @end table
15754 @node Transformation Examples
15755 @subsection Transformation Examples
15757 These transformations are useful with programs that can be part of a
15758 cross-compilation development environment.  For example, a
15759 cross-assembler running on a Sun 4 configured with
15760 @option{--target=i960-vxworks} is normally installed as
15761 @file{i960-vxworks-as}, rather than @file{as}, which could be confused
15762 with a native Sun 4 assembler.
15764 You can force a program name to begin with @file{g}, if you don't want
15765 @acronym{GNU} programs installed on your system to shadow other programs with
15766 the same name.  For example, if you configure @acronym{GNU} @code{diff} with
15767 @option{--program-prefix=g}, then when you run @samp{make install} it is
15768 installed as @file{/usr/local/bin/gdiff}.
15770 As a more sophisticated example, you could use
15772 @example
15773 --program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/'
15774 @end example
15775 @noindent
15777 to prepend @samp{g} to most of the program names in a source tree,
15778 excepting those like @code{gdb} that already have one and those like
15779 @code{less} and @code{lesskey} that aren't @acronym{GNU} programs.  (That is
15780 assuming that you have a source tree containing those programs that is
15781 set up to use this feature.)
15783 One way to install multiple versions of some programs simultaneously is
15784 to append a version number to the name of one or both.  For example, if
15785 you want to keep Autoconf version 1 around for awhile, you can configure
15786 Autoconf version 2 using @option{--program-suffix=2} to install the
15787 programs as @file{/usr/local/bin/autoconf2},
15788 @file{/usr/local/bin/autoheader2}, etc.  Nevertheless, pay attention
15789 that only the binaries are renamed, therefore you'd have problems with
15790 the library files which might overlap.
15792 @node Transformation Rules
15793 @subsection Transformation Rules
15795 Here is how to use the variable @code{program_transform_name} in a
15796 @file{Makefile.in}:
15798 @example
15799 PROGRAMS = cp ls rm
15800 transform = @@program_transform_name@@
15801 install:
15802         for p in $(PROGRAMS); do \
15803           $(INSTALL_PROGRAM) $$p $(DESTDIR)$(bindir)/`echo $$p | \
15804                                               sed '$(transform)'`; \
15805         done
15807 uninstall:
15808         for p in $(PROGRAMS); do \
15809           rm -f $(DESTDIR)$(bindir)/`echo $$p | sed '$(transform)'`; \
15810         done
15811 @end example
15813 It is guaranteed that @code{program_transform_name} is never empty, and
15814 that there are no useless separators.  Therefore you may safely embed
15815 @code{program_transform_name} within a sed program using @samp{;}:
15817 @example
15818 transform = @@program_transform_name@@
15819 transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/
15820 @end example
15822 Whether to do the transformations on documentation files (Texinfo or
15823 @code{man}) is a tricky question; there seems to be no perfect answer,
15824 due to the several reasons for name transforming.  Documentation is not
15825 usually particular to a specific architecture, and Texinfo files do not
15826 conflict with system documentation.  But they might conflict with
15827 earlier versions of the same files, and @code{man} pages sometimes do
15828 conflict with system documentation.  As a compromise, it is probably
15829 best to do name transformations on @code{man} pages but not on Texinfo
15830 manuals.
15832 @node Site Defaults
15833 @section Setting Site Defaults
15834 @cindex Site defaults
15836 Autoconf-generated @command{configure} scripts allow your site to provide
15837 default values for some configuration values.  You do this by creating
15838 site- and system-wide initialization files.
15840 @evindex CONFIG_SITE
15841 If the environment variable @code{CONFIG_SITE} is set, @command{configure}
15842 uses its value as the name of a shell script to read.  Otherwise, it
15843 reads the shell script @file{@var{prefix}/share/config.site} if it exists,
15844 then @file{@var{prefix}/etc/config.site} if it exists.  Thus,
15845 settings in machine-specific files override those in machine-independent
15846 ones in case of conflict.
15848 Site files can be arbitrary shell scripts, but only certain kinds of
15849 code are really appropriate to be in them.  Because @command{configure}
15850 reads any cache file after it has read any site files, a site file can
15851 define a default cache file to be shared between all Autoconf-generated
15852 @command{configure} scripts run on that system (@pxref{Cache Files}).  If
15853 you set a default cache file in a site file, it is a good idea to also
15854 set the output variable @code{CC} in that site file, because the cache
15855 file is only valid for a particular compiler, but many systems have
15856 several available.
15858 You can examine or override the value set by a command line option to
15859 @command{configure} in a site file; options set shell variables that have
15860 the same names as the options, with any dashes turned into underscores.
15861 The exceptions are that @option{--without-} and @option{--disable-} options
15862 are like giving the corresponding @option{--with-} or @option{--enable-}
15863 option and the value @samp{no}.  Thus, @option{--cache-file=localcache}
15864 sets the variable @code{cache_file} to the value @samp{localcache};
15865 @option{--enable-warnings=no} or @option{--disable-warnings} sets the variable
15866 @code{enable_warnings} to the value @samp{no}; @option{--prefix=/usr} sets the
15867 variable @code{prefix} to the value @samp{/usr}; etc.
15869 Site files are also good places to set default values for other output
15870 variables, such as @code{CFLAGS}, if you need to give them non-default
15871 values: anything you would normally do, repetitively, on the command
15872 line.  If you use non-default values for @var{prefix} or
15873 @var{exec_prefix} (wherever you locate the site file), you can set them
15874 in the site file if you specify it with the @code{CONFIG_SITE}
15875 environment variable.
15877 You can set some cache values in the site file itself.  Doing this is
15878 useful if you are cross-compiling, where it is impossible to check features
15879 that require running a test program.  You could ``prime the cache'' by
15880 setting those values correctly for that system in
15881 @file{@var{prefix}/etc/config.site}.  To find out the names of the cache
15882 variables you need to set, look for shell variables with @samp{_cv_} in
15883 their names in the affected @command{configure} scripts, or in the Autoconf
15884 M4 source code for those macros.
15886 The cache file is careful to not override any variables set in the site
15887 files.  Similarly, you should not override command-line options in the
15888 site files.  Your code should check that variables such as @code{prefix}
15889 and @code{cache_file} have their default values (as set near the top of
15890 @command{configure}) before changing them.
15892 Here is a sample file @file{/usr/share/local/gnu/share/config.site}.  The
15893 command @samp{configure --prefix=/usr/share/local/gnu} would read this
15894 file (if @code{CONFIG_SITE} is not set to a different file).
15896 @example
15897 # config.site for configure
15899 # Change some defaults.
15900 test "$prefix" = NONE && prefix=/usr/share/local/gnu
15901 test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu
15902 test "$sharedstatedir" = '$prefix/com' && sharedstatedir=/var
15903 test "$localstatedir" = '$prefix/var' && localstatedir=/var
15905 # Give Autoconf 2.x generated configure scripts a shared default
15906 # cache file for feature test results, architecture-specific.
15907 if test "$cache_file" = /dev/null; then
15908   cache_file="$prefix/var/config.cache"
15909   # A cache file is only valid for one C compiler.
15910   CC=gcc
15912 @end example
15915 @c ============================================== Running configure Scripts.
15917 @node Running configure Scripts
15918 @chapter Running @command{configure} Scripts
15919 @cindex @command{configure}
15921 Below are instructions on how to configure a package that uses a
15922 @command{configure} script, suitable for inclusion as an @file{INSTALL}
15923 file in the package.  A plain-text version of @file{INSTALL} which you
15924 may use comes with Autoconf.
15926 @menu
15927 * Basic Installation::          Instructions for typical cases
15928 * Compilers and Options::       Selecting compilers and optimization
15929 * Multiple Architectures::      Compiling for multiple architectures at once
15930 * Installation Names::          Installing in different directories
15931 * Optional Features::           Selecting optional features
15932 * System Type::                 Specifying the system type
15933 * Sharing Defaults::            Setting site-wide defaults for @command{configure}
15934 * Defining Variables::          Specifying the compiler etc.
15935 * configure Invocation::        Changing how @command{configure} runs
15936 @end menu
15938 @set autoconf
15939 @include install.texi
15942 @c ============================================== Recreating a Configuration
15944 @node config.status Invocation
15945 @chapter Recreating a Configuration
15946 @cindex @command{config.status}
15948 The @command{configure} script creates a file named @file{config.status},
15949 which actually configures, @dfn{instantiates}, the template files.  It
15950 also records the configuration options that were specified when the
15951 package was last configured in case reconfiguring is needed.
15953 Synopsis:
15954 @example
15955 ./config.status @var{option}@dots{} [@var{file}@dots{}]
15956 @end example
15958 It configures the @var{files}; if none are specified, all the templates
15959 are instantiated.  The files must be specified without their
15960 dependencies, as in
15962 @example
15963 ./config.status foobar
15964 @end example
15966 @noindent
15969 @example
15970 ./config.status foobar:foo.in:bar.in
15971 @end example
15973 The supported options are:
15975 @table @option
15976 @item --help
15977 @itemx -h
15978 Print a summary of the command line options, the list of the template
15979 files, and exit.
15981 @item --version
15982 @itemx -V
15983 Print the version number of Autoconf and the configuration settings,
15984 and exit.
15986 @item --silent
15987 @itemx --quiet
15988 @itemx -q
15989 Do not print progress messages.
15991 @item --debug
15992 @itemx -d
15993 Don't remove the temporary files.
15995 @item --file=@var{file}[:@var{template}]
15996 Require that @var{file} be instantiated as if
15997 @samp{AC_CONFIG_FILES(@var{file}:@var{template})} was used.  Both
15998 @var{file} and @var{template} may be @samp{-} in which case the standard
15999 output and/or standard input, respectively, is used.  If a
16000 @var{template} file name is relative, it is first looked for in the build
16001 tree, and then in the source tree.  @xref{Configuration Actions}, for
16002 more details.
16004 This option and the following ones provide one way for separately
16005 distributed packages to share the values computed by @command{configure}.
16006 Doing so can be useful if some of the packages need a superset of the
16007 features that one of them, perhaps a common library, does.  These
16008 options allow a @file{config.status} file to create files other than the
16009 ones that its @file{configure.ac} specifies, so it can be used for a
16010 different package.
16012 @item --header=@var{file}[:@var{template}]
16013 Same as @option{--file} above, but with @samp{AC_CONFIG_HEADERS}.
16015 @item --recheck
16016 Ask @file{config.status} to update itself and exit (no instantiation).
16017 This option is useful if you change @command{configure}, so that the
16018 results of some tests might be different from the previous run.  The
16019 @option{--recheck} option reruns @command{configure} with the same arguments
16020 you used before, plus the @option{--no-create} option, which prevents
16021 @command{configure} from running @file{config.status} and creating
16022 @file{Makefile} and other files, and the @option{--no-recursion} option,
16023 which prevents @command{configure} from running other @command{configure}
16024 scripts in subdirectories.  (This is so other Make rules can
16025 run @file{config.status} when it changes; @pxref{Automatic Remaking},
16026 for an example).
16027 @end table
16029 @file{config.status} checks several optional environment variables that
16030 can alter its behavior:
16032 @defvar CONFIG_SHELL
16033 @evindex CONFIG_SHELL
16034 The shell with which to run @command{configure} for the @option{--recheck}
16035 option.  It must be Bourne-compatible.  The default is a shell that
16036 supports @code{LINENO} if available, and @file{/bin/sh} otherwise.
16037 Invoking @command{configure} by hand bypasses this setting, so you may
16038 need to use a command like @samp{CONFIG_SHELL=/bin/bash /bin/bash ./configure}
16039 to insure that the same shell is used everywhere.  The absolute name of the
16040 shell should be passed.
16041 @end defvar
16043 @defvar CONFIG_STATUS
16044 @evindex CONFIG_STATUS
16045 The file name to use for the shell script that records the
16046 configuration.  The default is @file{./config.status}.  This variable is
16047 useful when one package uses parts of another and the @command{configure}
16048 scripts shouldn't be merged because they are maintained separately.
16049 @end defvar
16051 You can use @file{./config.status} in your makefiles.  For example, in
16052 the dependencies given above (@pxref{Automatic Remaking}),
16053 @file{config.status} is run twice when @file{configure.ac} has changed.
16054 If that bothers you, you can make each run only regenerate the files for
16055 that rule:
16056 @example
16057 @group
16058 config.h: stamp-h
16059 stamp-h: config.h.in config.status
16060         ./config.status config.h
16061         echo > stamp-h
16063 Makefile: Makefile.in config.status
16064         ./config.status Makefile
16065 @end group
16066 @end example
16068 The calling convention of @file{config.status} has changed; see
16069 @ref{Obsolete config.status Use}, for details.
16072 @c =================================================== Obsolete Constructs
16074 @node Obsolete Constructs
16075 @chapter Obsolete Constructs
16076 @cindex Obsolete constructs
16078 Autoconf changes, and throughout the years some constructs have been
16079 obsoleted.  Most of the changes involve the macros, but in some cases
16080 the tools themselves, or even some concepts, are now considered
16081 obsolete.
16083 You may completely skip this chapter if you are new to Autoconf.  Its
16084 intention is mainly to help maintainers updating their packages by
16085 understanding how to move to more modern constructs.
16087 @menu
16088 * Obsolete config.status Use::  Different calling convention
16089 * acconfig.h::                  Additional entries in @file{config.h.in}
16090 * autoupdate Invocation::       Automatic update of @file{configure.ac}
16091 * Obsolete Macros::             Backward compatibility macros
16092 * Autoconf 1::                  Tips for upgrading your files
16093 * Autoconf 2.13::               Some fresher tips
16094 @end menu
16096 @node Obsolete config.status Use
16097 @section Obsolete @file{config.status} Invocation
16099 @file{config.status} now supports arguments to specify the files to
16100 instantiate; see @ref{config.status Invocation}, for more details.
16101 Before, environment variables had to be used.
16103 @defvar CONFIG_COMMANDS
16104 @evindex CONFIG_COMMANDS
16105 The tags of the commands to execute.  The default is the arguments given
16106 to @code{AC_OUTPUT} and @code{AC_CONFIG_COMMANDS} in
16107 @file{configure.ac}.
16108 @end defvar
16110 @defvar CONFIG_FILES
16111 @evindex CONFIG_FILES
16112 The files in which to perform @samp{@@@var{variable}@@} substitutions.
16113 The default is the arguments given to @code{AC_OUTPUT} and
16114 @code{AC_CONFIG_FILES} in @file{configure.ac}.
16115 @end defvar
16117 @defvar CONFIG_HEADERS
16118 @evindex CONFIG_HEADERS
16119 The files in which to substitute C @code{#define} statements.  The
16120 default is the arguments given to @code{AC_CONFIG_HEADERS}; if that
16121 macro was not called, @file{config.status} ignores this variable.
16122 @end defvar
16124 @defvar CONFIG_LINKS
16125 @evindex CONFIG_LINKS
16126 The symbolic links to establish.  The default is the arguments given to
16127 @code{AC_CONFIG_LINKS}; if that macro was not called,
16128 @file{config.status} ignores this variable.
16129 @end defvar
16131 In @ref{config.status Invocation}, using this old interface, the example
16132 would be:
16134 @example
16135 @group
16136 config.h: stamp-h
16137 stamp-h: config.h.in config.status
16138         CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_FILES= \
16139           CONFIG_HEADERS=config.h ./config.status
16140         echo > stamp-h
16142 Makefile: Makefile.in config.status
16143         CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_HEADERS= \
16144           CONFIG_FILES=Makefile ./config.status
16145 @end group
16146 @end example
16148 @noindent
16149 (If @file{configure.ac} does not call @code{AC_CONFIG_HEADERS}, there is
16150 no need to set @code{CONFIG_HEADERS} in the @code{make} rules.  Equally
16151 for @code{CONFIG_COMMANDS}, etc.)
16154 @node acconfig.h
16155 @section @file{acconfig.h}
16157 @cindex @file{acconfig.h}
16158 @cindex @file{config.h.top}
16159 @cindex @file{config.h.bot}
16161 In order to produce @file{config.h.in}, @command{autoheader} needs to
16162 build or to find templates for each symbol.  Modern releases of Autoconf
16163 use @code{AH_VERBATIM} and @code{AH_TEMPLATE} (@pxref{Autoheader
16164 Macros}), but in older releases a file, @file{acconfig.h}, contained the
16165 list of needed templates.  @command{autoheader} copied comments and
16166 @code{#define} and @code{#undef} statements from @file{acconfig.h} in
16167 the current directory, if present.  This file used to be mandatory if
16168 you @code{AC_DEFINE} any additional symbols.
16170 Modern releases of Autoconf also provide @code{AH_TOP} and
16171 @code{AH_BOTTOM} if you need to prepend/append some information to
16172 @file{config.h.in}.  Ancient versions of Autoconf had a similar feature:
16173 if @file{./acconfig.h} contains the string @samp{@@TOP@@},
16174 @command{autoheader} copies the lines before the line containing
16175 @samp{@@TOP@@} into the top of the file that it generates.  Similarly,
16176 if @file{./acconfig.h} contains the string @samp{@@BOTTOM@@},
16177 @command{autoheader} copies the lines after that line to the end of the
16178 file it generates.  Either or both of those strings may be omitted.  An
16179 even older alternate way to produce the same effect in ancient versions
16180 of Autoconf is to create the files @file{@var{file}.top} (typically
16181 @file{config.h.top}) and/or @file{@var{file}.bot} in the current
16182 directory.  If they exist, @command{autoheader} copies them to the
16183 beginning and end, respectively, of its output.
16185 In former versions of Autoconf, the files used in preparing a software
16186 package for distribution were:
16187 @example
16188 @group
16189 configure.ac --.   .------> autoconf* -----> configure
16190                +---+
16191 [aclocal.m4] --+   `---.
16192 [acsite.m4] ---'       |
16193                        +--> [autoheader*] -> [config.h.in]
16194 [acconfig.h] ----.     |
16195                  +-----'
16196 [config.h.top] --+
16197 [config.h.bot] --'
16198 @end group
16199 @end example
16201 Using only the @code{AH_} macros, @file{configure.ac} should be
16202 self-contained, and should not depend upon @file{acconfig.h} etc.
16205 @node autoupdate Invocation
16206 @section Using @command{autoupdate} to Modernize @file{configure.ac}
16207 @cindex @command{autoupdate}
16209 The @command{autoupdate} program updates a @file{configure.ac} file that
16210 calls Autoconf macros by their old names to use the current macro names.
16211 In version 2 of Autoconf, most of the macros were renamed to use a more
16212 uniform and descriptive naming scheme.  @xref{Macro Names}, for a
16213 description of the new scheme.  Although the old names still work
16214 (@pxref{Obsolete Macros}, for a list of the old macros and the corresponding
16215 new names), you can make your @file{configure.ac} files more readable
16216 and make it easier to use the current Autoconf documentation if you
16217 update them to use the new macro names.
16219 @evindex SIMPLE_BACKUP_SUFFIX
16220 If given no arguments, @command{autoupdate} updates @file{configure.ac},
16221 backing up the original version with the suffix @file{~} (or the value
16222 of the environment variable @code{SIMPLE_BACKUP_SUFFIX}, if that is
16223 set).  If you give @command{autoupdate} an argument, it reads that file
16224 instead of @file{configure.ac} and writes the updated file to the
16225 standard output.
16227 @noindent
16228 @command{autoupdate} accepts the following options:
16230 @table @option
16231 @item --help
16232 @itemx -h
16233 Print a summary of the command line options and exit.
16235 @item --version
16236 @itemx -V
16237 Print the version number of Autoconf and exit.
16239 @item --verbose
16240 @itemx -v
16241 Report processing steps.
16243 @item --debug
16244 @itemx -d
16245 Don't remove the temporary files.
16247 @item --force
16248 @itemx -f
16249 Force the update even if the file has not changed.  Disregard the cache.
16251 @item --include=@var{dir}
16252 @itemx -I @var{dir}
16253 Also look for input files in @var{dir}.  Multiple invocations accumulate.
16254 Directories are browsed from last to first.
16255 @end table
16257 @node Obsolete Macros
16258 @section Obsolete Macros
16260 Several macros are obsoleted in Autoconf, for various reasons (typically
16261 they failed to quote properly, couldn't be extended for more recent
16262 issues, etc.).  They are still supported, but deprecated: their use
16263 should be avoided.
16265 During the jump from Autoconf version 1 to version 2, most of the
16266 macros were renamed to use a more uniform and descriptive naming scheme,
16267 but their signature did not change.  @xref{Macro Names}, for a
16268 description of the new naming scheme.  Below, if there is just the mapping
16269 from old names to new names for these macros, the reader is invited to
16270 refer to the definition of the new macro for the signature and the
16271 description.
16273 @defmac AC_ALLOCA
16274 @acindex{ALLOCA}
16275 @code{AC_FUNC_ALLOCA}
16276 @end defmac
16278 @defmac AC_ARG_ARRAY
16279 @acindex{ARG_ARRAY}
16280 removed because of limited usefulness
16281 @end defmac
16283 @defmac AC_C_CROSS
16284 @acindex{C_CROSS}
16285 This macro is obsolete; it does nothing.
16286 @end defmac
16288 @defmac AC_C_LONG_DOUBLE
16289 @acindex{C_LONG_DOUBLE}
16290 @cvindex HAVE_LONG_DOUBLE
16291 If the C compiler supports a working @code{long double} type with more
16292 range or precision than the @code{double} type, define
16293 @code{HAVE_LONG_DOUBLE}.
16295 You should use @code{AC_TYPE_LONG_DOUBLE} or
16296 @code{AC_TYPE_LONG_DOUBLE_WIDER} instead.  @xref{Particular Types}.
16297 @end defmac
16299 @defmac AC_CANONICAL_SYSTEM
16300 @acindex{CANONICAL_SYSTEM}
16301 Determine the system type and set output variables to the names of the
16302 canonical system types.  @xref{Canonicalizing}, for details about the
16303 variables this macro sets.
16305 The user is encouraged to use either @code{AC_CANONICAL_BUILD}, or
16306 @code{AC_CANONICAL_HOST}, or @code{AC_CANONICAL_TARGET}, depending on
16307 the needs.  Using @code{AC_CANONICAL_TARGET} is enough to run the two
16308 other macros.
16309 @end defmac
16311 @defmac AC_CHAR_UNSIGNED
16312 @acindex{CHAR_UNSIGNED}
16313 @code{AC_C_CHAR_UNSIGNED}
16314 @end defmac
16316 @defmac AC_CHECK_TYPE (@var{type}, @var{default})
16317 @acindex{CHECK_TYPE}
16318 Autoconf, up to 2.13, used to provide this version of
16319 @code{AC_CHECK_TYPE}, deprecated because of its flaws.  First, although
16320 it is a member of the @code{CHECK} clan, it does
16321 more than just checking.  Secondly, missing types are defined
16322 using @code{#define}, not @code{typedef}, and this can lead to
16323 problems in the case of pointer types.
16325 This use of @code{AC_CHECK_TYPE} is obsolete and discouraged; see
16326 @ref{Generic Types}, for the description of the current macro.
16328 If the type @var{type} is not defined, define it to be the C (or C++)
16329 builtin type @var{default}, e.g., @samp{short int} or @samp{unsigned int}.
16331 This macro is equivalent to:
16333 @example
16334 AC_CHECK_TYPE([@var{type}], [],
16335   [AC_DEFINE_UNQUOTED([@var{type}], [@var{default}],
16336      [Define to `@var{default}'
16337       if <sys/types.h> does not define.])])
16338 @end example
16340 In order to keep backward compatibility, the two versions of
16341 @code{AC_CHECK_TYPE} are implemented, selected by a simple heuristics:
16343 @enumerate
16344 @item
16345 If there are three or four arguments, the modern version is used.
16347 @item
16348 If the second argument appears to be a C or C++ type, then the
16349 obsolete version is used.  This happens if the argument is a C or C++
16350 @emph{builtin} type or a C identifier ending in @samp{_t}, optionally
16351 followed by one of @samp{[(* } and then by a string of zero or more
16352 characters taken from the set @samp{[]()* _a-zA-Z0-9}.
16354 @item
16355 If the second argument is spelled with the alphabet of valid C and C++
16356 types, the user is warned and the modern version is used.
16358 @item
16359 Otherwise, the modern version is used.
16360 @end enumerate
16362 @noindent
16363 You are encouraged either to use a valid builtin type, or to use the
16364 equivalent modern code (see above), or better yet, to use
16365 @code{AC_CHECK_TYPES} together with
16367 @example
16368 #ifndef HAVE_LOFF_T
16369 typedef loff_t off_t;
16370 #endif
16371 @end example
16372 @end defmac
16373 @c end of AC_CHECK_TYPE
16375 @defmac AC_CHECKING (@var{feature-description})
16376 @acindex{CHECKING}
16377 Same as @samp{AC_MSG_NOTICE([checking @var{feature-description}@dots{}]}.
16378 @end defmac
16380 @defmac AC_COMPILE_CHECK (@var{echo-text}, @var{includes}, @var{function-body}, @var{action-if-true}, @ovar{action-if-false})
16381 @acindex{COMPILE_CHECK}
16382 This is an obsolete version of @code{AC_TRY_COMPILE} itself replaced by
16383 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}), with the
16384 addition that it prints @samp{checking for @var{echo-text}} to the
16385 standard output first, if @var{echo-text} is non-empty.  Use
16386 @code{AC_MSG_CHECKING} and @code{AC_MSG_RESULT} instead to print
16387 messages (@pxref{Printing Messages}).
16388 @end defmac
16390 @defmac AC_CONST
16391 @acindex{CONST}
16392 @code{AC_C_CONST}
16393 @end defmac
16395 @defmac AC_CROSS_CHECK
16396 @acindex{CROSS_CHECK}
16397 Same as @code{AC_C_CROSS}, which is obsolete too, and does nothing
16398 @code{:-)}.
16399 @end defmac
16401 @defmac AC_CYGWIN
16402 @acindex{CYGWIN}
16403 Check for the Cygwin environment in which case the shell variable
16404 @code{CYGWIN} is set to @samp{yes}.  Don't use this macro, the dignified
16405 means to check the nature of the host is using
16406 @code{AC_CANONICAL_HOST}.  As a matter of fact this macro is defined as:
16408 @example
16409 AC_REQUIRE([AC_CANONICAL_HOST])[]dnl
16410 case $host_os in
16411   *cygwin* ) CYGWIN=yes;;
16412          * ) CYGWIN=no;;
16413 esac
16414 @end example
16416 Beware that the variable @code{CYGWIN} has a special meaning when
16417 running Cygwin, and should not be changed.  That's yet another reason
16418 not to use this macro.
16419 @end defmac
16421 @defmac AC_DECL_SYS_SIGLIST
16422 @acindex{DECL_SYS_SIGLIST}
16423 @cvindex SYS_SIGLIST_DECLARED
16424 Same as:
16426 @example
16427 AC_CHECK_DECLS([sys_siglist], [], [],
16428 [#include <signal.h>
16429 /* NetBSD declares sys_siglist in unistd.h.  */
16430 #ifdef HAVE_UNISTD_H
16431 # include <unistd.h>
16432 #endif
16434 @end example
16435 @end defmac
16437 @defmac AC_DECL_YYTEXT
16438 @acindex{DECL_YYTEXT}
16439 Does nothing, now integrated in @code{AC_PROG_LEX}.
16440 @end defmac
16442 @defmac AC_DIR_HEADER
16443 @acindex{DIR_HEADER}
16444 @cvindex DIRENT
16445 @cvindex SYSNDIR
16446 @cvindex SYSDIR
16447 @cvindex NDIR
16448 Like calling @code{AC_FUNC_CLOSEDIR_VOID} and@code{AC_HEADER_DIRENT},
16449 but defines a different set of C preprocessor macros to indicate which
16450 header file is found:
16452 @multitable {@file{sys/ndir.h}} {Old Symbol} {@code{HAVE_SYS_NDIR_H}}
16453 @item Header            @tab Old Symbol     @tab New Symbol
16454 @item @file{dirent.h}   @tab @code{DIRENT}  @tab @code{HAVE_DIRENT_H}
16455 @item @file{sys/ndir.h} @tab @code{SYSNDIR} @tab @code{HAVE_SYS_NDIR_H}
16456 @item @file{sys/dir.h}  @tab @code{SYSDIR}  @tab @code{HAVE_SYS_DIR_H}
16457 @item @file{ndir.h}     @tab @code{NDIR}    @tab @code{HAVE_NDIR_H}
16458 @end multitable
16459 @end defmac
16461 @defmac AC_DYNIX_SEQ
16462 @acindex{DYNIX_SEQ}
16463 If on DYNIX/ptx, add @option{-lseq} to output variable
16464 @code{LIBS}.  This macro used to be defined as
16466 @example
16467 AC_CHECK_LIB([seq], [getmntent], [LIBS="-lseq $LIBS"])
16468 @end example
16470 @noindent
16471 now it is just @code{AC_FUNC_GETMNTENT}.
16472 @end defmac
16474 @defmac AC_EXEEXT
16475 @acindex{EXEEXT}
16476 @ovindex EXEEXT
16477 Defined the output variable @code{EXEEXT} based on the output of the
16478 compiler, which is now done automatically.  Typically set to empty
16479 string if Posix and @samp{.exe} if a @acronym{DOS} variant.
16480 @end defmac
16482 @defmac AC_EMXOS2
16483 @acindex{EMXOS2}
16484 Similar to @code{AC_CYGWIN} but checks for the EMX environment on OS/2
16485 and sets @code{EMXOS2}.
16486 @end defmac
16488 @defmac AC_ERROR
16489 @acindex{ERROR}
16490 @code{AC_MSG_ERROR}
16491 @end defmac
16493 @defmac AC_FIND_X
16494 @acindex{FIND_X}
16495 @code{AC_PATH_X}
16496 @end defmac
16498 @defmac AC_FIND_XTRA
16499 @acindex{FIND_XTRA}
16500 @code{AC_PATH_XTRA}
16501 @end defmac
16503 @defmac AC_FOREACH
16504 @acindex{FOREACH}
16505 @code{m4_foreach_w}
16506 @end defmac
16508 @defmac AC_FUNC_CHECK
16509 @acindex{FUNC_CHECK}
16510 @code{AC_CHECK_FUNC}
16511 @end defmac
16513 @defmac AC_FUNC_WAIT3
16514 @acindex{FUNC_WAIT3}
16515 @cvindex HAVE_WAIT3
16516 If @code{wait3} is found and fills in the contents of its third argument
16517 (a @samp{struct rusage *}), which @acronym{HP-UX} does not do, define
16518 @code{HAVE_WAIT3}.
16520 These days portable programs should use @code{waitpid}, not
16521 @code{wait3}, as @code{wait3} has been removed from Posix.
16522 @end defmac
16524 @defmac AC_GCC_TRADITIONAL
16525 @acindex{GCC_TRADITIONAL}
16526 @code{AC_PROG_GCC_TRADITIONAL}
16527 @end defmac
16529 @defmac AC_GETGROUPS_T
16530 @acindex{GETGROUPS_T}
16531 @code{AC_TYPE_GETGROUPS}
16532 @end defmac
16534 @defmac AC_GETLOADAVG
16535 @acindex{GETLOADAVG}
16536 @code{AC_FUNC_GETLOADAVG}
16537 @end defmac
16539 @defmac AC_HAVE_FUNCS
16540 @acindex{HAVE_FUNCS}
16541 @code{AC_CHECK_FUNCS}
16542 @end defmac
16544 @defmac AC_HAVE_HEADERS
16545 @acindex{HAVE_HEADERS}
16546 @code{AC_CHECK_HEADERS}
16547 @end defmac
16549 @defmac AC_HAVE_LIBRARY (@var{library}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
16550 @acindex{HAVE_LIBRARY}
16551 This macro is equivalent to calling @code{AC_CHECK_LIB} with a
16552 @var{function} argument of @code{main}.  In addition, @var{library} can
16553 be written as any of @samp{foo}, @option{-lfoo}, or @samp{libfoo.a}.  In
16554 all of those cases, the compiler is passed @option{-lfoo}.  However,
16555 @var{library} cannot be a shell variable; it must be a literal name.
16556 @end defmac
16558 @defmac AC_HAVE_POUNDBANG
16559 @acindex{HAVE_POUNDBANG}
16560 @code{AC_SYS_INTERPRETER} (different calling convention)
16561 @end defmac
16563 @defmac AC_HEADER_CHECK
16564 @acindex{HEADER_CHECK}
16565 @code{AC_CHECK_HEADER}
16566 @end defmac
16568 @defmac AC_HEADER_EGREP
16569 @acindex{HEADER_EGREP}
16570 @code{AC_EGREP_HEADER}
16571 @end defmac
16573 @defmac AC_HELP_STRING
16574 @acindex{HELP_STRING}
16575 @code{AS_HELP_STRING}
16576 @end defmac
16578 @defmac AC_INIT (@var{unique-file-in-source-dir})
16579 @acindex{INIT}
16580 Formerly @code{AC_INIT} used to have a single argument, and was
16581 equivalent to:
16583 @example
16584 AC_INIT
16585 AC_CONFIG_SRCDIR(@var{unique-file-in-source-dir})
16586 @end example
16587 @end defmac
16589 @defmac AC_INLINE
16590 @acindex{INLINE}
16591 @code{AC_C_INLINE}
16592 @end defmac
16594 @defmac AC_INT_16_BITS
16595 @acindex{INT_16_BITS}
16596 @cvindex INT_16_BITS
16597 If the C type @code{int} is 16 bits wide, define @code{INT_16_BITS}.
16598 Use @samp{AC_CHECK_SIZEOF(int)} instead.
16599 @end defmac
16601 @defmac AC_IRIX_SUN
16602 @acindex{IRIX_SUN}
16603 If on @sc{irix} (Silicon Graphics Unix), add @option{-lsun} to output
16604 @code{LIBS}.  If you were using it to get @code{getmntent}, use
16605 @code{AC_FUNC_GETMNTENT} instead.  If you used it for the NIS versions
16606 of the password and group functions, use @samp{AC_CHECK_LIB(sun,
16607 getpwnam)}.  Up to Autoconf 2.13, it used to be
16609 @example
16610 AC_CHECK_LIB([sun], [getmntent], [LIBS="-lsun $LIBS"])
16611 @end example
16613 @noindent
16614 now it is defined as
16616 @example
16617 AC_FUNC_GETMNTENT
16618 AC_CHECK_LIB([sun], [getpwnam])
16619 @end example
16620 @end defmac
16622 @defmac AC_LANG_C
16623 @acindex{LANG_C}
16624 Same as @samp{AC_LANG([C])}.
16625 @end defmac
16627 @defmac AC_LANG_CPLUSPLUS
16628 @acindex{LANG_CPLUSPLUS}
16629 Same as @samp{AC_LANG([C++])}.
16630 @end defmac
16632 @defmac AC_LANG_FORTRAN77
16633 @acindex{LANG_FORTRAN77}
16634 Same as @samp{AC_LANG([Fortran 77])}.
16635 @end defmac
16637 @defmac AC_LANG_RESTORE
16638 @acindex{LANG_RESTORE}
16639 Select the @var{language} that is saved on the top of the stack, as set
16640 by @code{AC_LANG_SAVE}, remove it from the stack, and call
16641 @code{AC_LANG(@var{language})}.
16642 @end defmac
16644 @defmac AC_LANG_SAVE
16645 @acindex{LANG_SAVE}
16646 Remember the current language (as set by @code{AC_LANG}) on a stack.
16647 The current language does not change.  @code{AC_LANG_PUSH} is preferred.
16648 @end defmac
16650 @defmac AC_LINK_FILES (@var{source}@dots{}, @var{dest}@dots{})
16651 @acindex{LINK_FILES}
16652 This is an obsolete version of @code{AC_CONFIG_LINKS}.  An updated
16653 version of:
16655 @example
16656 AC_LINK_FILES(config/$machine.h config/$obj_format.h,
16657               host.h            object.h)
16658 @end example
16660 @noindent
16663 @example
16664 AC_CONFIG_LINKS([host.h:config/$machine.h
16665                 object.h:config/$obj_format.h])
16666 @end example
16667 @end defmac
16669 @defmac AC_LN_S
16670 @acindex{LN_S}
16671 @code{AC_PROG_LN_S}
16672 @end defmac
16674 @defmac AC_LONG_64_BITS
16675 @acindex{LONG_64_BITS}
16676 @cvindex LONG_64_BITS
16677 Define @code{LONG_64_BITS} if the C type @code{long int} is 64 bits wide.
16678 Use the generic macro @samp{AC_CHECK_SIZEOF([long int])} instead.
16679 @end defmac
16681 @defmac AC_LONG_DOUBLE
16682 @acindex{LONG_DOUBLE}
16683 If the C compiler supports a working @code{long double} type with more
16684 range or precision than the @code{double} type, define
16685 @code{HAVE_LONG_DOUBLE}.
16687 You should use @code{AC_TYPE_LONG_DOUBLE} or
16688 @code{AC_TYPE_LONG_DOUBLE_WIDER} instead.  @xref{Particular Types}.
16689 @end defmac
16691 @defmac AC_LONG_FILE_NAMES
16692 @acindex{LONG_FILE_NAMES}
16693 @code{AC_SYS_LONG_FILE_NAMES}
16694 @end defmac
16696 @defmac AC_MAJOR_HEADER
16697 @acindex{MAJOR_HEADER}
16698 @code{AC_HEADER_MAJOR}
16699 @end defmac
16701 @defmac AC_MEMORY_H
16702 @acindex{MEMORY_H}
16703 @cvindex NEED_MEMORY_H
16704 Used to define @code{NEED_MEMORY_H} if the @code{mem} functions were
16705 defined in @file{memory.h}.  Today it is equivalent to
16706 @samp{AC_CHECK_HEADERS([memory.h])}.  Adjust your code to depend upon
16707 @code{HAVE_MEMORY_H}, not @code{NEED_MEMORY_H}; see @ref{Standard
16708 Symbols}.
16709 @end defmac
16711 @defmac AC_MINGW32
16712 @acindex{MINGW32}
16713 Similar to @code{AC_CYGWIN} but checks for the MinGW compiler
16714 environment and sets @code{MINGW32}.
16715 @end defmac
16717 @defmac AC_MINUS_C_MINUS_O
16718 @acindex{MINUS_C_MINUS_O}
16719 @code{AC_PROG_CC_C_O}
16720 @end defmac
16722 @defmac AC_MMAP
16723 @acindex{MMAP}
16724 @code{AC_FUNC_MMAP}
16725 @end defmac
16727 @defmac AC_MODE_T
16728 @acindex{MODE_T}
16729 @code{AC_TYPE_MODE_T}
16730 @end defmac
16732 @defmac AC_OBJEXT
16733 @acindex{OBJEXT}
16734 @ovindex OBJEXT
16735 Defined the output variable @code{OBJEXT} based on the output of the
16736 compiler, after .c files have been excluded.  Typically set to @samp{o}
16737 if Posix, @samp{obj} if a @acronym{DOS} variant.
16738 Now the compiler checking macros handle
16739 this automatically.
16740 @end defmac
16742 @defmac AC_OBSOLETE (@var{this-macro-name}, @ovar{suggestion})
16743 @acindex{OBSOLETE}
16744 Make M4 print a message to the standard error output warning that
16745 @var{this-macro-name} is obsolete, and giving the file and line number
16746 where it was called.  @var{this-macro-name} should be the name of the
16747 macro that is calling @code{AC_OBSOLETE}.  If @var{suggestion} is given,
16748 it is printed at the end of the warning message; for example, it can be
16749 a suggestion for what to use instead of @var{this-macro-name}.
16751 For instance
16753 @example
16754 AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl
16755 @end example
16757 You are encouraged to use @code{AU_DEFUN} instead, since it gives better
16758 services to the user.
16759 @end defmac
16761 @defmac AC_OFF_T
16762 @acindex{OFF_T}
16763 @code{AC_TYPE_OFF_T}
16764 @end defmac
16766 @defmac AC_OUTPUT (@ovar{file}@dots{}, @ovar{extra-cmds}, @ovar{init-cmds})
16767 @acindex{OUTPUT}
16768 The use of @code{AC_OUTPUT} with argument is deprecated.  This obsoleted
16769 interface is equivalent to:
16771 @example
16772 @group
16773 AC_CONFIG_FILES(@var{file}@dots{})
16774 AC_CONFIG_COMMANDS([default],
16775                    @var{extra-cmds}, @var{init-cmds})
16776 AC_OUTPUT
16777 @end group
16778 @end example
16779 @end defmac
16781 @defmac AC_OUTPUT_COMMANDS (@var{extra-cmds}, @ovar{init-cmds})
16782 @acindex{OUTPUT_COMMANDS}
16783 Specify additional shell commands to run at the end of
16784 @file{config.status}, and shell commands to initialize any variables
16785 from @command{configure}.  This macro may be called multiple times.  It is
16786 obsolete, replaced by @code{AC_CONFIG_COMMANDS}.
16788 Here is an unrealistic example:
16790 @example
16791 fubar=27
16792 AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.],
16793                    [fubar=$fubar])
16794 AC_OUTPUT_COMMANDS([echo this is another, extra, bit],
16795                    [echo init bit])
16796 @end example
16798 Aside from the fact that @code{AC_CONFIG_COMMANDS} requires an
16799 additional key, an important difference is that
16800 @code{AC_OUTPUT_COMMANDS} is quoting its arguments twice, unlike
16801 @code{AC_CONFIG_COMMANDS}.  This means that @code{AC_CONFIG_COMMANDS}
16802 can safely be given macro calls as arguments:
16804 @example
16805 AC_CONFIG_COMMANDS(foo, [my_FOO()])
16806 @end example
16808 @noindent
16809 Conversely, where one level of quoting was enough for literal strings
16810 with @code{AC_OUTPUT_COMMANDS}, you need two with
16811 @code{AC_CONFIG_COMMANDS}.  The following lines are equivalent:
16813 @example
16814 @group
16815 AC_OUTPUT_COMMANDS([echo "Square brackets: []"])
16816 AC_CONFIG_COMMANDS([default], [[echo "Square brackets: []"]])
16817 @end group
16818 @end example
16819 @end defmac
16821 @defmac AC_PID_T
16822 @acindex{PID_T}
16823 @code{AC_TYPE_PID_T}
16824 @end defmac
16826 @defmac AC_PREFIX
16827 @acindex{PREFIX}
16828 @code{AC_PREFIX_PROGRAM}
16829 @end defmac
16831 @defmac AC_PROGRAMS_CHECK
16832 @acindex{PROGRAMS_CHECK}
16833 @code{AC_CHECK_PROGS}
16834 @end defmac
16836 @defmac AC_PROGRAMS_PATH
16837 @acindex{PROGRAMS_PATH}
16838 @code{AC_PATH_PROGS}
16839 @end defmac
16841 @defmac AC_PROGRAM_CHECK
16842 @acindex{PROGRAM_CHECK}
16843 @code{AC_CHECK_PROG}
16844 @end defmac
16846 @defmac AC_PROGRAM_EGREP
16847 @acindex{PROGRAM_EGREP}
16848 @code{AC_EGREP_CPP}
16849 @end defmac
16851 @defmac AC_PROGRAM_PATH
16852 @acindex{PROGRAM_PATH}
16853 @code{AC_PATH_PROG}
16854 @end defmac
16856 @defmac AC_REMOTE_TAPE
16857 @acindex{REMOTE_TAPE}
16858 removed because of limited usefulness
16859 @end defmac
16861 @defmac AC_RESTARTABLE_SYSCALLS
16862 @acindex{RESTARTABLE_SYSCALLS}
16863 @code{AC_SYS_RESTARTABLE_SYSCALLS}
16864 @end defmac
16866 @defmac AC_RETSIGTYPE
16867 @acindex{RETSIGTYPE}
16868 @code{AC_TYPE_SIGNAL}
16869 @end defmac
16871 @defmac AC_RSH
16872 @acindex{RSH}
16873 removed because of limited usefulness
16874 @end defmac
16876 @defmac AC_SCO_INTL
16877 @acindex{SCO_INTL}
16878 @ovindex LIBS
16879 If on SCO Unix, add @option{-lintl} to output variable @code{LIBS}.  This
16880 macro used to do this:
16882 @example
16883 AC_CHECK_LIB([intl], [strftime], [LIBS="-lintl $LIBS"])
16884 @end example
16886 @noindent
16887 Now it just calls @code{AC_FUNC_STRFTIME} instead.
16888 @end defmac
16890 @defmac AC_SETVBUF_REVERSED
16891 @acindex{SETVBUF_REVERSED}
16892 @code{AC_FUNC_SETVBUF_REVERSED}
16893 @end defmac
16895 @defmac AC_SET_MAKE
16896 @acindex{SET_MAKE}
16897 @code{AC_PROG_MAKE_SET}
16898 @end defmac
16900 @defmac AC_SIZEOF_TYPE
16901 @acindex{SIZEOF_TYPE}
16902 @code{AC_CHECK_SIZEOF}
16903 @end defmac
16905 @defmac AC_SIZE_T
16906 @acindex{SIZE_T}
16907 @code{AC_TYPE_SIZE_T}
16908 @end defmac
16910 @defmac AC_STAT_MACROS_BROKEN
16911 @acindex{STAT_MACROS_BROKEN}
16912 @code{AC_HEADER_STAT}
16913 @end defmac
16915 @defmac AC_STDC_HEADERS
16916 @acindex{STDC_HEADERS}
16917 @code{AC_HEADER_STDC}
16918 @end defmac
16920 @defmac AC_STRCOLL
16921 @acindex{STRCOLL}
16922 @code{AC_FUNC_STRCOLL}
16923 @end defmac
16925 @defmac AC_ST_BLKSIZE
16926 @acindex{ST_BLKSIZE}
16927 @code{AC_CHECK_MEMBERS}
16928 @end defmac
16930 @defmac AC_ST_BLOCKS
16931 @acindex{ST_BLOCKS}
16932 @code{AC_STRUCT_ST_BLOCKS}
16933 @end defmac
16935 @defmac AC_ST_RDEV
16936 @acindex{ST_RDEV}
16937 @code{AC_CHECK_MEMBERS}
16938 @end defmac
16940 @defmac AC_SYS_RESTARTABLE_SYSCALLS
16941 @acindex{SYS_RESTARTABLE_SYSCALLS}
16942 @cvindex HAVE_RESTARTABLE_SYSCALLS
16943 If the system automatically restarts a system call that is interrupted
16944 by a signal, define @code{HAVE_RESTARTABLE_SYSCALLS}.  This macro does
16945 not check whether system calls are restarted in general---it checks whether a
16946 signal handler installed with @code{signal} (but not @code{sigaction})
16947 causes system calls to be restarted.  It does not check whether system calls
16948 can be restarted when interrupted by signals that have no handler.
16950 These days portable programs should use @code{sigaction} with
16951 @code{SA_RESTART} if they want restartable system calls.  They should
16952 not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a
16953 system call is restartable is a dynamic issue, not a configuration-time
16954 issue.
16955 @end defmac
16957 @defmac AC_SYS_SIGLIST_DECLARED
16958 @acindex{SYS_SIGLIST_DECLARED}
16959 @code{AC_DECL_SYS_SIGLIST}
16960 @end defmac
16962 @defmac AC_TEST_CPP
16963 @acindex{TEST_CPP}
16964 @code{AC_TRY_CPP}, replaced by @code{AC_PREPROC_IFELSE}.
16965 @end defmac
16967 @defmac AC_TEST_PROGRAM
16968 @acindex{TEST_PROGRAM}
16969 @code{AC_TRY_RUN}, replaced by @code{AC_RUN_IFELSE}.
16970 @end defmac
16972 @defmac AC_TIMEZONE
16973 @acindex{TIMEZONE}
16974 @code{AC_STRUCT_TIMEZONE}
16975 @end defmac
16977 @defmac AC_TIME_WITH_SYS_TIME
16978 @acindex{TIME_WITH_SYS_TIME}
16979 @code{AC_HEADER_TIME}
16980 @end defmac
16982 @defmac AC_TRY_COMPILE (@var{includes}, @var{function-body}, @ovar{action-if-true}, @ovar{action-if-false})
16983 @acindex{TRY_COMPILE}
16984 Same as:
16986 @example
16987 AC_COMPILE_IFELSE(
16988   [AC_LANG_PROGRAM([[@var{includes}]],
16989      [[@var{function-body}]])],
16990   [@var{action-if-true}],
16991   [@var{action-if-false}])
16992 @end example
16994 @noindent
16995 @xref{Running the Compiler}.
16997 This macro double quotes both @var{includes} and @var{function-body}.
16999 For C and C++, @var{includes} is any @code{#include} statements needed
17000 by the code in @var{function-body} (@var{includes} is ignored if
17001 the currently selected language is Fortran or Fortran 77).  The compiler
17002 and compilation flags are determined by the current language
17003 (@pxref{Language Choice}).
17004 @end defmac
17006 @defmac AC_TRY_CPP (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
17007 @acindex{TRY_CPP}
17008 Same as:
17010 @example
17011 AC_PREPROC_IFELSE(
17012   [AC_LANG_SOURCE([[@var{input}]])],
17013   [@var{action-if-true}],
17014   [@var{action-if-false}])
17015 @end example
17017 @noindent
17018 @xref{Running the Preprocessor}.
17020 This macro double quotes the @var{input}.
17021 @end defmac
17023 @defmac AC_TRY_LINK (@var{includes}, @var{function-body}, @ovar{action-if-true}, @ovar{action-if-false})
17024 @acindex{TRY_LINK}
17025 Same as:
17027 @example
17028 AC_LINK_IFELSE(
17029   [AC_LANG_PROGRAM([[@var{includes}]],
17030      [[@var{function-body}]])],
17031   [@var{action-if-true}],
17032   [@var{action-if-false}])
17033 @end example
17035 @noindent
17036 @xref{Running the Compiler}.
17038 This macro double quotes both @var{includes} and @var{function-body}.
17040 Depending on the current language (@pxref{Language Choice}), create a
17041 test program to see whether a function whose body consists of
17042 @var{function-body} can be compiled and linked.  If the file compiles
17043 and links successfully, run shell commands @var{action-if-found},
17044 otherwise run @var{action-if-not-found}.
17046 This macro double quotes both @var{includes} and @var{function-body}.
17048 For C and C++, @var{includes} is any @code{#include} statements needed
17049 by the code in @var{function-body} (@var{includes} is ignored if
17050 the currently selected language is Fortran or Fortran 77).  The compiler
17051 and compilation flags are determined by the current language
17052 (@pxref{Language Choice}), and in addition @code{LDFLAGS} and
17053 @code{LIBS} are used for linking.
17054 @end defmac
17056 @defmac AC_TRY_LINK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found})
17057 @acindex{TRY_LINK_FUNC}
17058 This macro is equivalent to
17059 @samp{AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])],
17060 [@var{action-if-found}], [@var{action-if-not-found}])}.
17061 @end defmac
17063 @defmac AC_TRY_RUN (@var{program}, @ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-cross-compiling})
17064 @acindex{TRY_RUN}
17065 Same as:
17067 @example
17068 AC_RUN_IFELSE(
17069   [AC_LANG_SOURCE([[@var{program}]])],
17070   [@var{action-if-true}],
17071   [@var{action-if-false}],
17072   [@var{action-if-cross-compiling}])
17073 @end example
17075 @noindent
17076 @xref{Runtime}.
17077 @end defmac
17079 @defmac AC_UID_T
17080 @acindex{UID_T}
17081 @code{AC_TYPE_UID_T}
17082 @end defmac
17084 @defmac AC_UNISTD_H
17085 @acindex{UNISTD_H}
17086 Same as @samp{AC_CHECK_HEADERS([unistd.h])}.
17087 @end defmac
17089 @defmac AC_USG
17090 @acindex{USG}
17091 @cvindex USG
17092 Define @code{USG} if the @acronym{BSD} string functions are defined in
17093 @file{strings.h}.  You should no longer depend upon @code{USG}, but on
17094 @code{HAVE_STRING_H}; see @ref{Standard Symbols}.
17095 @end defmac
17097 @defmac AC_UTIME_NULL
17098 @acindex{UTIME_NULL}
17099 @code{AC_FUNC_UTIME_NULL}
17100 @end defmac
17102 @defmac AC_VALIDATE_CACHED_SYSTEM_TUPLE (@ovar{cmd})
17103 @acindex{VALIDATE_CACHED_SYSTEM_TUPLE}
17104 If the cache file is inconsistent with the current host, target and
17105 build system types, it used to execute @var{cmd} or print a default
17106 error message.  This is now handled by default.
17107 @end defmac
17109 @defmac AC_VERBOSE (@var{result-description})
17110 @acindex{VERBOSE}
17111 @code{AC_MSG_RESULT}.
17112 @end defmac
17114 @defmac AC_VFORK
17115 @acindex{VFORK}
17116 @code{AC_FUNC_VFORK}
17117 @end defmac
17119 @defmac AC_VPRINTF
17120 @acindex{VPRINTF}
17121 @code{AC_FUNC_VPRINTF}
17122 @end defmac
17124 @defmac AC_WAIT3
17125 @acindex{WAIT3}
17126 @code{AC_FUNC_WAIT3}
17127 @end defmac
17129 @defmac AC_WARN
17130 @acindex{WARN}
17131 @code{AC_MSG_WARN}
17132 @end defmac
17134 @defmac AC_WORDS_BIGENDIAN
17135 @acindex{WORDS_BIGENDIAN}
17136 @code{AC_C_BIGENDIAN}
17137 @end defmac
17139 @defmac AC_XENIX_DIR
17140 @acindex{XENIX_DIR}
17141 @ovindex LIBS
17142 This macro used to add @option{-lx} to output variable @code{LIBS} if on
17143 Xenix.  Also, if @file{dirent.h} is being checked for, added
17144 @option{-ldir} to @code{LIBS}.  Now it is merely an alias of
17145 @code{AC_HEADER_DIRENT} instead, plus some code to detect whether
17146 running @sc{xenix} on which you should not depend:
17148 @example
17149 AC_MSG_CHECKING([for Xenix])
17150 AC_EGREP_CPP([yes],
17151 [#if defined M_XENIX && !defined M_UNIX
17152   yes
17153 #endif],
17154              [AC_MSG_RESULT([yes]); XENIX=yes],
17155              [AC_MSG_RESULT([no]); XENIX=])
17156 @end example
17157 @end defmac
17159 @defmac AC_YYTEXT_POINTER
17160 @acindex{YYTEXT_POINTER}
17161 @code{AC_DECL_YYTEXT}
17162 @end defmac
17164 @node Autoconf 1
17165 @section Upgrading From Version 1
17166 @cindex Upgrading autoconf
17167 @cindex Autoconf upgrading
17169 Autoconf version 2 is mostly backward compatible with version 1.
17170 However, it introduces better ways to do some things, and doesn't
17171 support some of the ugly things in version 1.  So, depending on how
17172 sophisticated your @file{configure.ac} files are, you might have to do
17173 some manual work in order to upgrade to version 2.  This chapter points
17174 out some problems to watch for when upgrading.  Also, perhaps your
17175 @command{configure} scripts could benefit from some of the new features in
17176 version 2; the changes are summarized in the file @file{NEWS} in the
17177 Autoconf distribution.
17179 @menu
17180 * Changed File Names::          Files you might rename
17181 * Changed Makefiles::           New things to put in @file{Makefile.in}
17182 * Changed Macros::              Macro calls you might replace
17183 * Changed Results::             Changes in how to check test results
17184 * Changed Macro Writing::       Better ways to write your own macros
17185 @end menu
17187 @node Changed File Names
17188 @subsection Changed File Names
17190 If you have an @file{aclocal.m4} installed with Autoconf (as opposed to
17191 in a particular package's source directory), you must rename it to
17192 @file{acsite.m4}.  @xref{autoconf Invocation}.
17194 If you distribute @file{install.sh} with your package, rename it to
17195 @file{install-sh} so @code{make} builtin rules don't inadvertently
17196 create a file called @file{install} from it.  @code{AC_PROG_INSTALL}
17197 looks for the script under both names, but it is best to use the new name.
17199 If you were using @file{config.h.top}, @file{config.h.bot}, or
17200 @file{acconfig.h}, you still can, but you have less clutter if you
17201 use the @code{AH_} macros.  @xref{Autoheader Macros}.
17203 @node Changed Makefiles
17204 @subsection Changed Makefiles
17206 Add @samp{@@CFLAGS@@}, @samp{@@CPPFLAGS@@}, and @samp{@@LDFLAGS@@} in
17207 your @file{Makefile.in} files, so they can take advantage of the values
17208 of those variables in the environment when @command{configure} is run.
17209 Doing this isn't necessary, but it's a convenience for users.
17211 Also add @samp{@@configure_input@@} in a comment to each input file for
17212 @code{AC_OUTPUT}, so that the output files contain a comment saying
17213 they were produced by @command{configure}.  Automatically selecting the
17214 right comment syntax for all the kinds of files that people call
17215 @code{AC_OUTPUT} on became too much work.
17217 Add @file{config.log} and @file{config.cache} to the list of files you
17218 remove in @code{distclean} targets.
17220 If you have the following in @file{Makefile.in}:
17222 @example
17223 prefix = /usr/local
17224 exec_prefix = $(prefix)
17225 @end example
17227 @noindent
17228 you must change it to:
17230 @example
17231 prefix = @@prefix@@
17232 exec_prefix = @@exec_prefix@@
17233 @end example
17235 @noindent
17236 The old behavior of replacing those variables without @samp{@@}
17237 characters around them has been removed.
17239 @node Changed Macros
17240 @subsection Changed Macros
17242 Many of the macros were renamed in Autoconf version 2.  You can still
17243 use the old names, but the new ones are clearer, and it's easier to find
17244 the documentation for them.  @xref{Obsolete Macros}, for a table showing the
17245 new names for the old macros.  Use the @command{autoupdate} program to
17246 convert your @file{configure.ac} to using the new macro names.
17247 @xref{autoupdate Invocation}.
17249 Some macros have been superseded by similar ones that do the job better,
17250 but are not call-compatible.  If you get warnings about calling obsolete
17251 macros while running @command{autoconf}, you may safely ignore them, but
17252 your @command{configure} script generally works better if you follow
17253 the advice that is printed about what to replace the obsolete macros with.  In
17254 particular, the mechanism for reporting the results of tests has
17255 changed.  If you were using @command{echo} or @code{AC_VERBOSE} (perhaps
17256 via @code{AC_COMPILE_CHECK}), your @command{configure} script's output
17257 looks better if you switch to @code{AC_MSG_CHECKING} and
17258 @code{AC_MSG_RESULT}.  @xref{Printing Messages}.  Those macros work best
17259 in conjunction with cache variables.  @xref{Caching Results}.
17263 @node Changed Results
17264 @subsection Changed Results
17266 If you were checking the results of previous tests by examining the
17267 shell variable @code{DEFS}, you need to switch to checking the values of
17268 the cache variables for those tests.  @code{DEFS} no longer exists while
17269 @command{configure} is running; it is only created when generating output
17270 files.  This difference from version 1 is because properly quoting the
17271 contents of that variable turned out to be too cumbersome and
17272 inefficient to do every time @code{AC_DEFINE} is called.  @xref{Cache
17273 Variable Names}.
17275 For example, here is a @file{configure.ac} fragment written for Autoconf
17276 version 1:
17278 @example
17279 AC_HAVE_FUNCS(syslog)
17280 case "$DEFS" in
17281 *-DHAVE_SYSLOG*) ;;
17282 *) # syslog is not in the default libraries.  See if it's in some other.
17283   saved_LIBS="$LIBS"
17284   for lib in bsd socket inet; do
17285     AC_CHECKING(for syslog in -l$lib)
17286     LIBS="-l$lib $saved_LIBS"
17287     AC_HAVE_FUNCS(syslog)
17288     case "$DEFS" in
17289     *-DHAVE_SYSLOG*) break ;;
17290     *) ;;
17291     esac
17292     LIBS="$saved_LIBS"
17293   done ;;
17294 esac
17295 @end example
17297 Here is a way to write it for version 2:
17299 @example
17300 AC_CHECK_FUNCS([syslog])
17301 if test $ac_cv_func_syslog = no; then
17302   # syslog is not in the default libraries.  See if it's in some other.
17303   for lib in bsd socket inet; do
17304     AC_CHECK_LIB([$lib], [syslog], [AC_DEFINE([HAVE_SYSLOG])
17305       LIBS="-l$lib $LIBS"; break])
17306   done
17308 @end example
17310 If you were working around bugs in @code{AC_DEFINE_UNQUOTED} by adding
17311 backslashes before quotes, you need to remove them.  It now works
17312 predictably, and does not treat quotes (except back quotes) specially.
17313 @xref{Setting Output Variables}.
17315 All of the Boolean shell variables set by Autoconf macros now use
17316 @samp{yes} for the true value.  Most of them use @samp{no} for false,
17317 though for backward compatibility some use the empty string instead.  If
17318 you were relying on a shell variable being set to something like 1 or
17319 @samp{t} for true, you need to change your tests.
17321 @node Changed Macro Writing
17322 @subsection Changed Macro Writing
17324 When defining your own macros, you should now use @code{AC_DEFUN}
17325 instead of @code{define}.  @code{AC_DEFUN} automatically calls
17326 @code{AC_PROVIDE} and ensures that macros called via @code{AC_REQUIRE}
17327 do not interrupt other macros, to prevent nested @samp{checking@dots{}}
17328 messages on the screen.  There's no actual harm in continuing to use the
17329 older way, but it's less convenient and attractive.  @xref{Macro
17330 Definitions}.
17332 You probably looked at the macros that came with Autoconf as a guide for
17333 how to do things.  It would be a good idea to take a look at the new
17334 versions of them, as the style is somewhat improved and they take
17335 advantage of some new features.
17337 If you were doing tricky things with undocumented Autoconf internals
17338 (macros, variables, diversions), check whether you need to change
17339 anything to account for changes that have been made.  Perhaps you can
17340 even use an officially supported technique in version 2 instead of
17341 kludging.  Or perhaps not.
17343 To speed up your locally written feature tests, add caching to them.
17344 See whether any of your tests are of general enough usefulness to
17345 encapsulate them into macros that you can share.
17348 @node Autoconf 2.13
17349 @section Upgrading From Version 2.13
17350 @cindex Upgrading autoconf
17351 @cindex Autoconf upgrading
17353 The introduction of the previous section (@pxref{Autoconf 1}) perfectly
17354 suits this section@enddots{}
17356 @quotation
17357 Autoconf version 2.50 is mostly backward compatible with version 2.13.
17358 However, it introduces better ways to do some things, and doesn't
17359 support some of the ugly things in version 2.13.  So, depending on how
17360 sophisticated your @file{configure.ac} files are, you might have to do
17361 some manual work in order to upgrade to version 2.50.  This chapter
17362 points out some problems to watch for when upgrading.  Also, perhaps
17363 your @command{configure} scripts could benefit from some of the new
17364 features in version 2.50; the changes are summarized in the file
17365 @file{NEWS} in the Autoconf distribution.
17366 @end quotation
17368 @menu
17369 * Changed Quotation::           Broken code which used to work
17370 * New Macros::                  Interaction with foreign macros
17371 * Hosts and Cross-Compilation::  Bugward compatibility kludges
17372 * AC_LIBOBJ vs LIBOBJS::        LIBOBJS is a forbidden token
17373 * AC_FOO_IFELSE vs AC_TRY_FOO::  A more generic scheme for testing sources
17374 @end menu
17376 @node Changed Quotation
17377 @subsection Changed Quotation
17379 The most important changes are invisible to you: the implementation of
17380 most macros have completely changed.  This allowed more factorization of
17381 the code, better error messages, a higher uniformity of the user's
17382 interface etc.  Unfortunately, as a side effect, some construct which
17383 used to (miraculously) work might break starting with Autoconf 2.50.
17384 The most common culprit is bad quotation.
17386 For instance, in the following example, the message is not properly
17387 quoted:
17389 @example
17390 AC_INIT
17391 AC_CHECK_HEADERS(foo.h, ,
17392   AC_MSG_ERROR(cannot find foo.h, bailing out))
17393 AC_OUTPUT
17394 @end example
17396 @noindent
17397 Autoconf 2.13 simply ignores it:
17399 @example
17400 $ @kbd{autoconf-2.13; ./configure --silent}
17401 creating cache ./config.cache
17402 configure: error: cannot find foo.h
17404 @end example
17406 @noindent
17407 while Autoconf 2.50 produces a broken @file{configure}:
17409 @example
17410 $ @kbd{autoconf-2.50; ./configure --silent}
17411 configure: error: cannot find foo.h
17412 ./configure: exit: bad non-numeric arg `bailing'
17413 ./configure: exit: bad non-numeric arg `bailing'
17415 @end example
17417 The message needs to be quoted, and the @code{AC_MSG_ERROR} invocation
17418 too!
17420 @example
17421 AC_INIT([Example], [1.0], [bug-example@@example.org])
17422 AC_CHECK_HEADERS([foo.h], [],
17423   [AC_MSG_ERROR([cannot find foo.h, bailing out])])
17424 AC_OUTPUT
17425 @end example
17427 Many many (and many more) Autoconf macros were lacking proper quotation,
17428 including no less than@dots{} @code{AC_DEFUN} itself!
17430 @example
17431 $ @kbd{cat configure.in}
17432 AC_DEFUN([AC_PROG_INSTALL],
17433 [# My own much better version
17435 AC_INIT
17436 AC_PROG_INSTALL
17437 AC_OUTPUT
17438 $ @kbd{autoconf-2.13}
17439 autoconf: Undefined macros:
17440 ***BUG in Autoconf--please report*** AC_FD_MSG
17441 ***BUG in Autoconf--please report*** AC_EPI
17442 configure.in:1:AC_DEFUN([AC_PROG_INSTALL],
17443 configure.in:5:AC_PROG_INSTALL
17444 $ @kbd{autoconf-2.50}
17446 @end example
17449 @node New Macros
17450 @subsection New Macros
17452 @cindex undefined macro
17453 @cindex @code{_m4_divert_diversion}
17455 While Autoconf was relatively dormant in the late 1990s, Automake
17456 provided Autoconf-like macros for a while.  Starting with Autoconf 2.50
17457 in 2001, Autoconf provided
17458 versions of these macros, integrated in the @code{AC_} namespace,
17459 instead of @code{AM_}.  But in order to ease the upgrading via
17460 @command{autoupdate}, bindings to such @code{AM_} macros are provided.
17462 Unfortunately older versions of Automake (e.g., Automake 1.4)
17463 did not quote the names of these macros.
17464 Therefore, when @command{m4} finds something like
17465 @samp{AC_DEFUN(AM_TYPE_PTRDIFF_T, @dots{})} in @file{aclocal.m4},
17466 @code{AM_TYPE_PTRDIFF_T} is
17467 expanded, replaced with its Autoconf definition.
17469 Fortunately Autoconf catches pre-@code{AC_INIT} expansions, and
17470 complains, in its own words:
17472 @example
17473 $ @kbd{cat configure.ac}
17474 AC_INIT([Example], [1.0], [bug-example@@example.org])
17475 AM_TYPE_PTRDIFF_T
17476 $ @kbd{aclocal-1.4}
17477 $ @kbd{autoconf}
17478 aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion
17479 aclocal.m4:17: the top level
17480 autom4te: m4 failed with exit status: 1
17482 @end example
17484 Modern versions of Automake no longer define most of these
17485 macros, and properly quote the names of the remaining macros.
17486 If you must use an old Automake, do not depend upon macros from Automake
17487 as it is simply not its job
17488 to provide macros (but the one it requires itself):
17490 @example
17491 $ @kbd{cat configure.ac}
17492 AC_INIT([Example], [1.0], [bug-example@@example.org])
17493 AM_TYPE_PTRDIFF_T
17494 $ @kbd{rm aclocal.m4}
17495 $ @kbd{autoupdate}
17496 autoupdate: `configure.ac' is updated
17497 $ @kbd{cat configure.ac}
17498 AC_INIT([Example], [1.0], [bug-example@@example.org])
17499 AC_CHECK_TYPES([ptrdiff_t])
17500 $ @kbd{aclocal-1.4}
17501 $ @kbd{autoconf}
17503 @end example
17506 @node Hosts and Cross-Compilation
17507 @subsection Hosts and Cross-Compilation
17508 @cindex Cross compilation
17510 Based on the experience of compiler writers, and after long public
17511 debates, many aspects of the cross-compilation chain have changed:
17513 @itemize @minus
17514 @item
17515 the relationship between the build, host, and target architecture types,
17517 @item
17518 the command line interface for specifying them to @command{configure},
17520 @item
17521 the variables defined in @command{configure},
17523 @item
17524 the enabling of cross-compilation mode.
17525 @end itemize
17527 @sp 1
17529 The relationship between build, host, and target have been cleaned up:
17530 the chain of default is now simply: target defaults to host, host to
17531 build, and build to the result of @command{config.guess}.  Nevertheless,
17532 in order to ease the transition from 2.13 to 2.50, the following
17533 transition scheme is implemented.  @emph{Do not rely on it}, as it will
17534 be completely disabled in a couple of releases (we cannot keep it, as it
17535 proves to cause more problems than it cures).
17537 They all default to the result of running @command{config.guess}, unless
17538 you specify either @option{--build} or @option{--host}.  In this case,
17539 the default becomes the system type you specified.  If you specify both,
17540 and they're different, @command{configure} enters cross compilation
17541 mode, so it doesn't run any tests that require execution.
17543 Hint: if you mean to override the result of @command{config.guess},
17544 prefer @option{--build} over @option{--host}.  In the future,
17545 @option{--host} will not override the name of the build system type.
17546 Whenever you specify @option{--host}, be sure to specify @option{--build}
17547 too.
17549 @sp 1
17551 For backward compatibility, @command{configure} accepts a system
17552 type as an option by itself.  Such an option overrides the
17553 defaults for build, host, and target system types.  The following
17554 configure statement configures a cross toolchain that runs on
17555 Net@acronym{BSD}/alpha but generates code for @acronym{GNU} Hurd/sparc,
17556 which is also the build platform.
17558 @example
17559 ./configure --host=alpha-netbsd sparc-gnu
17560 @end example
17562 @sp 1
17564 In Autoconf 2.13 and before, the variables @code{build}, @code{host},
17565 and @code{target} had a different semantics before and after the
17566 invocation of @code{AC_CANONICAL_BUILD} etc.  Now, the argument of
17567 @option{--build} is strictly copied into @code{build_alias}, and is left
17568 empty otherwise.  After the @code{AC_CANONICAL_BUILD}, @code{build} is
17569 set to the canonicalized build type.  To ease the transition, before,
17570 its contents is the same as that of @code{build_alias}.  Do @emph{not}
17571 rely on this broken feature.
17573 For consistency with the backward compatibility scheme exposed above,
17574 when @option{--host} is specified but @option{--build} isn't, the build
17575 system is assumed to be the same as @option{--host}, and
17576 @samp{build_alias} is set to that value.  Eventually, this
17577 historically incorrect behavior will go away.
17579 @sp 1
17581 The former scheme to enable cross-compilation proved to cause more harm
17582 than good, in particular, it used to be triggered too easily, leaving
17583 regular end users puzzled in front of cryptic error messages.
17584 @command{configure} could even enter cross-compilation mode only
17585 because the compiler was not functional.  This is mainly because
17586 @command{configure} used to try to detect cross-compilation, instead of
17587 waiting for an explicit flag from the user.
17589 Now, @command{configure} enters cross-compilation mode if and only if
17590 @option{--host} is passed.
17592 That's the short documentation.  To ease the transition between 2.13 and
17593 its successors, a more complicated scheme is implemented.  @emph{Do not
17594 rely on the following}, as it will be removed in the near future.
17596 If you specify @option{--host}, but not @option{--build}, when
17597 @command{configure} performs the first compiler test it tries to run
17598 an executable produced by the compiler.  If the execution fails, it
17599 enters cross-compilation mode.  This is fragile.  Moreover, by the time
17600 the compiler test is performed, it may be too late to modify the
17601 build-system type: other tests may have already been performed.
17602 Therefore, whenever you specify @option{--host}, be sure to specify
17603 @option{--build} too.
17605 @example
17606 ./configure --build=i686-pc-linux-gnu --host=m68k-coff
17607 @end example
17609 @noindent
17610 enters cross-compilation mode.  The former interface, which
17611 consisted in setting the compiler to a cross-compiler without informing
17612 @command{configure} is obsolete.  For instance, @command{configure}
17613 fails if it can't run the code generated by the specified compiler if you
17614 configure as follows:
17616 @example
17617 ./configure CC=m68k-coff-gcc
17618 @end example
17621 @node AC_LIBOBJ vs LIBOBJS
17622 @subsection @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}
17624 Up to Autoconf 2.13, the replacement of functions was triggered via the
17625 variable @code{LIBOBJS}.  Since Autoconf 2.50, the macro
17626 @code{AC_LIBOBJ} should be used instead (@pxref{Generic Functions}).
17627 Starting at Autoconf 2.53, the use of @code{LIBOBJS} is an error.
17629 This change is mandated by the unification of the @acronym{GNU} Build System
17630 components.  In particular, the various fragile techniques used to parse
17631 a @file{configure.ac} are all replaced with the use of traces.  As a
17632 consequence, any action must be traceable, which obsoletes critical
17633 variable assignments.  Fortunately, @code{LIBOBJS} was the only problem,
17634 and it can even be handled gracefully (read, ``without your having to
17635 change something'').
17637 There were two typical uses of @code{LIBOBJS}: asking for a replacement
17638 function, and adjusting @code{LIBOBJS} for Automake and/or Libtool.
17640 @sp 1
17642 As for function replacement, the fix is immediate: use
17643 @code{AC_LIBOBJ}.  For instance:
17645 @example
17646 LIBOBJS="$LIBOBJS fnmatch.o"
17647 LIBOBJS="$LIBOBJS malloc.$ac_objext"
17648 @end example
17650 @noindent
17651 should be replaced with:
17653 @example
17654 AC_LIBOBJ([fnmatch])
17655 AC_LIBOBJ([malloc])
17656 @end example
17658 @sp 1
17660 @ovindex LIBOBJDIR
17661 When used with Automake 1.10 or newer, a suitable value for
17662 @code{LIBOBJDIR} is set so that the @code{LIBOBJS} and @code{LTLIBOBJS}
17663 can be referenced from any @file{Makefile.am}.  Even without Automake,
17664 arranging for @code{LIBOBJDIR} to be set correctly enables
17665 referencing @code{LIBOBJS} and @code{LTLIBOBJS} in another directory.
17666 The @code{LIBOJBDIR} feature is experimental.
17669 @node AC_FOO_IFELSE vs AC_TRY_FOO
17670 @subsection @code{AC_FOO_IFELSE} vs.@: @code{AC_TRY_FOO}
17672 Since Autoconf 2.50, internal codes uses @code{AC_PREPROC_IFELSE},
17673 @code{AC_COMPILE_IFELSE}, @code{AC_LINK_IFELSE}, and
17674 @code{AC_RUN_IFELSE} on one hand and @code{AC_LANG_SOURCES},
17675 and @code{AC_LANG_PROGRAM} on the other hand instead of the deprecated
17676 @code{AC_TRY_CPP}, @code{AC_TRY_COMPILE}, @code{AC_TRY_LINK}, and
17677 @code{AC_TRY_RUN}.  The motivations where:
17678 @itemize @minus
17679 @item
17680 a more consistent interface: @code{AC_TRY_COMPILE} etc.@: were double
17681 quoting their arguments;
17683 @item
17684 the combinatoric explosion is solved by decomposing on the one hand the
17685 generation of sources, and on the other hand executing the program;
17687 @item
17688 this scheme helps supporting more languages than plain C and C++.
17689 @end itemize
17691 In addition to the change of syntax, the philosophy has changed too:
17692 while emphasis was put on speed at the expense of accuracy, today's
17693 Autoconf promotes accuracy of the testing framework at, ahem@dots{}, the
17694 expense of speed.
17697 As a perfect example of what is @emph{not} to be done, here is how to
17698 find out whether a header file contains a particular declaration, such
17699 as a typedef, a structure, a structure member, or a function.  Use
17700 @code{AC_EGREP_HEADER} instead of running @code{grep} directly on the
17701 header file; on some systems the symbol might be defined in another
17702 header file that the file you are checking includes.
17704 As a (bad) example, here is how you should not check for C preprocessor
17705 symbols, either defined by header files or predefined by the C
17706 preprocessor: using @code{AC_EGREP_CPP}:
17708 @example
17709 @group
17710 AC_EGREP_CPP(yes,
17711 [#ifdef _AIX
17712   yes
17713 #endif
17714 ], is_aix=yes, is_aix=no)
17715 @end group
17716 @end example
17718 The above example, properly written would (i) use
17719 @code{AC_LANG_PROGRAM}, and (ii) run the compiler:
17721 @example
17722 @group
17723 AC_COMPILE_IFELSE([AC_LANG_PROGRAM(
17724 [[#ifndef _AIX
17725  error: This isn't AIX!
17726 #endif
17727 ]])],
17728                    [is_aix=yes],
17729                    [is_aix=no])
17730 @end group
17731 @end example
17734 @c ============================= Generating Test Suites with Autotest
17736 @node Using Autotest
17737 @chapter Generating Test Suites with Autotest
17739 @cindex Autotest
17741 @display
17742 @strong{N.B.: This section describes an experimental feature which will
17743 be part of Autoconf in a forthcoming release.  Although we believe
17744 Autotest is stabilizing, this documentation describes an interface which
17745 might change in the future: do not depend upon Autotest without
17746 subscribing to the Autoconf mailing lists.}
17747 @end display
17749 It is paradoxical that portable projects depend on nonportable tools
17750 to run their test suite.  Autoconf by itself is the paragon of this
17751 problem: although it aims at perfectly portability, up to 2.13 its
17752 test suite was using Deja@acronym{GNU}, a rich and complex testing
17753 framework, but which is far from being standard on Posix systems.
17754 Worse yet, it was likely to be missing on the most fragile platforms,
17755 the very platforms that are most likely to torture Autoconf and
17756 exhibit deficiencies.
17758 To circumvent this problem, many package maintainers have developed their
17759 own testing framework, based on simple shell scripts whose sole outputs
17760 are exit status values describing whether the test succeeded.  Most of
17761 these tests share common patterns, and this can result in lots of
17762 duplicated code and tedious maintenance.
17764 Following exactly the same reasoning that yielded to the inception of
17765 Autoconf, Autotest provides a test suite generation framework, based on
17766 M4 macros building a portable shell script.  The suite itself is
17767 equipped with automatic logging and tracing facilities which greatly
17768 diminish the interaction with bug reporters, and simple timing reports.
17770 Autoconf itself has been using Autotest for years, and we do attest that
17771 it has considerably improved the strength of the test suite and the
17772 quality of bug reports.  Other projects are known to use some generation
17773 of Autotest, such as Bison, Free Recode, Free Wdiff, @acronym{GNU} Tar, each of
17774 them with different needs, and this usage has validated Autotest as a general
17775 testing framework.
17777 Nonetheless, compared to Deja@acronym{GNU}, Autotest is inadequate for
17778 interactive tool testing, which is probably its main limitation.
17780 @menu
17781 * Using an Autotest Test Suite::  Autotest and the user
17782 * Writing testsuite.at::        Autotest macros
17783 * testsuite Invocation::        Running @command{testsuite} scripts
17784 * Making testsuite Scripts::    Using autom4te to create @command{testsuite}
17785 @end menu
17787 @node Using an Autotest Test Suite
17788 @section Using an Autotest Test Suite
17790 @menu
17791 * testsuite Scripts::           The concepts of Autotest
17792 * Autotest Logs::               Their contents
17793 @end menu
17795 @node testsuite Scripts
17796 @subsection @command{testsuite} Scripts
17798 @cindex @command{testsuite}
17800 Generating testing or validation suites using Autotest is rather easy.
17801 The whole validation suite is held in a file to be processed through
17802 @command{autom4te}, itself using @acronym{GNU} M4 under the scene, to
17803 produce a stand-alone Bourne shell script which then gets distributed.
17804 Neither @command{autom4te} nor @acronym{GNU} M4 are needed at
17805 the installer's end.
17807 @cindex test group
17808 Each test of the validation suite should be part of some test group.  A
17809 @dfn{test group} is a sequence of interwoven tests that ought to be
17810 executed together, usually because one test in the group creates data
17811 files than a later test in the same group needs to read.  Complex test
17812 groups make later debugging more tedious.  It is much better to
17813 keep only a few tests per test group.  Ideally there is only one test
17814 per test group.
17816 For all but the simplest packages, some file such as @file{testsuite.at}
17817 does not fully hold all test sources, as these are often easier to
17818 maintain in separate files.  Each of these separate files holds a single
17819 test group, or a sequence of test groups all addressing some common
17820 functionality in the package.  In such cases, @file{testsuite.at}
17821 merely initializes the validation suite, and sometimes does elementary
17822 health checking, before listing include statements for all other test
17823 files.  The special file @file{package.m4}, containing the
17824 identification of the package, is automatically included if found.
17826 A convenient alternative consists in moving all the global issues
17827 (local Autotest macros, elementary health checking, and @code{AT_INIT}
17828 invocation) into the file @code{local.at}, and making
17829 @file{testsuite.at} be a simple list of @code{m4_include} of sub test
17830 suites.  In such case, generating the whole test suite or pieces of it
17831 is only a matter of choosing the @command{autom4te} command line
17832 arguments.
17834 The validation scripts that Autotest produces are by convention called
17835 @command{testsuite}.  When run, @command{testsuite} executes each test
17836 group in turn, producing only one summary line per test to say if that
17837 particular test succeeded or failed.  At end of all tests, summarizing
17838 counters get printed.  One debugging directory is left for each test
17839 group which failed, if any: such directories are named
17840 @file{testsuite.dir/@var{nn}}, where @var{nn} is the sequence number of
17841 the test group, and they include:
17843 @itemize @bullet
17844 @item a debugging script named @file{run} which reruns the test in
17845 @dfn{debug mode} (@pxref{testsuite Invocation}).  The automatic generation
17846 of debugging scripts has the purpose of easing the chase for bugs.
17848 @item all the files created with @code{AT_DATA}
17850 @item a log of the run, named @file{testsuite.log}
17851 @end itemize
17853 In the ideal situation, none of the tests fail, and consequently no
17854 debugging directory is left behind for validation.
17856 It often happens in practice that individual tests in the validation
17857 suite need to get information coming out of the configuration process.
17858 Some of this information, common for all validation suites, is provided
17859 through the file @file{atconfig}, automatically created by
17860 @code{AC_CONFIG_TESTDIR}.  For configuration informations which your
17861 testing environment specifically needs, you might prepare an optional
17862 file named @file{atlocal.in}, instantiated by @code{AC_CONFIG_FILES}.
17863 The configuration process produces @file{atconfig} and @file{atlocal}
17864 out of these two input files, and these two produced files are
17865 automatically read by the @file{testsuite} script.
17867 Here is a diagram showing the relationship between files.
17869 @noindent
17870 Files used in preparing a software package for distribution:
17872 @example
17873                 [package.m4] -->.
17874                                  \
17875 subfile-1.at ->.  [local.at] ---->+
17876     ...         \                  \
17877 subfile-i.at ---->-- testsuite.at -->-- autom4te* -->testsuite
17878     ...         /
17879 subfile-n.at ->'
17880 @end example
17882 @noindent
17883 Files used in configuring a software package:
17885 @example
17886                                      .--> atconfig
17887                                     /
17888 [atlocal.in] -->  config.status* --<
17889                                     \
17890                                      `--> [atlocal]
17891 @end example
17893 @noindent
17894 Files created during the test suite execution:
17896 @example
17897 atconfig -->.                    .--> testsuite.log
17898              \                  /
17899               >-- testsuite* --<
17900              /                  \
17901 [atlocal] ->'                    `--> [testsuite.dir]
17902 @end example
17905 @node Autotest Logs
17906 @subsection Autotest Logs
17908 When run, the test suite creates a log file named after itself, e.g., a
17909 test suite named @command{testsuite} creates @file{testsuite.log}.  It
17910 contains a lot of information, usually more than maintainers actually
17911 need, but therefore most of the time it contains all that is needed:
17913 @table @asis
17914 @item command line arguments
17915 @c akim s/to consist in/to consist of/
17916 A bad but unfortunately widespread habit consists of
17917 setting environment variables before the command, such as in
17918 @samp{CC=my-home-grown-cc ./testsuite}.  The test suite does not
17919 know this change, hence (i) it cannot report it to you, and (ii)
17920 it cannot preserve the value of @code{CC} for subsequent runs.
17921 Autoconf faced exactly the same problem, and solved it by asking
17922 users to pass the variable definitions as command line arguments.
17923 Autotest requires this rule, too, but has no means to enforce it; the log
17924 then contains a trace of the variables that were changed by the user.
17926 @item @file{ChangeLog} excerpts
17927 The topmost lines of all the @file{ChangeLog} files found in the source
17928 hierarchy.  This is especially useful when bugs are reported against
17929 development versions of the package, since the version string does not
17930 provide sufficient information to know the exact state of the sources
17931 the user compiled.  Of course, this relies on the use of a
17932 @file{ChangeLog}.
17934 @item build machine
17935 Running a test suite in a cross-compile environment is not an easy task,
17936 since it would mean having the test suite run on a machine @var{build},
17937 while running programs on a machine @var{host}.  It is much simpler to
17938 run both the test suite and the programs on @var{host}, but then, from
17939 the point of view of the test suite, there remains a single environment,
17940 @var{host} = @var{build}.  The log contains relevant information on the
17941 state of the build machine, including some important environment
17942 variables.
17943 @c FIXME: How about having an M4sh macro to say `hey, log the value
17944 @c of `@dots{}'?  This would help both Autoconf and Autotest.
17946 @item tested programs
17947 The absolute file name and answers to @option{--version} of the tested
17948 programs (see @ref{Writing testsuite.at}, @code{AT_TESTED}).
17950 @item configuration log
17951 The contents of @file{config.log}, as created by @command{configure},
17952 are appended.  It contains the configuration flags and a detailed report
17953 on the configuration itself.
17954 @end table
17957 @node Writing testsuite.at
17958 @section Writing @file{testsuite.at}
17960 The @file{testsuite.at} is a Bourne shell script making use of special
17961 Autotest M4 macros.  It often contains a call to @code{AT_INIT} near
17962 its beginning followed by one call to @code{m4_include} per source file
17963 for tests.  Each such included file, or the remainder of
17964 @file{testsuite.at} if include files are not used, contain a sequence of
17965 test groups.  Each test group begins with a call to @code{AT_SETUP},
17966 then an arbitrary number of shell commands or calls to @code{AT_CHECK},
17967 and then completes with a call to @code{AT_CLEANUP}.
17969 @defmac AT_INIT (@ovar{name})
17970 @atindex{INIT}
17971 @c FIXME: Not clear, plus duplication of the information.
17972 Initialize Autotest.  Giving a @var{name} to the test suite is
17973 encouraged if your package includes several test suites.  In any case,
17974 the test suite always displays the package name and version.  It also
17975 inherits the package bug report address.
17976 @end defmac
17978 @defmac AT_COPYRIGHT (@var{copyright-notice})
17979 @atindex{COPYRIGHT}
17980 @cindex Copyright Notice
17981 State that, in addition to the Free Software Foundation's copyright on
17982 the Autotest macros, parts of your test suite are covered by
17983 @var{copyright-notice}.
17985 The @var{copyright-notice} shows up in both the head of
17986 @command{testsuite} and in @samp{testsuite --version}.
17987 @end defmac
17989 @defmac AT_TESTED (@var{executables})
17990 @atindex{TESTED}
17991 Log the file name and answer to @option{--version} of each program in
17992 space-separated list @var{executables}.  Several invocations register
17993 new executables, in other words, don't fear registering one program
17994 several times.
17995 @end defmac
17997 Autotest test suites rely on @env{PATH} to find the tested program.
17998 This avoids the need to generate absolute names of the various tools, and
17999 makes it possible to test installed programs.  Therefore, knowing which
18000 programs are being exercised is crucial to understanding problems in
18001 the test suite itself, or its occasional misuses.  It is a good idea to
18002 also subscribe foreign programs you depend upon, to avoid incompatible
18003 diagnostics.
18005 @sp 1
18007 @defmac AT_SETUP (@var{test-group-name})
18008 @atindex{SETUP}
18009 This macro starts a group of related tests, all to be executed in the
18010 same subshell.  It accepts a single argument, which holds a few words
18011 (no more than about 30 or 40 characters) quickly describing the purpose
18012 of the test group being started.
18013 @end defmac
18015 @defmac AT_KEYWORDS (@var{keywords})
18016 @atindex{KEYWORDS}
18017 Associate the space-separated list of @var{keywords} to the enclosing
18018 test group.  This makes it possible to run ``slices'' of the test suite.
18019 For instance, if some of your test groups exercise some @samp{foo}
18020 feature, then using @samp{AT_KEYWORDS(foo)} lets you run
18021 @samp{./testsuite -k foo} to run exclusively these test groups.  The
18022 @var{title} of the test group is automatically recorded to
18023 @code{AT_KEYWORDS}.
18025 Several invocations within a test group accumulate new keywords.  In
18026 other words, don't fear registering the same keyword several times in a
18027 test group.
18028 @end defmac
18030 @defmac AT_CAPTURE_FILE (@var{file})
18031 @atindex{CAPTURE_FILE}
18032 If the current test group fails, log the contents of @var{file}.
18033 Several identical calls within one test group have no additional effect.
18034 @end defmac
18036 @defmac AT_XFAIL_IF (@var{shell-condition})
18037 @atindex{XFAIL_IF}
18038 Determine whether the test is expected to fail because it is a known
18039 bug (for unsupported features, you should skip the test).
18040 @var{shell-condition} is a shell expression such as a @code{test}
18041 command; you can instantiate this macro many times from within the
18042 same test group, and one of the conditions is enough to turn
18043 the test into an expected failure.
18044 @end defmac
18046 @defmac AT_CLEANUP
18047 @atindex{CLEANUP}
18048 End the current test group.
18049 @end defmac
18051 @sp 1
18053 @defmac AT_DATA (@var{file}, @var{contents})
18054 @atindex{DATA}
18055 Initialize an input data @var{file} with given @var{contents}.  Of
18056 course, the @var{contents} have to be properly quoted between square
18057 brackets to protect against included commas or spurious M4
18058 expansion.  The contents ought to end with an end of line.
18059 @end defmac
18061 @defmac AT_CHECK (@var{commands}, @dvar{status, 0}, @dvar{stdout, }, @dvar{stderr, }, @ovar{run-if-fail}, @ovar{run-if-pass})
18062 @atindex{CHECK}
18063 Execute a test by performing given shell @var{commands}.  These commands
18064 should normally exit with @var{status}, while producing expected
18065 @var{stdout} and @var{stderr} contents.  If @var{commands} exit with
18066 status 77, then the whole test group is skipped.  Otherwise, if this test
18067 fails, run shell commands @var{run-if-fail} or, if this test passes, run shell
18068 commands @var{run-if-pass}.
18070 The @var{commands} @emph{must not} redirect the standard output, nor the
18071 standard error.
18073 If @var{status}, or @var{stdout}, or @var{stderr} is @samp{ignore}, then
18074 the corresponding value is not checked.
18076 The special value @samp{expout} for @var{stdout} means the expected
18077 output of the @var{commands} is the content of the file @file{expout}.
18078 If @var{stdout} is @samp{stdout}, then the standard output of the
18079 @var{commands} is available for further tests in the file @file{stdout}.
18080 Similarly for @var{stderr} with @samp{expout} and @samp{stderr}.
18081 @end defmac
18084 @node testsuite Invocation
18085 @section Running @command{testsuite} Scripts
18086 @cindex @command{testsuite}
18088 Autotest test suites support the following arguments:
18090 @table @option
18091 @item --help
18092 @itemx -h
18093 Display the list of options and exit successfully.
18095 @item --version
18096 @itemx -V
18097 Display the version of the test suite and exit successfully.
18099 @item --clean
18100 @itemx -c
18101 Remove all the files the test suite might have created and exit.  Meant
18102 for @code{clean} Make targets.
18104 @item --list
18105 @itemx -l
18106 List all the tests (or only the selection), including their possible
18107 keywords.
18108 @end table
18110 @sp 1
18112 By default all tests are performed (or described with
18113 @option{--list}) in the default environment first silently, then
18114 verbosely, but the environment, set of tests, and verbosity level can be
18115 tuned:
18117 @table @samp
18118 @item @var{variable}=@var{value}
18119 Set the environment @var{variable} to @var{value}.  Use this rather
18120 than @samp{FOO=foo ./testsuite} as debugging scripts would then run in a
18121 different environment.
18123 @cindex @code{AUTOTEST_PATH}
18124 The variable @code{AUTOTEST_PATH} specifies the testing path to prepend
18125 to @env{PATH}.  Relative directory names (not starting with
18126 @samp{/}) are considered to be relative to the top level of the
18127 package being built.  All directories are made absolute, first
18128 starting from the top level @emph{build} tree, then from the
18129 @emph{source} tree.  For instance @samp{./testsuite
18130 AUTOTEST_PATH=tests:bin} for a @file{/src/foo-1.0} source package built
18131 in @file{/tmp/foo} results in @samp{/tmp/foo/tests:/tmp/foo/bin} and
18132 then @samp{/src/foo-1.0/tests:/src/foo-1.0/bin} being prepended to
18133 @env{PATH}.
18135 @item @var{number}
18136 @itemx @var{number}-@var{number}
18137 @itemx @var{number}-
18138 @itemx -@var{number}
18139 Add the corresponding test groups, with obvious semantics, to the
18140 selection.
18142 @item --keywords=@var{keywords}
18143 @itemx -k @var{keywords}
18144 Add to the selection the test groups with title or keywords (arguments
18145 to @code{AT_SETUP} or @code{AT_KEYWORDS}) that match @emph{all} keywords
18146 of the comma separated list @var{keywords}, case-insensitively.  Use
18147 @samp{!} immediately before the keyword to invert the selection for this
18148 keyword.  By default, the keywords match whole words; enclose them in
18149 @samp{.*} to also match parts of words.
18151 For example, running
18153 @example
18154 @kbd{./testsuite -k 'autoupdate,.*FUNC.*'}
18155 @end example
18157 @noindent
18158 selects all tests tagged @samp{autoupdate} @emph{and} with tags
18159 containing @samp{FUNC} (as in @samp{AC_CHECK_FUNC}, @samp{AC_FUNC_ALLOCA},
18160 etc.), while
18162 @example
18163 @kbd{./testsuite -k '!autoupdate' -k '.*FUNC.*'}
18164 @end example
18166 @noindent
18167 selects all tests not tagged @samp{autoupdate} @emph{or} with tags
18168 containing @samp{FUNC}.
18170 @item --errexit
18171 @itemx -e
18172 If any test fails, immediately abort testing.  It implies
18173 @option{--debug}: post test group clean up, and top-level logging
18174 are inhibited.  This option is meant for the full test
18175 suite, it is not really useful for generated debugging scripts.
18177 @item --verbose
18178 @itemx -v
18179 Force more verbosity in the detailed output of what is being done.  This
18180 is the default for debugging scripts.
18182 @item --debug
18183 @itemx -d
18184 Do not remove the files after a test group was performed ---but they are
18185 still removed @emph{before}, therefore using this option is sane when
18186 running several test groups.  Create debugging scripts.  Do not
18187 overwrite the top-level
18188 log (in order to preserve supposedly existing full log file).  This is
18189 the default for debugging scripts, but it can also be useful to debug
18190 the testsuite itself.
18192 @item --trace
18193 @itemx -x
18194 Trigger shell tracing of the test groups.
18195 @end table
18198 @node Making testsuite Scripts
18199 @section Making @command{testsuite} Scripts
18201 For putting Autotest into movement, you need some configuration and
18202 makefile machinery.  We recommend, at least if your package uses deep or
18203 shallow hierarchies, that you use @file{tests/} as the name of the
18204 directory holding all your tests and their makefile.  Here is a
18205 check list of things to do.
18207 @itemize @minus
18209 @item
18210 @cindex @file{package.m4}
18211 Make sure to create the file @file{package.m4}, which defines the
18212 identity of the package.  It must define @code{AT_PACKAGE_STRING}, the
18213 full signature of the package, and @code{AT_PACKAGE_BUGREPORT}, the
18214 address to which bug reports should be sent.  For sake of completeness,
18215 we suggest that you also define @code{AT_PACKAGE_NAME},
18216 @code{AT_PACKAGE_TARNAME}, and @code{AT_PACKAGE_VERSION}.
18217 @xref{Initializing configure}, for a description of these variables.  We
18218 suggest the following makefile excerpt:
18220 @smallexample
18221 $(srcdir)/package.m4: $(top_srcdir)/configure.ac
18222         @{                                      \
18223           echo '# Signature of the current package.'; \
18224           echo 'm4_define([AT_PACKAGE_NAME],      [@@PACKAGE_NAME@@])'; \
18225           echo 'm4_define([AT_PACKAGE_TARNAME],   [@@PACKAGE_TARNAME@@])'; \
18226           echo 'm4_define([AT_PACKAGE_VERSION],   [@@PACKAGE_VERSION@@])'; \
18227           echo 'm4_define([AT_PACKAGE_STRING],    [@@PACKAGE_STRING@@])'; \
18228           echo 'm4_define([AT_PACKAGE_BUGREPORT], [@@PACKAGE_BUGREPORT@@])'; \
18229         @} >'$(srcdir)/package.m4'
18230 @end smallexample
18232 @noindent
18233 Be sure to distribute @file{package.m4} and to put it into the source
18234 hierarchy: the test suite ought to be shipped!
18236 @item
18237 Invoke @code{AC_CONFIG_TESTDIR}.
18239 @defmac AC_CONFIG_TESTDIR (@var{directory}, @dvar{test-path, directory})
18240 @acindex{CONFIG_TESTDIR}
18241 An Autotest test suite is to be configured in @var{directory}.  This
18242 macro requires the instantiation of @file{@var{directory}/atconfig} from
18243 @file{@var{directory}/atconfig.in}, and sets the default
18244 @code{AUTOTEST_PATH} to @var{test-path} (@pxref{testsuite Invocation}).
18245 @end defmac
18247 @item
18248 Still within @file{configure.ac}, as appropriate, ensure that some
18249 @code{AC_CONFIG_FILES} command includes substitution for
18250 @file{tests/atlocal}.
18252 @item
18253 The @file{tests/Makefile.in} should be modified so the validation in
18254 your package is triggered by @samp{make check}.  An example is provided
18255 below.
18256 @end itemize
18258 With Automake, here is a minimal example about how to link @samp{make
18259 check} with a validation suite.
18261 @example
18262 EXTRA_DIST = testsuite.at $(TESTSUITE) atlocal.in
18263 TESTSUITE = $(srcdir)/testsuite
18265 check-local: atconfig atlocal $(TESTSUITE)
18266         $(SHELL) '$(TESTSUITE)' $(TESTSUITEFLAGS)
18268 installcheck-local: atconfig atlocal $(TESTSUITE)
18269         $(SHELL) '$(TESTSUITE)' AUTOTEST_PATH='$(bindir)' \
18270           $(TESTSUITEFLAGS)
18272 clean-local:
18273         test ! -f '$(TESTSUITE)' || \
18274          $(SHELL) '$(TESTSUITE)' --clean
18276 AUTOTEST = $(AUTOM4TE) --language=autotest
18277 $(TESTSUITE): $(srcdir)/testsuite.at
18278         $(AUTOTEST) -I '$(srcdir)' -o $@@.tmp $@@.at
18279         mv $@@.tmp $@@
18280 @end example
18282 You might want to list explicitly the dependencies, i.e., the list of
18283 the files @file{testsuite.at} includes.
18285 With strict Autoconf, you might need to add lines inspired from the
18286 following:
18288 @example
18289 subdir = tests
18291 atconfig: $(top_builddir)/config.status
18292         cd $(top_builddir) && \
18293            $(SHELL) ./config.status $(subdir)/$@@
18295 atlocal: $(srcdir)/atlocal.in $(top_builddir)/config.status
18296         cd $(top_builddir) && \
18297            $(SHELL) ./config.status $(subdir)/$@@
18298 @end example
18300 @noindent
18301 and manage to have @file{atconfig.in} and @code{$(EXTRA_DIST)}
18302 distributed.
18304 With all this in place, and if you have not initialized @samp{TESTSUITEFLAGS}
18305 within your makefile, you can fine-tune test suite execution with this variable,
18306 for example:
18308 @example
18309 make check TESTSUITEFLAGS='-v -d -x 75 -k AC_PROG_CC CFLAGS=-g'
18310 @end example
18314 @c =============================== Frequent Autoconf Questions, with answers
18316 @node FAQ
18317 @chapter Frequent Autoconf Questions, with answers
18319 Several questions about Autoconf come up occasionally.  Here some of them
18320 are addressed.
18322 @menu
18323 * Distributing::                Distributing @command{configure} scripts
18324 * Why GNU M4::                  Why not use the standard M4?
18325 * Bootstrapping::               Autoconf and @acronym{GNU} M4 require each other?
18326 * Why Not Imake::               Why @acronym{GNU} uses @command{configure} instead of Imake
18327 * Defining Directories::        Passing @code{datadir} to program
18328 * autom4te.cache::              What is it?  Can I remove it?
18329 * Present But Cannot Be Compiled::  Compiler and Preprocessor Disagree
18330 @end menu
18332 @node Distributing
18333 @section Distributing @command{configure} Scripts
18334 @cindex License
18336 @display
18337 What are the restrictions on distributing @command{configure}
18338 scripts that Autoconf generates?  How does that affect my
18339 programs that use them?
18340 @end display
18342 There are no restrictions on how the configuration scripts that Autoconf
18343 produces may be distributed or used.  In Autoconf version 1, they were
18344 covered by the @acronym{GNU} General Public License.  We still encourage
18345 software authors to distribute their work under terms like those of the
18346 @acronym{GPL}, but doing so is not required to use Autoconf.
18348 Of the other files that might be used with @command{configure},
18349 @file{config.h.in} is under whatever copyright you use for your
18350 @file{configure.ac}.  @file{config.sub} and @file{config.guess} have an
18351 exception to the @acronym{GPL} when they are used with an Autoconf-generated
18352 @command{configure} script, which permits you to distribute them under the
18353 same terms as the rest of your package.  @file{install-sh} is from the X
18354 Consortium and is not copyrighted.
18356 @node Why GNU M4
18357 @section Why Require @acronym{GNU} M4?
18359 @display
18360 Why does Autoconf require @acronym{GNU} M4?
18361 @end display
18363 Many M4 implementations have hard-coded limitations on the size and
18364 number of macros that Autoconf exceeds.  They also lack several
18365 builtin macros that it would be difficult to get along without in a
18366 sophisticated application like Autoconf, including:
18368 @example
18369 m4_builtin
18370 m4_indir
18371 m4_bpatsubst
18372 __file__
18373 __line__
18374 @end example
18376 Autoconf requires version 1.4.7 or later of @acronym{GNU} M4.
18378 Since only software maintainers need to use Autoconf, and since @acronym{GNU}
18379 M4 is simple to configure and install, it seems reasonable to require
18380 @acronym{GNU} M4 to be installed also.  Many maintainers of @acronym{GNU} and
18381 other free software already have most of the @acronym{GNU} utilities
18382 installed, since they prefer them.
18384 @node Bootstrapping
18385 @section How Can I Bootstrap?
18386 @cindex Bootstrap
18388 @display
18389 If Autoconf requires @acronym{GNU} M4 and @acronym{GNU} M4 has an Autoconf
18390 @command{configure} script, how do I bootstrap?  It seems like a chicken
18391 and egg problem!
18392 @end display
18394 This is a misunderstanding.  Although @acronym{GNU} M4 does come with a
18395 @command{configure} script produced by Autoconf, Autoconf is not required
18396 in order to run the script and install @acronym{GNU} M4.  Autoconf is only
18397 required if you want to change the M4 @command{configure} script, which few
18398 people have to do (mainly its maintainer).
18400 @node Why Not Imake
18401 @section Why Not Imake?
18402 @cindex Imake
18404 @display
18405 Why not use Imake instead of @command{configure} scripts?
18406 @end display
18408 Several people have written addressing this question, so I include
18409 adaptations of their explanations here.
18411 The following answer is based on one written by Richard Pixley:
18413 @quotation
18414 Autoconf generated scripts frequently work on machines that it has
18415 never been set up to handle before.  That is, it does a good job of
18416 inferring a configuration for a new system.  Imake cannot do this.
18418 Imake uses a common database of host specific data.  For X11, this makes
18419 sense because the distribution is made as a collection of tools, by one
18420 central authority who has control over the database.
18422 @acronym{GNU} tools are not released this way.  Each @acronym{GNU} tool has a
18423 maintainer; these maintainers are scattered across the world.  Using a
18424 common database would be a maintenance nightmare.  Autoconf may appear
18425 to be this kind of database, but in fact it is not.  Instead of listing
18426 host dependencies, it lists program requirements.
18428 If you view the @acronym{GNU} suite as a collection of native tools, then the
18429 problems are similar.  But the @acronym{GNU} development tools can be
18430 configured as cross tools in almost any host+target permutation.  All of
18431 these configurations can be installed concurrently.  They can even be
18432 configured to share host independent files across hosts.  Imake doesn't
18433 address these issues.
18435 Imake templates are a form of standardization.  The @acronym{GNU} coding
18436 standards address the same issues without necessarily imposing the same
18437 restrictions.
18438 @end quotation
18441 Here is some further explanation, written by Per Bothner:
18443 @quotation
18444 One of the advantages of Imake is that it easy to generate large
18445 makefiles using the @samp{#include} and macro mechanisms of @command{cpp}.
18446 However, @code{cpp} is not programmable: it has limited conditional
18447 facilities, and no looping.  And @code{cpp} cannot inspect its
18448 environment.
18450 All of these problems are solved by using @code{sh} instead of
18451 @code{cpp}.  The shell is fully programmable, has macro substitution,
18452 can execute (or source) other shell scripts, and can inspect its
18453 environment.
18454 @end quotation
18457 Paul Eggert elaborates more:
18459 @quotation
18460 With Autoconf, installers need not assume that Imake itself is already
18461 installed and working well.  This may not seem like much of an advantage
18462 to people who are accustomed to Imake.  But on many hosts Imake is not
18463 installed or the default installation is not working well, and requiring
18464 Imake to install a package hinders the acceptance of that package on
18465 those hosts.  For example, the Imake template and configuration files
18466 might not be installed properly on a host, or the Imake build procedure
18467 might wrongly assume that all source files are in one big directory
18468 tree, or the Imake configuration might assume one compiler whereas the
18469 package or the installer needs to use another, or there might be a
18470 version mismatch between the Imake expected by the package and the Imake
18471 supported by the host.  These problems are much rarer with Autoconf,
18472 where each package comes with its own independent configuration
18473 processor.
18475 Also, Imake often suffers from unexpected interactions between
18476 @command{make} and the installer's C preprocessor.  The fundamental problem
18477 here is that the C preprocessor was designed to preprocess C programs,
18478 not makefiles.  This is much less of a problem with Autoconf,
18479 which uses the general-purpose preprocessor M4, and where the
18480 package's author (rather than the installer) does the preprocessing in a
18481 standard way.
18482 @end quotation
18485 Finally, Mark Eichin notes:
18487 @quotation
18488 Imake isn't all that extensible, either.  In order to add new features to
18489 Imake, you need to provide your own project template, and duplicate most
18490 of the features of the existing one.  This means that for a sophisticated
18491 project, using the vendor-provided Imake templates fails to provide any
18492 leverage---since they don't cover anything that your own project needs
18493 (unless it is an X11 program).
18495 On the other side, though:
18497 The one advantage that Imake has over @command{configure}:
18498 @file{Imakefile} files tend to be much shorter (likewise, less redundant)
18499 than @file{Makefile.in} files.  There is a fix to this, however---at least
18500 for the Kerberos V5 tree, we've modified things to call in common
18501 @file{post.in} and @file{pre.in} makefile fragments for the
18502 entire tree.  This means that a lot of common things don't have to be
18503 duplicated, even though they normally are in @command{configure} setups.
18504 @end quotation
18507 @node Defining Directories
18508 @section How Do I @code{#define} Installation Directories?
18510 @display
18511 My program needs library files, installed in @code{datadir} and
18512 similar.  If I use
18514 @example
18515 AC_DEFINE_UNQUOTED([DATADIR], [$datadir],
18516   [Define to the read-only architecture-independent
18517    data directory.])
18518 @end example
18520 @noindent
18521 I get
18523 @example
18524 #define DATADIR "$@{prefix@}/share"
18525 @end example
18526 @end display
18528 As already explained, this behavior is on purpose, mandated by the
18529 @acronym{GNU} Coding Standards, see @ref{Installation Directory
18530 Variables}.  There are several means to achieve a similar goal:
18532 @itemize @minus
18533 @item
18534 Do not use @code{AC_DEFINE} but use your makefile to pass the
18535 actual value of @code{datadir} via compilation flags.
18536 @xref{Installation Directory Variables}, for the details.
18538 @item
18539 This solution can be simplified when compiling a program: you may either
18540 extend the @code{CPPFLAGS}:
18542 @example
18543 CPPFLAGS = -DDATADIR='"$(datadir)"' @@CPPFLAGS@@
18544 @end example
18546 @noindent
18547 or create a dedicated header file:
18549 @example
18550 DISTCLEANFILES = datadir.h
18551 datadir.h: Makefile
18552         echo '#define DATADIR "$(datadir)"' >$@@
18553 @end example
18555 @item
18556 Use @code{AC_DEFINE} but have @command{configure} compute the literal
18557 value of @code{datadir} and others.  Many people have wrapped macros to
18558 automate this task.  For instance, the macro @code{AC_DEFINE_DIR} from
18559 the @uref{http://autoconf-archive.cryp.to/, Autoconf Macro
18560 Archive}.
18562 This solution does not conform to the @acronym{GNU} Coding Standards.
18564 @item
18565 Note that all the previous solutions hard wire the absolute name of
18566 these directories in the executables, which is not a good property.  You
18567 may try to compute the names relative to @code{prefix}, and try to
18568 find @code{prefix} at runtime, this way your package is relocatable.
18569 Some macros are already available to address this issue: see
18570 @code{adl_COMPUTE_RELATIVE_PATHS} and
18571 @code{adl_COMPUTE_STANDARD_RELATIVE_PATHS} on the
18572 @uref{http://autoconf-archive.cryp.to/,
18573 Autoconf Macro Archive}.
18574 @end itemize
18577 @node autom4te.cache
18578 @section What is @file{autom4te.cache}?
18580 @display
18581 What is this directory @file{autom4te.cache}?  Can I safely remove it?
18582 @end display
18584 In the @acronym{GNU} Build System, @file{configure.ac} plays a central
18585 role and is read by many tools: @command{autoconf} to create
18586 @file{configure}, @command{autoheader} to create @file{config.h.in},
18587 @command{automake} to create @file{Makefile.in}, @command{autoscan} to
18588 check the completeness of @file{configure.ac}, @command{autoreconf} to
18589 check the @acronym{GNU} Build System components that are used.  To
18590 ``read @file{configure.ac}'' actually means to compile it with M4,
18591 which can be a long process for complex @file{configure.ac}.
18593 This is why all these tools, instead of running directly M4, invoke
18594 @command{autom4te} (@pxref{autom4te Invocation}) which, while answering to
18595 a specific demand, stores additional information in
18596 @file{autom4te.cache} for future runs.  For instance, if you run
18597 @command{autoconf}, behind the scenes, @command{autom4te} also
18598 stores information for the other tools, so that when you invoke
18599 @command{autoheader} or @command{automake} etc., reprocessing
18600 @file{configure.ac} is not needed.  The speed up is frequently of 30%,
18601 and is increasing with the size of @file{configure.ac}.
18603 But it is and remains being simply a cache: you can safely remove it.
18605 @sp 1
18607 @display
18608 Can I permanently get rid of it?
18609 @end display
18611 The creation of this cache can be disabled from
18612 @file{~/.autom4te.cfg}, see @ref{Customizing autom4te}, for more
18613 details.  You should be aware that disabling the cache slows down the
18614 Autoconf test suite by 40%.  The more @acronym{GNU} Build System
18615 components are used, the more the cache is useful; for instance
18616 running @samp{autoreconf -f} on the Core Utilities is twice slower without
18617 the cache @emph{although @option{--force} implies that the cache is
18618 not fully exploited}, and eight times slower than without
18619 @option{--force}.
18622 @node Present But Cannot Be Compiled
18623 @section Header Present But Cannot Be Compiled
18625 The most important guideline to bear in mind when checking for
18626 features is to mimic as much as possible the intended use.
18627 Unfortunately, old versions of @code{AC_CHECK_HEADER} and
18628 @code{AC_CHECK_HEADERS} failed to follow this idea, and called
18629 the preprocessor, instead of the compiler, to check for headers.  As a
18630 result, incompatibilities between headers went unnoticed during
18631 configuration, and maintainers finally had to deal with this issue
18632 elsewhere.
18634 As of Autoconf 2.56 both checks are performed, and @code{configure}
18635 complains loudly if the compiler and the preprocessor do not agree.
18636 For the time being the result used is that of the preprocessor, to give
18637 maintainers time to adjust their @file{configure.ac}, but in the
18638 future, only the compiler will be considered.
18640 Consider the following example:
18642 @smallexample
18643 $ @kbd{cat number.h}
18644 typedef int number;
18645 $ @kbd{cat pi.h}
18646 const number pi = 3;
18647 $ @kbd{cat configure.ac}
18648 AC_INIT([Example], [1.0], [bug-example@@example.org])
18649 AC_CHECK_HEADERS([pi.h])
18650 $ @kbd{autoconf -Wall}
18651 $ @kbd{./configure}
18652 checking for gcc... gcc
18653 checking for C compiler default output file name... a.out
18654 checking whether the C compiler works... yes
18655 checking whether we are cross compiling... no
18656 checking for suffix of executables...
18657 checking for suffix of object files... o
18658 checking whether we are using the GNU C compiler... yes
18659 checking whether gcc accepts -g... yes
18660 checking for gcc option to accept ISO C89... none needed
18661 checking how to run the C preprocessor... gcc -E
18662 checking for grep that handles long lines and -e... grep
18663 checking for egrep... grep -E
18664 checking for ANSI C header files... yes
18665 checking for sys/types.h... yes
18666 checking for sys/stat.h... yes
18667 checking for stdlib.h... yes
18668 checking for string.h... yes
18669 checking for memory.h... yes
18670 checking for strings.h... yes
18671 checking for inttypes.h... yes
18672 checking for stdint.h... yes
18673 checking for unistd.h... yes
18674 checking pi.h usability... no
18675 checking pi.h presence... yes
18676 configure: WARNING: pi.h: present but cannot be compiled
18677 configure: WARNING: pi.h:     check for missing prerequisite headers?
18678 configure: WARNING: pi.h: see the Autoconf documentation
18679 configure: WARNING: pi.h:     section "Present But Cannot Be Compiled"
18680 configure: WARNING: pi.h: proceeding with the preprocessor's result
18681 configure: WARNING: pi.h: in the future, the compiler will take precedence
18682 configure: WARNING:     ## -------------------------------------- ##
18683 configure: WARNING:     ## Report this to bug-example@@example.org ##
18684 configure: WARNING:     ## -------------------------------------- ##
18685 checking for pi.h... yes
18686 @end smallexample
18688 @noindent
18689 The proper way the handle this case is using the fourth argument
18690 (@pxref{Generic Headers}):
18692 @example
18693 $ @kbd{cat configure.ac}
18694 AC_INIT([Example], [1.0], [bug-example@@example.org])
18695 AC_CHECK_HEADERS([number.h pi.h], [], [],
18696 [[#ifdef HAVE_NUMBER_H
18697 # include <number.h>
18698 #endif
18700 $ @kbd{autoconf -Wall}
18701 $ @kbd{./configure}
18702 checking for gcc... gcc
18703 checking for C compiler default output... a.out
18704 checking whether the C compiler works... yes
18705 checking whether we are cross compiling... no
18706 checking for suffix of executables...
18707 checking for suffix of object files... o
18708 checking whether we are using the GNU C compiler... yes
18709 checking whether gcc accepts -g... yes
18710 checking for gcc option to accept ANSI C... none needed
18711 checking for number.h... yes
18712 checking for pi.h... yes
18713 @end example
18715 See @ref{Particular Headers}, for a list of headers with their
18716 prerequisite.
18718 @c ===================================================== History of Autoconf.
18720 @node History
18721 @chapter History of Autoconf
18722 @cindex History of autoconf
18724 You may be wondering, Why was Autoconf originally written?  How did it
18725 get into its present form?  (Why does it look like gorilla spit?)  If
18726 you're not wondering, then this chapter contains no information useful
18727 to you, and you might as well skip it.  If you @emph{are} wondering,
18728 then let there be light@enddots{}
18730 @menu
18731 * Genesis::                     Prehistory and naming of @command{configure}
18732 * Exodus::                      The plagues of M4 and Perl
18733 * Leviticus::                   The priestly code of portability arrives
18734 * Numbers::                     Growth and contributors
18735 * Deuteronomy::                 Approaching the promises of easy configuration
18736 @end menu
18738 @node Genesis
18739 @section Genesis
18741 In June 1991 I was maintaining many of the @acronym{GNU} utilities for the
18742 Free Software Foundation.  As they were ported to more platforms and
18743 more programs were added, the number of @option{-D} options that users
18744 had to select in the makefile (around 20) became burdensome.
18745 Especially for me---I had to test each new release on a bunch of
18746 different systems.  So I wrote a little shell script to guess some of
18747 the correct settings for the fileutils package, and released it as part
18748 of fileutils 2.0.  That @command{configure} script worked well enough that
18749 the next month I adapted it (by hand) to create similar @command{configure}
18750 scripts for several other @acronym{GNU} utilities packages.  Brian Berliner
18751 also adapted one of my scripts for his @acronym{CVS} revision control system.
18753 Later that summer, I learned that Richard Stallman and Richard Pixley
18754 were developing similar scripts to use in the @acronym{GNU} compiler tools;
18755 so I adapted my @command{configure} scripts to support their evolving
18756 interface: using the file name @file{Makefile.in} as the templates;
18757 adding @samp{+srcdir}, the first option (of many); and creating
18758 @file{config.status} files.
18760 @node Exodus
18761 @section Exodus
18763 As I got feedback from users, I incorporated many improvements, using
18764 Emacs to search and replace, cut and paste, similar changes in each of
18765 the scripts.  As I adapted more @acronym{GNU} utilities packages to use
18766 @command{configure} scripts, updating them all by hand became impractical.
18767 Rich Murphey, the maintainer of the @acronym{GNU} graphics utilities, sent me
18768 mail saying that the @command{configure} scripts were great, and asking if
18769 I had a tool for generating them that I could send him.  No, I thought,
18770 but I should!  So I started to work out how to generate them.  And the
18771 journey from the slavery of hand-written @command{configure} scripts to the
18772 abundance and ease of Autoconf began.
18774 Cygnus @command{configure}, which was being developed at around that time,
18775 is table driven; it is meant to deal mainly with a discrete number of
18776 system types with a small number of mainly unguessable features (such as
18777 details of the object file format).  The automatic configuration system
18778 that Brian Fox had developed for Bash takes a similar approach.  For
18779 general use, it seems to me a hopeless cause to try to maintain an
18780 up-to-date database of which features each variant of each operating
18781 system has.  It's easier and more reliable to check for most features on
18782 the fly---especially on hybrid systems that people have hacked on
18783 locally or that have patches from vendors installed.
18785 I considered using an architecture similar to that of Cygnus
18786 @command{configure}, where there is a single @command{configure} script that
18787 reads pieces of @file{configure.in} when run.  But I didn't want to have
18788 to distribute all of the feature tests with every package, so I settled
18789 on having a different @command{configure} made from each
18790 @file{configure.in} by a preprocessor.  That approach also offered more
18791 control and flexibility.
18793 I looked briefly into using the Metaconfig package, by Larry Wall,
18794 Harlan Stenn, and Raphael Manfredi, but I decided not to for several
18795 reasons.  The @command{Configure} scripts it produces are interactive,
18796 which I find quite inconvenient; I didn't like the ways it checked for
18797 some features (such as library functions); I didn't know that it was
18798 still being maintained, and the @command{Configure} scripts I had
18799 seen didn't work on many modern systems (such as System V R4 and NeXT);
18800 it wasn't flexible in what it could do in response to a feature's
18801 presence or absence; I found it confusing to learn; and it was too big
18802 and complex for my needs (I didn't realize then how much Autoconf would
18803 eventually have to grow).
18805 I considered using Perl to generate my style of @command{configure}
18806 scripts, but decided that M4 was better suited to the job of simple
18807 textual substitutions: it gets in the way less, because output is
18808 implicit.  Plus, everyone already has it.  (Initially I didn't rely on
18809 the @acronym{GNU} extensions to M4.)  Also, some of my friends at the
18810 University of Maryland had recently been putting M4 front ends on
18811 several programs, including @code{tvtwm}, and I was interested in trying
18812 out a new language.
18814 @node Leviticus
18815 @section Leviticus
18817 Since my @command{configure} scripts determine the system's capabilities
18818 automatically, with no interactive user intervention, I decided to call
18819 the program that generates them Autoconfig.  But with a version number
18820 tacked on, that name would be too long for old Unix file systems,
18821 so I shortened it to Autoconf.
18823 In the fall of 1991 I called together a group of fellow questers after
18824 the Holy Grail of portability (er, that is, alpha testers) to give me
18825 feedback as I encapsulated pieces of my handwritten scripts in M4 macros
18826 and continued to add features and improve the techniques used in the
18827 checks.  Prominent among the testers were Fran@,{c}ois Pinard, who came up
18828 with the idea of making an Autoconf shell script to run M4
18829 and check for unresolved macro calls; Richard Pixley, who suggested
18830 running the compiler instead of searching the file system to find
18831 include files and symbols, for more accurate results; Karl Berry, who
18832 got Autoconf to configure @TeX{} and added the macro index to the
18833 documentation; and Ian Lance Taylor, who added support for creating a C
18834 header file as an alternative to putting @option{-D} options in a
18835 makefile, so he could use Autoconf for his @acronym{UUCP} package.
18836 The alpha testers cheerfully adjusted their files again and again as the
18837 names and calling conventions of the Autoconf macros changed from
18838 release to release.  They all contributed many specific checks, great
18839 ideas, and bug fixes.
18841 @node Numbers
18842 @section Numbers
18844 In July 1992, after months of alpha testing, I released Autoconf 1.0,
18845 and converted many @acronym{GNU} packages to use it.  I was surprised by how
18846 positive the reaction to it was.  More people started using it than I
18847 could keep track of, including people working on software that wasn't
18848 part of the @acronym{GNU} Project (such as TCL, FSP, and Kerberos V5).
18849 Autoconf continued to improve rapidly, as many people using the
18850 @command{configure} scripts reported problems they encountered.
18852 Autoconf turned out to be a good torture test for M4 implementations.
18853 Unix M4 started to dump core because of the length of the
18854 macros that Autoconf defined, and several bugs showed up in @acronym{GNU}
18855 M4 as well.  Eventually, we realized that we needed to use some
18856 features that only @acronym{GNU} M4 has.  4.3@acronym{BSD} M4, in
18857 particular, has an impoverished set of builtin macros; the System V
18858 version is better, but still doesn't provide everything we need.
18860 More development occurred as people put Autoconf under more stresses
18861 (and to uses I hadn't anticipated).  Karl Berry added checks for X11.
18862 david zuhn contributed C++ support.  Fran@,{c}ois Pinard made it diagnose
18863 invalid arguments.  Jim Blandy bravely coerced it into configuring
18864 @acronym{GNU} Emacs, laying the groundwork for several later improvements.
18865 Roland McGrath got it to configure the @acronym{GNU} C Library, wrote the
18866 @command{autoheader} script to automate the creation of C header file
18867 templates, and added a @option{--verbose} option to @command{configure}.
18868 Noah Friedman added the @option{--autoconf-dir} option and
18869 @code{AC_MACRODIR} environment variable.  (He also coined the term
18870 @dfn{autoconfiscate} to mean ``adapt a software package to use
18871 Autoconf''.)  Roland and Noah improved the quoting protection in
18872 @code{AC_DEFINE} and fixed many bugs, especially when I got sick of
18873 dealing with portability problems from February through June, 1993.
18875 @node Deuteronomy
18876 @section Deuteronomy
18878 A long wish list for major features had accumulated, and the effect of
18879 several years of patching by various people had left some residual
18880 cruft.  In April 1994, while working for Cygnus Support, I began a major
18881 revision of Autoconf.  I added most of the features of the Cygnus
18882 @command{configure} that Autoconf had lacked, largely by adapting the
18883 relevant parts of Cygnus @command{configure} with the help of david zuhn
18884 and Ken Raeburn.  These features include support for using
18885 @file{config.sub}, @file{config.guess}, @option{--host}, and
18886 @option{--target}; making links to files; and running @command{configure}
18887 scripts in subdirectories.  Adding these features enabled Ken to convert
18888 @acronym{GNU} @code{as}, and Rob Savoye to convert Deja@acronym{GNU}, to using
18889 Autoconf.
18891 I added more features in response to other peoples' requests.  Many
18892 people had asked for @command{configure} scripts to share the results of
18893 the checks between runs, because (particularly when configuring a large
18894 source tree, like Cygnus does) they were frustratingly slow.  Mike
18895 Haertel suggested adding site-specific initialization scripts.  People
18896 distributing software that had to unpack on MS-DOS asked for a way to
18897 override the @file{.in} extension on the file names, which produced file
18898 names like @file{config.h.in} containing two dots.  Jim Avera did an
18899 extensive examination of the problems with quoting in @code{AC_DEFINE}
18900 and @code{AC_SUBST}; his insights led to significant improvements.
18901 Richard Stallman asked that compiler output be sent to @file{config.log}
18902 instead of @file{/dev/null}, to help people debug the Emacs
18903 @command{configure} script.
18905 I made some other changes because of my dissatisfaction with the quality
18906 of the program.  I made the messages showing results of the checks less
18907 ambiguous, always printing a result.  I regularized the names of the
18908 macros and cleaned up coding style inconsistencies.  I added some
18909 auxiliary utilities that I had developed to help convert source code
18910 packages to use Autoconf.  With the help of Fran@,{c}ois Pinard, I made
18911 the macros not interrupt each others' messages.  (That feature revealed
18912 some performance bottlenecks in @acronym{GNU} M4, which he hastily
18913 corrected!)  I reorganized the documentation around problems people want
18914 to solve.  And I began a test suite, because experience had shown that
18915 Autoconf has a pronounced tendency to regress when we change it.
18917 Again, several alpha testers gave invaluable feedback, especially
18918 Fran@,{c}ois Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn,
18919 and Mark Eichin.
18921 Finally, version 2.0 was ready.  And there was much rejoicing.  (And I
18922 have free time again.  I think.  Yeah, right.)
18925 @c ========================================================== Appendices
18927 @node Copying This Manual
18928 @appendix Copying This Manual
18929 @cindex License
18931 @menu
18932 * GNU Free Documentation License::  License for copying this manual
18933 @end menu
18935 @include fdl.texi
18937 @node Indices
18938 @appendix Indices
18940 @menu
18941 * Environment Variable Index::  Index of environment variables used
18942 * Output Variable Index::       Index of variables set in output files
18943 * Preprocessor Symbol Index::   Index of C preprocessor symbols defined
18944 * Autoconf Macro Index::        Index of Autoconf macros
18945 * M4 Macro Index::              Index of M4, M4sugar, and M4sh macros
18946 * Autotest Macro Index::        Index of Autotest macros
18947 * Program & Function Index::    Index of those with portability problems
18948 * Concept Index::               General index
18949 @end menu
18951 @node Environment Variable Index
18952 @appendixsec Environment Variable Index
18954 This is an alphabetical list of the environment variables that Autoconf
18955 checks.
18957 @printindex ev
18959 @node Output Variable Index
18960 @appendixsec Output Variable Index
18962 This is an alphabetical list of the variables that Autoconf can
18963 substitute into files that it creates, typically one or more
18964 makefiles.  @xref{Setting Output Variables}, for more information
18965 on how this is done.
18967 @printindex ov
18969 @node Preprocessor Symbol Index
18970 @appendixsec Preprocessor Symbol Index
18972 This is an alphabetical list of the C preprocessor symbols that the
18973 Autoconf macros define.  To work with Autoconf, C source code needs to
18974 use these names in @code{#if} or @code{#ifdef} directives.
18976 @printindex cv
18978 @node Autoconf Macro Index
18979 @appendixsec Autoconf Macro Index
18981 This is an alphabetical list of the Autoconf macros.
18982 @ifset shortindexflag
18983 To make the list easier to use, the macros are listed without their
18984 preceding @samp{AC_}.
18985 @end ifset
18987 @printindex AC
18989 @node M4 Macro Index
18990 @appendixsec M4 Macro Index
18992 This is an alphabetical list of the M4, M4sugar, and M4sh macros.
18993 @ifset shortindexflag
18994 To make the list easier to use, the macros are listed without their
18995 preceding @samp{m4_} or @samp{AS_}.
18996 @end ifset
18998 @printindex MS
19000 @node Autotest Macro Index
19001 @appendixsec Autotest Macro Index
19003 This is an alphabetical list of the Autotest macros.
19004 @ifset shortindexflag
19005 To make the list easier to use, the macros are listed without their
19006 preceding @samp{AT_}.
19007 @end ifset
19009 @printindex AT
19011 @node Program & Function Index
19012 @appendixsec Program and Function Index
19014 This is an alphabetical list of the programs and functions which
19015 portability is discussed in this document.
19017 @printindex pr
19019 @node Concept Index
19020 @appendixsec Concept Index
19022 This is an alphabetical list of the files, tools, and concepts
19023 introduced in this document.
19025 @printindex cp
19027 @bye
19029 @c  LocalWords:  texinfo setfilename autoconf texi settitle setchapternewpage
19030 @c  LocalWords:  setcontentsaftertitlepage finalout ARG ovar varname dvar acx
19031 @c  LocalWords:  makeinfo dvi defcodeindex ev ov CPP cv Autotest mv defindex fn
19032 @c  LocalWords:  shortindexflag iftex ifset acindex ACindex ifclear ahindex fu
19033 @c  LocalWords:  asindex MSindex atindex ATindex auindex hdrindex prindex FIXME
19034 @c  LocalWords:  msindex alloca fnindex Aaarg indices FSF's dircategory ifnames
19035 @c  LocalWords:  direntry autoscan autoreconf autoheader autoupdate config FDs
19036 @c  LocalWords:  testsuite titlepage Elliston Demaille vskip filll ifnottex hmm
19037 @c  LocalWords:  insertcopying Autoconf's detailmenu Automake Libtool Posix ois
19038 @c  LocalWords:  Systemology Checkpointing Changequote INTERCAL changequote dfn
19039 @c  LocalWords:  Quadrigraphs builtins Shellology acconfig Bugward LIBOBJ Imake
19040 @c  LocalWords:  LIBOBJS IFELSE cindex flushright Pinard Metaconfig uref Simons
19041 @c  LocalWords:  distclean uninstall noindent versioning Tromey dir
19042 @c  LocalWords:  SAMS samp aclocal acsite underquoted emph itemx prepend SUBST
19043 @c  LocalWords:  evindex automake Gettext autopoint gettext symlink libtoolize
19044 @c  LocalWords:  defmac INIT tarname ovindex cvindex BUGREPORT PREREQ asis PROG
19045 @c  LocalWords:  SRCDIR srcdir globbing afterwards cmds foos fooo foooo init cd
19046 @c  LocalWords:  builddir timestamp src Imakefile chmod defvar CFLAGS CPPFLAGS
19047 @c  LocalWords:  CXXFLAGS DEFS DHAVE defvarx FCFLAGS FFLAGS LDFLAGS bindir GCC
19048 @c  LocalWords:  datadir datarootdir docdir dvidir htmldir libdir ifnothtml kbd
19049 @c  LocalWords:  includedir infodir libexecdir localedir localstatedir mandir
19050 @c  LocalWords:  oldincludedir pdfdir PDF psdir PostScript sbindir sysconfdir
19051 @c  LocalWords:  sharedstatedir DDATADIR sed tmp pkgdatadir VPATH conf unistd
19052 @c  LocalWords:  undef endif builtin FUNCS ifndef STACKSEG getb GETB YMP fubar
19053 @c  LocalWords:  PRE dest SUBDIRS subdirs fi struct STDC stdlib stddef INTTYPES
19054 @c  LocalWords:  inttypes STDINT stdint AWK AIX Solaris NeXT env EGREP FGREP yy
19055 @c  LocalWords:  LEXLIB YYTEXT lfl nonportable Automake's LN RANLIB byacc INETD
19056 @c  LocalWords:  inetd prog PROGS progs ranlib lmp lXt lX nsl gethostbyname UX
19057 @c  LocalWords:  NextStep isinf isnan glibc IRIX sunmath lm lsunmath pre sizeof
19058 @c  LocalWords:  ld inline malloc putenv setenv FreeBSD realloc SunOS MinGW
19059 @c  LocalWords:  snprintf vsnprintf sprintf vsprintf sscanf gcc strerror ifdef
19060 @c  LocalWords:  strnlen sysconf PAGESIZE unsetenv va fallback memcpy dst FUNC
19061 @c  LocalWords:  PowerPC GNUC libPW pragma Olibcalls CHOWN chown CLOSEDIR VFORK
19062 @c  LocalWords:  closedir FNMATCH fnmatch vfork FSEEKO LARGEFILE fseeko SVR sc
19063 @c  LocalWords:  largefile GETGROUPS getgroups GETLOADAVG DGUX UMAX NLIST KMEM
19064 @c  LocalWords:  GETLODAVG SETGID getloadavg nlist GETMNTENT irix
19065 @c  LocalWords:  getmntent UnixWare GETPGRP getpgid getpgrp Posix's pid LSTAT
19066 @c  LocalWords:  lstat rpl MEMCMP memcmp OpenStep MBRTOWC mbrtowc MKTIME mktime
19067 @c  LocalWords:  localtime MMAP mmap OBSTACK obstack obstacks ARGTYPES timeval
19068 @c  LocalWords:  SETPGRP setpgrp defmacx Hurd SETVBUF setvbuf STRCOLL strcoll
19069 @c  LocalWords:  STRTOD strtod DECL STRFTIME strftime SCO UTIME utime VPRINTF
19070 @c  LocalWords:  DOPRNT vprintf doprnt sp unfixable LIBSOURCE LIBSOURCES Eggert
19071 @c  LocalWords:  linux netinet ia Tru XFree DIRENT NDIR dirent ndir multitable
19072 @c  LocalWords:  NAMLEN strlen namlen MKDEV SYSMACROS makedev RESOLV resolv DNS
19073 @c  LocalWords:  inet structs NAMESER arpa NETDB netdb UTekV UTS autom GCC's kB
19074 @c  LocalWords:  STDBOOL BOOL stdbool conformant cplusplus bool Bool stdarg tm
19075 @c  LocalWords:  ctype strchr strrchr rindex bcopy memmove memchr WEXITSTATUS
19076 @c  LocalWords:  WIFEXITED TIOCGWINSZ GWINSZ termios preprocess preprocessable
19077 @c  LocalWords:  DECLS strdup calloc BLKSIZE blksize RDEV rdev TZNAME tzname pw
19078 @c  LocalWords:  passwd gecos pwd MBSTATE mbstate wchar RETSIGTYPE hup UID uid
19079 @c  LocalWords:  gid ptrdiff uintmax EXEEXT OBJEXT Ae Onolimit conftest AXP str
19080 @c  LocalWords:  ALIGNOF WERROR Werror cpp HP's WorkShop egcs un fied stdc CXX
19081 @c  LocalWords:  varargs BIGENDIAN Endianness SPARC endianness grep'ed CONST FC
19082 @c  LocalWords:  const STRINGIZE stringizing PARAMS unprotoize protos KCC cxx
19083 @c  LocalWords:  xlC aCC CXXCPP FREEFORM xlf FLIBS FCLIBS ish SRCEXT XTRA LFS
19084 @c  LocalWords:  ISC lcposix MINIX Minix conditionalized inlines hw dD confdefs
19085 @c  LocalWords:  fputs stdout PREPROC ar UFS HFS QNX realtime fstype STATVFS se
19086 @c  LocalWords:  statvfs STATFS statfs func machfile hdr lelf raboof DEFUN GTK
19087 @c  LocalWords:  GTKMM Grmph ified ine defn baz EOF qar Ahhh changecom algol io
19088 @c  LocalWords:  changeword quadrigraphs quadrigraph dnl SGI atoi overquoting
19089 @c  LocalWords:  Aas Wcross sep args namespace undefine bpatsubst popdef dquote
19090 @c  LocalWords:  bregexp Overquote overquotation meisch maisch meische maische
19091 @c  LocalWords:  miscian DIRNAME dirname MKDIR CATFILE XMKMF TRAVOLTA celsius
19092 @c  LocalWords:  EMX emxos Emacsen Korn DYNIX subshell posix Ksh ksh Pdksh Zsh
19093 @c  LocalWords:  pdksh zsh Allbery Lipe Kubota UWS zorglub stderr eval esac lfn
19094 @c  LocalWords:  drivespec Posixy DJGPP doschk prettybird LPT pfew Zsh's yu yaa
19095 @c  LocalWords:  yM uM aM firebird IP subdir misparses ok Unpatched abc bc zA
19096 @c  LocalWords:  CDPATH DUALCASE LINENO prepass Subshells lineno NULLCMD cmp wc
19097 @c  LocalWords:  MAILPATH scanset arg NetBSD Almquist printf expr cp
19098 @c  LocalWords:  Oliva awk Aaaaarg cmd regex xfoo GNV OpenVMS VM
19099 @c  LocalWords:  sparc Proulx SysV nbar nfoo maxdepth acdilrtu TWG mc
19100 @c  LocalWords:  mkdir exe uname OpenBSD Fileutils mktemp umask TMPDIR guid os
19101 @c  LocalWords:  fooXXXXXX Unicos parenthesization utimes hpux hppa unescaped
19102 @c  LocalWords:  pmake DOS's gmake ifoo DESTDIR autoconfiscated pc coff mips gg
19103 @c  LocalWords:  dec ultrix cpu wildcards rpcc rdtsc powerpc readline
19104 @c  LocalWords:  withval vxworks gless localcache usr LOFF loff CYGWIN Cygwin
19105 @c  LocalWords:  cygwin SIGLIST siglist SYSNDIR SYSDIR ptx lseq rusage elif MSC
19106 @c  LocalWords:  lfoo POUNDBANG lsun NIS getpwnam SYSCALLS RSH INTL lintl aix
19107 @c  LocalWords:  intl lx ldir syslog bsd EPI toolchain netbsd objext de KNR nn
19108 @c  LocalWords:  fication LTLIBOBJS Wdiff TESTDIR atconfig atlocal akim XFAIL
19109 @c  LocalWords:  ChangeLog prepended errexit smallexample TESTSUITEFLAGS GPL er
19110 @c  LocalWords:  installcheck autotest indir Pixley Bothner Eichin Kerberos adl
19111 @c  LocalWords:  DISTCLEANFILES preprocessor's fileutils Stallman Murphey Stenn
19112 @c  LocalWords:  Manfredi Autoconfig TCL FSP david zuhn Blandy MACRODIR Raeburn
19113 @c  LocalWords:  autoconfiscate Savoye Haertel Avera Meyering fdl appendixsec
19114 @c  LocalWords:  printindex american LIBOBJDIR LibdirTest ERLCFLAGS OBJCFLAGS
19115 @c  LocalWords:  VER Gnulib online xyes strcpy TYPEOF typeof OBJC objcc objc ln
19116 @c  LocalWords:  GOBJC OBJCCPP OTP ERLC erl valloc decr dumpdef errprint incr
19117 @c  LocalWords:  esyscmd len maketemp pushdef substr syscmd sysval translit txt
19118 @c  LocalWords:  sinclude foreach myvar tolower toupper uniq BASENAME STDIN
19119 @c  LocalWords:  Dynix descrips basename aname cname macroexpands xno xcheck
19120 @c  LocalWords:  LIBREADLINE lreadline lncurses libreadline
19122 @c Local Variables:
19123 @c fill-column: 72
19124 @c ispell-local-dictionary: "american"
19125 @c End: